Update to Polar

{
  "description": "Guide for testing Polar payment integrations using the sandbox environment. Use this skill when: (1) Setting up the Polar sandbox for development; (2) Testing checkout flows without real payments; (3) Using Stripe test cards with Polar; (4) Writing integration tests for payment flows; (5) Testing webhooks locally with the Polar CLI (`polar webhook listen`, `polar webhook trigger`) and generating webhook fixtures; (6) Mocking Polar in unit tests; (7) Setting up CI/CD pipelines with Polar sandbox; (8) Debugging payment issues in sandbox.\n",
  "included_files": [],
  "name": "polar-testing",
  "skill_md_contents": "---\nname: polar-testing\ndescription: |\n  Guide for testing Polar payment integrations using the sandbox environment. Use this skill when: (1) Setting up the Polar sandbox for development; (2) Testing checkout flows without real payments; (3) Using Stripe test cards with Polar; (4) Writing integration tests for payment flows; (5) Testing webhooks locally with the Polar CLI (`polar webhook listen`, `polar webhook trigger`) and generating webhook fixtures; (6) Mocking Polar in unit tests; (7) Setting up CI/CD pipelines with Polar sandbox; (8) Debugging payment issues in sandbox.\n---\n\n# Polar Testing Guide\n\nTest Polar integrations safely using the sandbox environment - a fully isolated server where you can experiment without affecting production data or processing real payments.\n\n## Sandbox Environment\n\n### Access\n\n- **Dashboard**: https://sandbox.polar.sh\n- **API**: https://sandbox-api.polar.sh/v1\n\nThe sandbox is completely isolated from production. You need separate:\n- User account\n- Organization\n- Access tokens\n- Webhook endpoints\n\n### Setup Steps\n\n1. Go to https://sandbox.polar.sh/start\n2. Create a new account (or use \"Go to sandbox\" from org switcher)\n3. Create a test organization\n4. Generate an access token in Settings → Access Tokens, or with `polar auth token` once the CLI is signed in to the sandbox (see \"Install and sign in\" below)\n\n### SDK Configuration\n\nSet up the client as in `polar-integration` (\"Setup\") and pass `environment: \"sandbox\"`:\n\n```typescript\nimport { createPolar } from \"@polar-sh/sdk/2026-10\";\n\nconst polar = createPolar({\n  accessToken: process.env.POLAR_ACCESS_TOKEN!,\n  environment: \"sandbox\",\n});\n```\n\n```python\nimport os\n\nfrom polar.v2026_10 import Polar\n\npolar = Polar(os.environ[\"POLAR_ACCESS_TOKEN\"], environment=\"sandbox\")\n```\n\n### Sandbox Limitations\n\n- No real money is processed, and data is isolated from production\n- Customer-facing emails (receipts, renewal reminders) are only delivered to members of your organization; `you+test@example.com` aliases are accepted\n- The API allows 100 requests per minute, against 500 in production, which matters for large integration suites\n\n## Test Cards\n\nPolar uses Stripe for payment processing, so any of [Stripe's test cards](https://docs.stripe.com/testing#cards) work. Use a future expiry date and any CVC:\n\n| Card Number | Behavior |\n|-------------|----------|\n| 4242 4242 4242 4242 | Successful payment |\n| 4000 0000 0000 0002 | Generic decline |\n| 4000 0000 0000 9995 | Insufficient funds |\n| 4000 0027 6000 3184 | Requires 3D Secure authentication |\n\n## Local Webhook Testing\n\nUse the Polar CLI. It forwards your organization's webhook events straight to your local server: no tunnel, no public URL, and no webhook endpoint in the dashboard.\n\n### Install and sign in\n\n```bash\nnpm install -g @polar-sh/cli\n\npolar auth login --sandbox\n```\n\nFor other install methods, see the [CLI docs](https://polar.sh/docs/integrate/cli/introduction).\n\n`polar auth login` opens a browser, so ask the user to run it. Check the result with `polar auth whoami --json`: `environments` lists the signed-in environments and `organization` is the active one.\n\nWhere no browser is available (CI, remote machines, cloud agents), an organization access token replaces `auth login`:\n\n```bash\nexport POLAR_ACCESS_TOKEN=polar_oat_...   # scopes: webhooks:read, webhooks:write, organizations:read\nexport POLAR_ENVIRONMENT=sandbox\n```\n\nIf `POLAR_ACCESS_TOKEN` is already exported in the shell, for example from the app's `.env`, the CLI uses it instead of the login.\n\n### Forward events to your app\n\n```bash\npolar webhook listen 3000/api/polar/webhook\n```\n\n`listen` takes a port, a `port/path`, or a full URL. It runs until stopped, so start it in its own terminal or as a background process and keep it running while you test. It forwards every webhook event for the organization, including the ones real sandbox activity produces, such as completing a test checkout. If the account has several organizations, pick one with `--org <id>` or `polar auth org`.\n\n### Set the webhook secret\n\n`listen` signs forwarded events with a local secret, not a dashboard endpoint's secret. Write it to `.env` without printing it:\n\n```bash\nsecret=$(polar webhook listen --print-secret) && echo \"POLAR_WEBHOOK_SECRET=$secret\" >> .env\n```\n\nIf `.env` already has a `POLAR_WEBHOOK_SECRET` line, replace it instead of appending, then restart the dev server. Deployed environments use the secret of their dashboard webhook endpoint.\n\n### Send test events\n\n```bash\npolar webhook trigger order.paid\n```\n\n`trigger` sends a sample event through the running `listen`. When your handler doesn't accept it (a non-2xx response, a connection error, or a redirect), it prints the handler's response body and exits with status 1. Read that output, fix the handler, and run the same command again until it exits with 0.\n\nA redirect usually means auth middleware is intercepting the webhook route. Exclude the route from it: Polar never follows redirects when delivering webhooks.\n\n```bash\npolar webhook trigger --list --json                     # every event you can send\npolar webhook trigger order.paid --override data.customer.email=jane@example.com\npolar webhook trigger order.paid --seed 7               # the same IDs on every run\n```\n\n`--override` takes `path=value` and can be repeated. The API rejects paths that don't exist in the payload.\n\n## Integration Testing\n\n### Test Checkout Flow\n\nUse an organization access token with the `products:write` and `checkouts:write` scopes. Organization tokens already imply the organization, so don't pass `organization_id`.\n\n```typescript\nimport { describe, it, expect, beforeAll } from \"vitest\";\nimport { createPolar } from \"@polar-sh/sdk/2026-10\";\n\nconst polar = createPolar({\n  accessToken: process.env.POLAR_ACCESS_TOKEN!,\n  environment: \"sandbox\",\n});\n\ndescribe(\"Polar Checkout\", () => {\n  let testProductId: string;\n\n  beforeAll(async () => {\n    const product = await polar.products.create({\n      name: \"Test Product\",\n      prices: [{ amount_type: \"fixed\", price_amount: 1000, price_currency: \"usd\" }],\n    });\n    testProductId = product.id;\n  });\n\n  it(\"creates a checkout session\", async () => {\n    const checkout = await polar.checkouts.create({\n      products: [testProductId],\n      success_url: \"http://localhost:3000/success\",\n      customer_email: \"test@example.com\",\n    });\n\n    expect(checkout.status).toBe(\"open\");\n    expect(checkout.url).toContain(\"sandbox\");\n  });\n\n  it(\"retrieves a checkout\", async () => {\n    const checkout = await polar.checkouts.create({\n      products: [testProductId],\n      success_url: \"http://localhost:3000/success\",\n    });\n\n    const retrieved = await polar.checkouts.get(checkout.id);\n    expect(retrieved.id).toBe(checkout.id);\n  });\n});\n```\n\n### Test Webhook Handler\n\nGenerate fixtures from real payloads instead of writing them by hand. `--dry-run` prints the payload without sending it, so `listen` doesn't need to be running:\n\n```bash\nmkdir -p test/fixtures\npolar webhook trigger order.paid --dry-run --json --seed 1 > test/fixtures/order.paid.json\npolar webhook trigger subscription.created --dry-run --json --seed 1 > test/fixtures/subscription.created.json\n```\n\nSign them the way `polar webhook listen` does ([Standard Webhooks](https://www.standardwebhooks.com/)): an HMAC-SHA256 of `id.timestamp.body`, base64-encoded and keyed with the secret string. This test calls the webhook route from `polar-integration` Recipe 3 directly:\n\n```typescript\nimport { createHmac } from \"node:crypto\";\nimport { readFile } from \"node:fs/promises\";\nimport { beforeAll, describe, expect, it, vi } from \"vitest\";\n\nconst secret = \"test_webhook_secret\";\nlet POST: (request: Request) => Promise<Response>;\n\nbeforeAll(async () => {\n  vi.stubEnv(\"POLAR_WEBHOOK_SECRET\", secret);\n  ({ POST } = await import(\"../app/api/polar/webhook/route\"));\n});\n\nconst sign = (id: string, timestamp: number, body: string) =>\n  `v1,${createHmac(\"sha256\", secret).update(`${id}.${timestamp}.${body}`).digest(\"base64\")}`;\n\nconst webhookRequest = (body: string, signature?: string) => {\n  const id = \"msg_test\";\n  const timestamp = Math.floor(Date.now() / 1000);\n  return new Request(\"http://localhost/api/polar/webhook\", {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      \"webhook-id\": id,\n      \"webhook-timestamp\": String(timestamp),\n      \"webhook-signature\": signature ?? sign(id, timestamp, body),\n    },\n    body,\n  });\n};\n\ndescribe(\"Polar webhook handler\", () => {\n  it(\"accepts a signed order.paid event\", async () => {\n    const body = await readFile(\"test/fixtures/order.paid.json\", \"utf8\");\n    const response = await POST(webhookRequest(body));\n    expect(response.status).toBe(202);\n  });\n\n  it(\"rejects an invalid signature\", async () => {\n    const body = await readFile(\"test/fixtures/order.paid.json\", \"utf8\");\n    const response = await POST(webhookRequest(body, \"v1,invalid\"));\n    expect(response.status).toBe(403);\n  });\n});\n```\n\n### Test License Key Validation\n\nValidation needs a token with `license_keys:write`. A valid key returns `status: \"granted\"`; an unknown key throws `ResourceNotFound`:\n\n```typescript\nimport { describe, it, expect } from \"vitest\";\nimport { createPolar, errors } from \"@polar-sh/sdk/2026-10\";\n\nconst polar = createPolar({\n  accessToken: process.env.POLAR_ACCESS_TOKEN!,\n  environment: \"sandbox\",\n});\nconst organization_id = process.env.POLAR_ORG_ID!;\n\ndescribe(\"License keys\", () => {\n  it(\"validates a granted key\", async () => {\n    const result = await polar.licenseKeys.validate({ key: process.env.TEST_LICENSE_KEY!, organization_id });\n    expect(result.status).toBe(\"granted\");\n  });\n\n  it(\"rejects an unknown key\", async () => {\n    await expect(\n      polar.licenseKeys.validate({ key: \"INVALID-KEY\", organization_id }),\n    ).rejects.toBeInstanceOf(errors.ResourceNotFound);\n  });\n});\n```\n\n## Mocking Polar in Unit Tests\n\n### Mock SDK\n\nMock `createPolar` and keep the real `webhooks` and `errors` exports. Responses use the same `snake_case` fields as the API:\n\n```typescript\nimport { vi } from \"vitest\";\n\nvi.mock(\"@polar-sh/sdk/2026-10\", async (importOriginal) => ({\n  ...(await importOriginal<typeof import(\"@polar-sh/sdk/2026-10\")>()),\n  createPolar: () => ({\n    checkouts: {\n      create: vi.fn().mockResolvedValue({\n        id: \"checkout_mock\",\n        url: \"https://sandbox.polar.sh/checkout/mock\",\n        status: \"open\",\n      }),\n      get: vi.fn().mockResolvedValue({ id: \"checkout_mock\", status: \"succeeded\" }),\n    },\n    customers: {\n      getStateExternal: vi.fn().mockResolvedValue({\n        active_subscriptions: [{ id: \"sub_mock\", status: \"active\", product_id: \"prod_mock\" }],\n        granted_benefits: [],\n        active_meters: [],\n      }),\n    },\n    subscriptions: {\n      revoke: vi.fn(),\n      update: vi.fn(),\n    },\n  }),\n}));\n```\n\n### Mock Webhook Payloads\n\nLoad the fixtures generated with `polar webhook trigger <event> --dry-run --json` (see Test Webhook Handler). Hand-written payloads drift from the real shape, and `validateEvent` only checks the signature and event type, so the drift goes unnoticed.\n\n```typescript\nimport orderPaid from \"./fixtures/order.paid.json\";\nimport subscriptionCreated from \"./fixtures/subscription.created.json\";\n```\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Test Polar Integration\n\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n\n    env:\n      POLAR_ACCESS_TOKEN: ${{ secrets.POLAR_SANDBOX_TOKEN }}\n      POLAR_ORG_ID: ${{ secrets.POLAR_SANDBOX_ORG_ID }}\n\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"22\"\n          cache: \"npm\"\n\n      - run: npm ci\n\n      - name: Run unit tests\n        run: npm run test:unit\n\n      - name: Run integration tests\n        run: npm run test:integration\n```\n\nIf CI also runs the Polar CLI, add `POLAR_ENVIRONMENT: sandbox`.\n\n### Environment Setup\n\nCreate sandbox credentials specifically for CI:\n\n1. Create a dedicated sandbox organization for CI\n2. Create an organization access token for it with only the scopes the tests need (`polar auth token --scope products:write --scope checkouts:write` opens the token page with them preselected)\n3. Commit the webhook fixtures; handler tests sign them with a test secret and need no webhook endpoint\n4. Store the token and organization ID in GitHub Secrets\n\n## Debugging Tips\n\n### Check Webhook Delivery\n\nLocally, `polar webhook listen` logs every forwarded event with your handler's status, and `polar webhook trigger` prints the handler's response body when it fails.\n\nFor a deployed endpoint:\n\n1. Go to sandbox.polar.sh → Settings → Webhooks\n2. Click on your endpoint\n3. View delivery history and payloads\n4. Check response codes and errors\n\n### Common Issues\n\n**Webhook signature mismatch**\n- Ensure you're using the sandbox webhook secret\n- Locally, use the secret from `polar webhook listen --print-secret` and restart the dev server after changing `.env`\n- Check that the raw body is being passed (not parsed JSON)\n- Verify timestamp is within tolerance (5 minutes)\n\n**Checkout not completing**\n- Use test cards, not real cards\n- Check browser console for errors\n- Verify `success_url` is correct\n\n**API returns 401**\n- Verify you're using a sandbox token with the sandbox API\n- Check the token hasn't expired or been revoked\n\n**API returns 403**\n- The token is missing a scope the endpoint needs\n\n### Inspect API Errors\n\nThe SDK throws typed errors with the HTTP status and response body:\n\n```typescript\nimport { PolarClientError } from \"@polar-sh/sdk\";\n\ntry {\n  await polar.checkouts.create({ products: [productId], success_url: \"http://localhost:3000/success\" });\n} catch (error) {\n  if (error instanceof PolarClientError) console.error(error.statusCode, error.error);\n  throw error;\n}\n```\n\n## Test Checklist\n\nBefore going to production:\n\n- [ ] Checkout flow completes successfully\n- [ ] Webhooks received and processed\n- [ ] Subscription lifecycle works (create, cancel, revoke)\n- [ ] Benefits granted and revoked correctly\n- [ ] License key validation works\n- [ ] Error handling for declined payments\n- [ ] Customer portal accessible\n- [ ] Refund flow tested\n"
}