feat(integrations): push Polar order, subscription, and refund events by webhook

Aperta
  • Qualcosa non va?
#429 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
15/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
nextjs, playwright, react, typescript
Ambito
api, backend

Direzione di ricerca

Start with step 1: read docs/providers/polar.md ("Permissions") and Polar's webhook API docs to pin down the create endpoint, signature scheme and headers, and the delivery id to deduplicate on, then record findings on the issue. Code lives in src/lib/adapters/polar/; the mapping of order.paid and friends onto existing event types is what the timeline consumes, so read that event pipeline before writing handlers. It is blocked on #28 (ingest contract) and #426 (setup panel), so confirm those have landed first. Done means both setup paths work against the simulated Polar provider, deliveries are verified, deduplicated, and logged without bodies, and unit plus Playwright tests pass under npm test.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

area: integrations blocked enhancement impact: medium priority: P1 size: S

Context

Decision on #424 (2026-11-14): Polar offers automatic setup as an opt-in and setup by hand. Polar has no read-only scope that can create a webhook: automatic setup needs webhooks:write, while the adapter holds read scopes only (docs/providers/polar.md, "Permissions"). The panel in #426 warns about this before asking, and points users who want DevMacro to stay read-only to setup by hand.

Item Value
Create Webhook endpoints through the API with webhooks:write, or by hand in Polar's webhook settings
Events for the timeline order.paid, order.refunded, subscription.created, subscription.canceled, subscription.revoked, refund.created, mapped to the adapter's polar.order.paid, polar.subscription.started, polar.subscription.canceled, polar.refund.succeeded
Not pushed Revenue, fees, and recurring revenue from Polar's analytics. Polling stays

Plan

  1. Confirm from Polar's docs, before any code: the create endpoint, its request and response (whether it returns the signing secret), the signature scheme and headers, and the delivery id to deduplicate on. Record them on this issue and in the provider page.
  2. Declare Polar's webhook in the #28 contract: automatic setup needs webhooks:write, steps for setup by hand.
  3. Automatic: after the opt-in consent for webhooks:write, create the endpoint with DevMacro's URL and the events above, store its secret encrypted, delete it on disconnect.
  4. By hand: show the URL and the steps, and a field for Polar's signing secret if Polar generates it.
  5. Verify signatures, deduplicate, map deliveries to the connection by the per-connection URL. Deliveries become the existing event types, so polling and webhooks show one entry.
  6. Docs: docs/providers/polar.md ("Permissions", "Permission risks" for webhooks:write, "Webhooks").

Acceptance criteria

  • Step 1 findings recorded with links to Polar's docs.
  • The opt-in write access warning from #426 shows before Polar's consent screen.
  • Automatic setup creates the endpoint, and a paid order reaches the timeline within a minute.
  • Setup by hand works without requesting webhooks:write.
  • Disconnect deletes an automatic endpoint.
  • Unsigned, wrongly signed, stale, or repeated deliveries are rejected or ignored, and logged without their body.
  • Unit tests on recorded, sanitized payloads from Polar's documented samples. No live calls in CI.
  • Playwright e2e: both setup paths for the simulated Polar provider.

Files and areas

  • src/lib/adapters/polar/, docs/providers/polar.md, docs/operations/oauth-apps.md.
  • Non-goals: other write scopes, pushing analytics figures.

Verification

  • npm run lint, npm run typecheck, npm test
  • Playwright spec for both setup paths.

Depends on

  • #28 Ingest provider webhooks
  • #426 Webhook setup panel

Branch: <issue-number>-polar-webhooks
Closes with a Closes #<issue-number> footer on the commit or pull request.

Model: anthropic/claude-opus-5-5 | Reasoning effort: unknown

Lingua principale
TypeScript
Stelle
1
Fork
1
Merge medio
6h 56m
PR unite (30g)
136

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di eddiejaoude/StackDash

Tutte le issue di eddiejaoude/StackDash

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.