feat: affitor setup polar + onboard Polar auto-inject (one-command non-Stripe payments)

[sonpiaz]

Why

Mandeck's ship-paid-saas skill ships paid SaaS on Polar (merchant of record — no Stripe) with every sale reported to Affitor via POST /api/v1/track/sale. Until now only Stripe had first-class CLI tooling; for Polar the CLI degraded to printing snippets. This PR gives Polar the same one-command experience — and structurally paves the path for other self-hosted-webhook providers.

What

affitor setup polar (new, cli 0.5.0)

• Creates the webhook endpoint on the advertiser's Polar org (POST /v1/webhooks/endpoints, format: raw, events order.paid + order.refunded) pointing at their app (default https://<domain>/api/polar/webhook, --url to override). --sandbox targets sandbox-api.polar.sh. Token via --token / POLAR_ACCESS_TOKEN / masked prompt (needs webhooks:write scope).
• Persists the signing secret to .affitor/.env (gitignored) + writes POLAR_WEBHOOK_SECRET into the app's .env(.local) (never overwrites a different value).
• Generates the glue route from the recipes registry (Next.js App Router; src/app honored). New-file-only — an existing route is never overwritten.
• Idempotent: re-runs match the endpoint by URL (Polar's list API returns the secret, so it's recovered), PATCH missing events as a union, and early-exit already_connected on a same-URL+env re-run.
• --json agent mode mirrors onboard's contract: no app-source writes; output carries route: {path, source, deps, env}, steps[], next_actions[].

onboard extended (auto-inject beyond Stripe)

• wireServerSale now routes per provider. Polar: detects the webhook route; auto-injects trackSale ONLY into the unambiguous @polar-sh/nextjs Webhooks({ onOrderPaid }) shape (diff + confirm; conservative bail-outs mirror the Stripe transform); raw validateEvent handlers get the exact printed patch; no route at all → points at affitor setup polar. Lemon Squeezy/Paddle keep the degrade-to-print path.

@affitor/recipes 0.2.0

• Contract fix: the Polar sale snippet read raw-JSON snake_case (order.total_amount, order.subscription_id, order.customer_id) — those fields are undefined on the SDK-parsed payloads our handlers target (Webhooks()/validateEvent parse through Zod $inboundSchema → camelCase), silently losing amount + attribution. Now: totalAmount/subscriptionId/customerId, plus clickId carrier (metadata.affitor_click_id ?? metadata.reference_id — Polar propagates a checkout link's ?reference_id= into order metadata, renewals included), customer.externalId fallback, isRecurring: billingReason === 'subscription_cycle' (exact enum; Boolean(subscriptionId) mislabeled first payments).
• New getWebhookRoute(framework, provider): the full self-hosted glue route (Polar × next-app), composed from the SAME sale-body constant so CLI/MCP/docs can't drift. POLAR_WEBHOOK_EVENTS exported.

Stripe bug fix (pre-existing, found during the doc-bug investigation this mission ordered)

• setup stripe registered advertiser webhook endpoints at ${apiUrl}/webhooks/stripe/${program_id} — that route does not exist in the CMS (only POST /api/webhook-distributor/stripe is served; verified in affiliate-cms routes). Every CLI-created endpoint 404'd and events were silently lost. Now points at the real global ingest route. ⚠️ CMS follow-up (out of scope here): the distributor verifies signatures against env secrets only; it should also try the per-program webhook_secret that /v1/cli/stripe-connect already stores in tracking_settings.

Verification

• 133 tests green across the workspace (30 recipes / 94 cli / 9 mcp), tsc clean, build clean.
• E2E against a mock Polar API (create/reuse/PATCH-events paths): --json (no file writes, route in payload), interactive (route + env written), idempotent re-run (already_connected), endpoint-reuse with secret recovery.
• Contract proof: both the generated route AND the onboard-injected route typecheck clean under tsc --strict against the real published @polar-sh/nextjs@0.9.6 + @affitor/sdk@2.1.0 — the camelCase field contract is machine-verified, not assumed.
• Management-API contract verified against live polar.sh/docs + api.polar.sh/openapi.json (2026-07-05); payload parsing verified from polar-js source ($inboundSchema).
• affitor test sale passes against the real pipeline (isolated is_test event, program 430).

Blocked / not done

• No live Polar sandbox run: no Polar sandbox org/token exists on this machine (human signup required). The command is mock-verified + type-proven as above; first real-token run should be npx affitor setup polar --sandbox in a scratch Next app.
• Hosted relay (/webhook-distributor/polar) intentionally out of scope — advertiser self-hosts the route (per mission).
• CMS-side Stripe per-program secret verification (noted above).

Notes

• PR targets main: this repo has no uat branch and no deploy-on-merge; all 23 prior PRs target main (the uat→main flow applies to cms/dashboard/docs).
• Versions: recipes 0.2.0, cli 0.5.0, mcp 0.2.1 (republish against recipes ^0.2.0). npm publish is a separate manual step after merge.
• Docs PR in affitor-docs accompanies this one (setup-polar reference + integrations/polar guide + 3 runtime-verified doc bug fixes).

🤖 Generated with Claude Code

https://claude.ai/code/session_017mS1Kn4D45SX2wVaVmfwUE