Release 2023/10/14

.env.dist

@@ -1,7 +1,18 @@
 FAIRPOST_FEED_PATH=feed
 FAIRPOST_FEED_INTERVAL=6 #days
-FAIRPOST_FEED_PLATFORMS=asyoutube,asfacebook,aslinkedin,asinstagram,astiktok,asreddit,astwitter
 
+FAIRPOST_FEED_PLATFORMS=
+# FAIRPOST_FEED_PLATFORMS=facebook,asyoutube,asfacebook,aslinkedin,asinstagram,astiktok,asreddit,astwitter
+
+# AYRSHARE
 FAIRPOST_AYRSHARE_API_KEY=xxxx
 
-FAIRPOST_REDDIT_SUBREDDIT=generative
+FAIRPOST_REDDIT_SUBREDDIT=generative
+
+
+# facebook
+# FAIRPOST_FACEBOOK_APP_ID=xxx
+# FAIRPOST_FACEBOOK_APP_SECRET=xxx
+# FAIRPOST_FACEBOOK_PAGE_ID=xxx 
+# FAIRPOST_FACEBOOK_PAGE_ACCESS_TOKEN=xxx
+# FAIRPOST_FACEBOOK_PUBLISH_POSTS=true

.eslintignore

@@ -0,0 +1,3 @@
+node_modules
+feed
+dist

.eslintrc

@@ -0,0 +1,17 @@
+{
+    "root": true,
+    "parser": "@typescript-eslint/parser",
+    "plugins": [
+      "@typescript-eslint",
+      "prettier"
+    ],
+    "extends": [
+      "eslint:recommended",
+      "plugin:@typescript-eslint/eslint-recommended",
+      "plugin:@typescript-eslint/recommended",
+      "prettier"
+    ],
+    "rules": {
+      "prettier/prettier": 2 // Means error
+    }
+}

.github/workflows/qa.yml

