PostGuard

PostGuard is a pre-flight check for a Buffer queue. It signs in with Buffer, reads the scheduled posts, and flags the ones that were fine when you queued them and will be broken when they publish.

Next 7 days: 3 dead links, 1 duplicate, 2 missing alt text, 1 paused channel.

It is read-only. There is no pause mutation in the Buffer API, so each finding links to the post’s channel in Buffer instead of editing it.

Demo, no account required

npm install
npm run dev

Open http://localhost:3000 and choose Try the demo queue. Demo mode replays a fixture (Northwind Studio) and does not call Buffer, so it spends none of the shared app quota. On /demo, the example switcher chooses All (the mixed queue) or a single platform: Instagram, TikTok, X, LinkedIn, or Facebook. The choice is ?platform= (tiktok, x, and so on), so a reload and Scan again keep it. Posts that already have a picture or a video show that media on the card. Instagram, TikTok, and Pinterest posts in the demo each have a picture or a poster, except the TikTok post with no video, which shows a “No video attached” box. Other platforms show a picture on most posts. The files live in public/demo (Unsplash photos, saved in the repo). The checks still use the fixture URLs, so a signed or missing file is still flagged.

Connect a real Buffer account

1. In Buffer, open Settings → API and create an app client.
2. Choose a confidential / private client. PostGuard keeps the secret on the server.
3. Permissions: account:read and posts:read. Do not enable write scopes. The app form has no offline_access checkbox; PostGuard still asks for it, and if Buffer does not return a refresh token the session simply lasts one hour.
4. Redirect URI, matched exactly:
   • Local: http://localhost:3000/api/auth/callback
   • Production: https://YOUR_PROJECT.vercel.app/api/auth/callback
5. Privacy policy URL: https://YOUR_PROJECT.vercel.app/privacy (or http://localhost:3000/privacy while developing).
6. Copy .env.example to .env.local and fill in:

Variable	Required	Purpose
BUFFER_CLIENT_ID	For live scans	App client id
BUFFER_CLIENT_SECRET	For a confidential client	Sent on the token and refresh calls. Omit only for a public client.
BUFFER_REDIRECT_URI	Yes, in production	Must match the URI registered above. Defaults to the request origin + /api/auth/callback when unset.
SESSION_SECRET	For live scans	Encrypts the refresh-token cookie. node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
POSTGUARD_WINDOW_DAYS	No	Default window (7). The dashboard can switch to 3 or 14.
APP_URL	No	Public origin. Also the origin of every link in an alert email (see Alerts).

Then npm run dev, and use Connect Buffer. The flow is OAuth 2.0 authorization code with PKCE (S256):

• Authorize: GET https://auth.buffer.com/auth
• Token: POST https://auth.buffer.com/token
• API: POST https://api.buffer.com with Authorization: Bearer

Access tokens last one hour. If the token response includes a refresh token, it is single-use: every refresh stores the new one and drops the old one. Reusing an old refresh token revokes the grant. If the response has no refresh token, PostGuard keeps the access token and, when it expires, shows a reconnect prompt instead of calling the refresh endpoint or crashing. Tokens sit in an AES-256-GCM httpOnly cookie. Sign out deletes it.

Deploy

Vercel is the straightforward host. Hobby is enough for the demo and a light judging load. A live scan of a large queue does HTTP checks and can run long; the route asks for 60 seconds (maxDuration). Hobby plans cap that lower, which is another reason the demo queue is the path to show judges.

1. Push this repo and import it at vercel.com/new. Framework preset: Next.js. Root directory: the repo root.
2. Add the env vars from the table. Set BUFFER_REDIRECT_URI to https://YOUR_PROJECT.vercel.app/api/auth/callback and APP_URL to https://YOUR_PROJECT.vercel.app.
3. Deploy.
4. Register that exact redirect URI, and https://YOUR_PROJECT.vercel.app/privacy, on the Buffer app client.
5. Open the deployment. Confirm the demo queue, then connect a Buffer account and run one scan.

No database is required for the dashboard. (Alerts need Redis, see Alerts.) Scan results are cached in memory for 10 minutes so a reload does not spend the quota again. Use Scan again to bypass the cache.

What a scan does

One scan, on demand:

1. account { organizations }
2. channels for that organization (disconnected, locked, paused, Mastodon maxCharacters, X subscriptionType)
3. posts with status of scheduled, error, and needs_approval, dueAt from 24 hours ago through the window, sorted by dueAt, page size 50, cursor in after / pageInfo.endCursor. Include drafts adds draft and sending, plus one page of status: [draft] with no date filter so an unscheduled draft is visible. sent is never requested.
4. One page of posts with dueAtPresence: absent, using the same status list
5. HEAD, then GET, for the URLs in the copy and on the media. Signed and private-host URLs are classified without a request.

PostStatus in the published schema is draft, error, needs_approval, scheduled, sending, sent.

Paging stops after 12 pages or when the 15-minute RateLimit window has 2 requests left. The meter reads RateLimit and RateLimit-Policy and matches windows by w (900, 86400, 2592000), not by the policy name.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