QR-master/docs/automations/social-milestone-worker.md

Social milestone worker

The app detects QR-code scan milestones and stores customer consent. It does not hold X or Meta credentials. The external worker publishes what was approved — per channel, never more.

Consent is bound to a channel

Approving a post on X says nothing about Instagram: different audience, different disclosure about the customer's business. Every channel therefore has its own checkbox in the dialog, its own text, its own handle and its own row in SocialMilestonePost. No row means no consent. A channel is only offered where a publisher is configured — SOCIAL_MILESTONE_CHANNELS (app) must stay in sync with SOCIAL_WORKER_CHANNELS (worker), otherwise approvals pile up in the queue with nobody to publish them.

Test setup (manual SQL only)

1. Apply, in this order, to qrmaster_test: sql/2026-08-13_social_milestones.sql, sql/2026-08-16_social_milestone_retries.sql, sql/2026-08-16_social_milestone_channels.sql.
2. Set distinct CRON_SECRET and INTERNAL_API_SECRET values in .env.test. For an end-to-end test without 1,000 scans, also set SOCIAL_MILESTONE_THRESHOLDS=1 (or 1,2). Do not set this on production. Publishing is immediate after consent by default. Set SOCIAL_MILESTONE_POST_DELAY_HOURS=24 only if a revocation window is desired. Set SOCIAL_MILESTONE_MIN_GAP_HOURS=0 on test, otherwise the second milestone waits a full day behind the first one.
3. Deploy using the documented test compose command. CRON_SECRET is forwarded to the web service by docker-compose.yml.
4. Trigger detection manually:

curl -H "Authorization: Bearer $CRON_SECRET" \
  https://testmodul.qrmaster.net/api/cron/social-milestones

The detector creates records at 1,000 and 10,000 unique scans only. It is safe to call repeatedly because (qrId, kind) is unique. A QR code that is already past several thresholds on first detection only produces the highest one.

Queue contract

curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
  "https://qrmaster.net/api/internal/social-milestones?channel=instagram"

Returns at most one approved post for that channel, claims it, and expects a result report for the returned id:

curl -X PATCH -H "Authorization: Bearer $INTERNAL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"id":"<post-id>","result":"posted","postUrl":"https://..."}' \
  https://qrmaster.net/api/internal/social-milestones

First attempts are spaced by SOCIAL_MILESTONE_MIN_GAP_HOURS (default 24) per channel, so the brand timeline cannot be flooded when several customers consent on the same day. A blocked poll answers {"milestone": null, "reason": "spacing", "nextPostAt": "..."}.

milestone.text is published verbatim — it is the text the customer read before consenting. The image is not part of the payload: the worker downloads it from <QRMASTER_API_BASE>/s/m/<shareToken>/og, the same renderer that serves the popup and the link preview. ?format= takes landscape (1200×630, default), square (1080×1080) or portrait (1080×1350).

Instagram

Publishing runs against the QRMaster.net Business account (see social-accounts-and-jobs.md) in three steps: POST /{ig-user-id}/media → poll status_code until FINISHED → POST /{ig-user-id}/media_publish.

Worth knowing before enabling it:

• JPEG only. The worker flattens the rendered PNG onto white and uploads it through POST /api/social-assets; Meta downloads image_url itself, so it has to be publicly readable on the verified domain. SOCIAL_ASSET_ADMIN_KEY is the existing TIKTOK_ADMIN_KEY.
• No clickable links in captions. The Instagram text therefore ends in hashtags instead of the share URL, and mentions use the customer's Instagram handle, not their X handle.
• 50 posts / 24 h, verifiable via GET /{ig-user-id}/content_publishing_limit.
• Reconciliation is caption-based. Before a repeated attempt the worker compares the caption against the last 25 media items. Two milestones with an identical caption — same QR title, same scan count — would be treated as the same post; the 24 h spacing makes that combination unlikely but not impossible.
• Required environment: SOCIAL_WORKER_CHANNELS=x,instagram, INSTAGRAM_USER_ID, INSTAGRAM_ACCESS_TOKEN, plus SOCIAL_MILESTONE_CHANNELS=x,instagram on the web service so the dialog asks for it in the first place.

Do not configure this worker against testmodul. LinkedIn has no approved brand-posting integration in this project. Customers can self-share on all three: X opens a prefilled intent, LinkedIn gets the text copied, Instagram opens the system share sheet on a phone and falls back to an image download.

Failed posts

A reported failure — and a claim the worker never confirmed — counts as one attempt. The queue re-schedules the post itself after 5, then 10 minutes and only parks it in failed once three attempts are used up. Before posting again the worker reconciles against the account (share token on X, caption on Instagram), so a failure reported after a successful post cannot duplicate it.

The consent dialog opens once per milestone, so a customer who has closed it can no longer see or restart a failed post from there. Settings → Milestone sharing lists every milestone with one line per channel and offers "Try again" (re-queues the approved text unchanged) and "Cancel" (revokes that channel before anything is published).