@@ -0,0 +1,29 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: QA
+
+on:
+  pull_request:
+    branches: [ "develop", "master" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x, 16.x, 18.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build
+    - run: npm test

.gitignore

@@ -1,6 +1,8 @@
 # Feed
 feed
 .DS_Store
+build
+*.log
 
 # Logs
 logs

.prettierrc

@@ -0,0 +1,3 @@
+{
+
+}

README.md

@@ -1,24 +1,34 @@
 # Fairpost
 
-
-
-Ayrshare feed helps you manage your ayrshare
-feed from the command line.
+Fairpost helps you manage your social
+feeds from the command line, using Node.
 
 Each post is a folder, containing at least one 
 text file (the post body) and optionally images
 or a video. 
 
+To smoothly maintain your feed, you can run 
+fairpost every day. Fairpost will prepare and 
+schedule new content to be published on all your 
+platforms on a regular basis, while
+you can just focus on creating new content.
+
+Or, if you prefer, you can manually publish one
+specific post on all supported and enabled 
+platforms at once.
+
 Edit the .env file to manage the platforms
-you want to support, amongst others. 
+you want to support, the interval for new posts,
+etcetera. For each platform, you'll have to 
+register the app to post on your behalf.
 
 ## Setting up 
 ```
 # install
 npm install
 
 # compile typescript code
-tsc
+npm run build
 
 # copy and edit config file
 cp .env.dist .env && nano .env
@@ -32,7 +42,7 @@ cp .env.dist .env && nano .env
 fairpost.js prepare-posts
 ```
 Folders need to be `prepared` (iow turned into posts)
-before they can be posted to a platform. 
+before they can be published to a platform. 
 Each platform, as defined in src/platforms, will 
 handle the folder contents by itself. It may
 decide to modify the media (eg, scale images) 
@@ -46,7 +56,13 @@ folder.
 ```
 fairpost.js schedule-next-post
 ```
-The next post can then be `scheduled`. For each platform this just updates the json file in one post to set the status to scheduled, and set the schedule date. By default the date will be `FAIRPOST_FEED_INTERVAL` days after the last post for that platform, or `now`, whichever is latest.
+The next post can then be `scheduled`. For each platform,
+if there is not already a scheduled post, this will update
+the json file in one post to set the status to scheduled, 
+and set the schedule date. 
+By default the date will be `FAIRPOST_FEED_INTERVAL` days 
+after the last post for that platform, or `now`, whichever 
+is latest.
 
 ## Publish
 ```
@@ -55,32 +71,49 @@ fairpost.js publish-due-posts
 This will publish any scheduled posts that are past their due date.
 
 
-## Arguments
+## Other commands
 
-Each of these commands (and others) accept `--arguments`
+Other commands accept `--arguments`
 that may help you, for example, to immediately publish
 a certain post to a certain platform if you like.
 
 But more commonly, you would call this script
-every day and just add posts to the feed folder as 
-time goes by. 
-The script will then automatically prepare these posts,
+every day. 
+The script will then automatically prepare the posts,
 schedule the next post using a certain interval, 
 publish any post when it is due, and schedule the 
-next post automatically.
+next post automatically. All you have to do is 
+add folders with content.
 
 
 
 ## Cli
 
 ```
-fairpost.js help 
-fairpost.js get-feed
+# basic commands:
+fairpost.js help
+fairpost.js get-feed [--config=xxx]
+fairpost.js test-platform --platform=xxx
+fairpost.js test-platforms [--platforms=xxx,xxx]
+fairpost.js get-platform --platform=xxx
+fairpost.js get-platforms [--platforms=xxx,xxx]
+fairpost.js get-folder --folder=xxx
 fairpost.js get-folders [--folders=xxx,xxx]
-fairpost.js prepare-posts [--platforms=xxx,xxx] [--folders=xxx,xxx]
-fairpost.js get-posts [--status=xxx] [--platforms=xxx,xxx] [--folders=xxx,xxx]
-fairpost.js schedule-next-post [--date=xxxx-xx-xx] [--platforms=xxx,xxx] [--folders=xxx,xxx]
-fairpost.js publish-due-posts [--platforms=xxx,xxx] [--folders=xxx,xxx] [--dry-run]
+fairpost.js get-post --folder=xxx --platform=xxx
+fairpost.js get-posts [--status=xxx] [--folders=xxx,xxx] [--platforms=xxx,xxx] 
+fairpost.js prepare-post --folder=xxx --platform=xxx
+fairpost.js schedule-post --folder=xxx --platform=xxx --date=xxxx-xx-xx 
+fairpost.js schedule-posts [--folders=xxx,xxx] [--platforms=xxx,xxx] --date=xxxx-xx-xx
+fairpost.js publish-post --folders=xxx --platforms=xxx [--dry-run]
+fairpost.js publish-posts [--folders=xxx,xxx] [--platforms=xxx,xxx]
+
+# feed planning:
+fairpost.js prepare-posts [--folders=xxx,xxx] [--platforms=xxx,xxx]
+fairpost.js schedule-next-post [--date=xxxx-xx-xx] [--folders=xxx,xxx] [--platforms=xxx,xxx] 
+fairpost.js publish-due-posts [--folders=xxx,xxx] [--platforms=xxx,xxx] [--dry-run]
+
+# platform tools:
+fairpost.js facebook-get-page-token --app-user-id=xxx --user-token=xxx
 ```
 
 ### Common arguments 
@@ -102,7 +135,7 @@ extending `src/classes/Platform`. You want to override at least the
 method `preparePost(folder: Folder)` and 
 `publishPost(post: Post, dryrun:boolean = false)`.
 
-Then add a slug for your platform to `src/platforms/index.js` and
+Then add a platformId for your platform to `src/platforms/index.js` and
 enable your platform in your `.env`.
 
 

docs/Facebook.md

@@ -0,0 +1,99 @@
+# Platform: Facebook
+
+The `facebook` platform manage a facebook **page* (not your feed)
+using the plain graph api - no extensions installed.
+
+## Setting up the Facebook platform
+
+
+### Create a new App in your facebook account
+ - go to https://developers.facebook.com/
+ - create an app that can manage pages 
+ - for instagram, you'll need to attach a business account (...) that is connected to a facebook page
+ - under 'settings', find your app ID 
+   - save this as `FAIRPOST_FACEBOOK_APP_ID` in your .env
+ - under 'settings', find your app secret
+   - save this as `FAIRPOST_FACEBOOK_APP_SECRET` in your .env
+
+### Find the page id of the page you want the app to manage
+  - go to https://business.facebook.com/
+  - find your page (currently under 'settings > business assets')
+  - note the page id 
+    - save this as `FAIRPOST_FACEBOOK_PAGE_ID` in your .env
+
+### Get a (short lived) Page Access Token for the page you want the app to manage
+
+This is good for testing, but you'll have to refresh this token often.
+
+ - go to https://developers.facebook.com/tools/explorer/
+ - select your app 
+ - add permissions
+   - pages_manage_engagement
+   - pages_manage_posts
+   - pages_read_engagement
+   - pages_read_user_engagement
+   - publish_video
+   - business_management
+ - request a (short lived) page access token
+   - save this as `FAIRPOST_FACEBOOK_PAGE_ACCESS_TOKEN` in your .env
+
+### Get a (long lived) Page Access Token for the page you want the app to manage
+
+This token should last forever. It involves get a long-lived user token and then requesting the 'accounts' for your 'app scoped user id'; but this app provides a tool to help you do that: 
+
+ - go to https://developers.facebook.com/tools/explorer/
+ - select your app 
+ - add permissions
+   - pages_manage_engagement
+   - pages_manage_posts
+   - pages_read_engagement
+   - pages_read_user_engagement
+   - publish_video
+   - business_management
+ - request a (short lived) user access token
+ - click 'submit' to submit the default `?me` query
+   - remember the `id` in the response as your id
+ - call `./fairpost.js facebook-get-page-token
+    --app-user-id={your id} --user-token={your token}`
+   - note the token returned 
+   - save this as `FAIRPOST_FACEBOOK_PAGE_ACCESS_TOKEN` in your .env
+
+### Enable and test the facebook platform
+ - Add 'facebook' to your `FAIRPOST_FEED_PLATFORMS` in `.env`
+ - call `./fairpost.js test --platforms=facebook`
+
+# Limitations 
+
+## Images 
+
+From https://developers.facebook.com/docs/graph-api/reference/page/photos/ :
+
+Facebook strips all location metadata before publishing and resizes images to different dimensions to best support rendering in multiple sizes.
+
+
+### Supported Formats
+Facebook supports the following formats:
+ - JPEG
+ - BMP
+ - PNG
+ - GIF
+ - TIFF
+
+### File Size
+
+Files must be 4MB or smaller in size.
+For PNG files, try keep the file size below 1 MB. PNG files larger than 1 MB may appear pixelated after upload.
+
+# Random documentation
+
+https://dev.to/xaypanya/how-to-connect-your-nodejs-server-to-facebook-page-api-1hol
+https://developers.facebook.com/docs/pages/getting-started
+https://developers.facebook.com/docs/pages-api/posts
+https://developers.facebook.com/docs/graph-api/reference/page/photos/
+https://developers.facebook.com/docs/video-api/guides/publishing
+
+large uploads:
+https://developers.facebook.com/docs/graph-api/guides/upload/
+
+https://www.npmjs.com/package/formdata-node
+https://medium.com/deno-the-complete-reference/sending-form-data-using-fetch-in-node-js-8cedd0b2af85