@polar-sh/sdk 1.0.0-alpha.15 → 1.0.0-alpha.16

package/.agents/skills/polar-typescript-sdk/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: polar-typescript-sdk
+description: Integrate Polar billing in server-side TypeScript applications using the versioned createPolar and createPolarCore clients. Use when implementing Polar customers and external IDs, checkout or customer portal sessions, customer-state entitlement checks, webhook validation and processing, API error handling, tree-shakable SDK calls, usage-event ingestion and metered billing, or migrating an application from the old Polar TypeScript SDK.
+---
+
+# Polar TypeScript SDK
+
+Use the generated, versioned Polar SDK without inventing methods or parameters.
+
+## Inspect the application first
+
+1. Identify the installed `@polar-sh/sdk` version and preserve the API version already selected by the application.
+2. Inspect generated service signatures, model interfaces, response types, and endpoint-specific errors before writing calls.
+3. Use `createPolar` for the full service client. Use `createPolarCore` with individual service functions when bundle size or tree-shaking matters.
+4. Identify whether the access token is scoped to an organization. Pass `organization_id` when the selected token does not imply one, and confirm the required endpoint scopes.
+5. Keep client, webhook, and environment configuration in trusted server-side code.
+
+## Migrate from the old SDK
+
+Read [Migration from the `<1.0.0` SDK](references/migration-from-v0.md) before changing an application that imports an unversioned `Polar` class or uses camelCase request and response fields. Do not mix old and new client, field-casing, pagination, error, or webhook conventions.
+
+## Configure and reuse the client
+
+Keep production and sandbox access tokens separate. Never expose an organization access token in browser, mobile, or other public client code. Pass `environment: "sandbox"` while testing; omit it or pass `environment: "production"` in production.
+
+```typescript
+import { createPolar } from "@polar-sh/sdk/2026-04";
+
+const accessToken = process.env.POLAR_ACCESS_TOKEN;
+if (!accessToken) {
+  throw new Error("POLAR_ACCESS_TOKEN is required");
+}
+
+const polar = createPolar({
+  accessToken,
+  environment: "sandbox",
+});
+
+const customerState = await polar.customers.getStateExternal("usr_123");
+```
+
+Create the client once for a long-running server and reuse it. The TypeScript client uses `fetch` and does not expose a connection-closing lifecycle.
+
+For tree-shakable individual functions, create a core client and bind only the operations the application uses:
+
+```typescript
+import { createPolarCore } from "@polar-sh/sdk/2026-04";
+import { getStateExternalCustomers } from "@polar-sh/sdk/2026-04/services/customers";
+
+const polarCore = createPolarCore({ accessToken });
+const getCustomerState = getStateExternalCustomers(polarCore);
+const customerState = await getCustomerState("usr_123");
+```
+
+## Follow generated argument and output conventions
+
+- Use camelCase service names and methods such as `benefitGrants`, `getStateExternal`, and `iterList`.
+- Keep request, query, and response field names in API-style `snake_case`, such as `external_customer_id`.
+- Pass path parameters positionally.
+- Pass query parameters as an optional object after path parameters.
+- Pass request bodies as a single typed object.
+- Treat responses as typed plain JavaScript objects.
+- Expect UUID and date-time OpenAPI fields to remain strings.
+- Consume paginated `iter*` methods with `for await`; each additional page performs another API request.
+
+```typescript
+for await (const customer of polar.customers.iterList({
+  sorting: ["email"],
+})) {
+  console.log(customer.id);
+}
+```
+
+## Correlate customers with stable external IDs
+
+Use the application's immutable user or organization identifier as the Polar customer `external_id`. It is unique within a Polar organization. It may be assigned later when initially unset, but it cannot be changed or removed once set.
+
+```typescript
+const customer = await polar.customers.create({
+  external_id: "usr_123",
+  email: "user@example.com",
+});
+const customerState = await polar.customers.getStateExternal("usr_123");
+```
+
+Handle concurrent creation safely. A preflight lookup followed by creation is not atomic; if creation reports an existing email or external ID, fetch and reconcile the existing customer rather than creating a second mapping.
+
+## Create checkout and customer portal sessions
+
+Create checkout sessions on the server and send only the returned URL to the browser. Prefer `external_customer_id` so a completed checkout is reconciled with the application's customer.
+
+```typescript
+const productId = process.env.POLAR_PRODUCT_ID;
+if (!productId) {
+  throw new Error("POLAR_PRODUCT_ID is required");
+}
+
+const checkout = await polar.checkouts.create({
+  products: [productId],
+  external_customer_id: "usr_123",
+  success_url: "https://example.com/billing/success?checkout_id={CHECKOUT_ID}",
+  return_url: "https://example.com/settings/billing",
+});
+redirect(checkout.url);
+```
+
+Do not treat the success redirect as proof of payment or entitlement. Confirm access through customer state or a verified webhook.
+
+Create short-lived customer portal sessions only for an authenticated customer:
+
+```typescript
+const session = await polar.customerSessions.create({
+  external_customer_id: "usr_123",
+  return_url: "https://example.com/settings/billing",
+});
+redirect(session.customer_portal_url);
+```
+
+Validate return URLs and never let an untrusted caller choose another customer's external ID.
+
+## Reconcile feature access from customer state
+
+Prefer a `feature_flag` benefit attached to the relevant products over inferring access from subscription statuses. Reconcile both access grants and access revocations.
+
+```typescript
+const benefitId = process.env.POLAR_BENEFIT_ID;
+if (!benefitId) {
+  throw new Error("POLAR_BENEFIT_ID is required");
+}
+
+const customerState = await polar.customers.getStateExternal("usr_123");
+const enabled = customerState.granted_benefits.some(
+  (grant) => grant.benefit_id === benefitId,
+);
+
+await setFeatureAccess({
+  customerExternalId: "usr_123",
+  enabled,
+});
+```
+
+Make `setFeatureAccess` an idempotent application write. A missing benefit must disable access, not merely skip a grant operation.
+
+For webhook-driven synchronization, use benefit-grant events for an incremental local grant ledger or `customer.state_changed` for complete snapshot reconciliation. Read [Webhook processing](references/webhooks.md) before implementing or modifying a receiver.
+
+## Ingest metered usage events
+
+Read [Usage-event ingestion](references/usage-events.md) before implementing metered billing. In particular:
+
+- Match the event name and metadata to the configured meter.
+- Associate the event with exactly one `customer_id` or `external_customer_id`.
+- Assign every logical event a stable, unique `external_id`.
+- Reuse the same `external_id` when retrying so Polar can deduplicate the event.
+- Inspect both `inserted` and `duplicates` in the ingestion result.
+- Enforce usage limits in the application; ingestion does not reject an action because a customer has exhausted a balance.
+
+## Handle API failures intentionally
+
+Handle generated endpoint-specific errors before broad SDK errors. Import base errors from `@polar-sh/sdk` and version-specific endpoint errors from the selected API version's `errors` namespace.
+
+- `PolarNetworkError`: retry only when the operation is safe or carries a stable deduplication identifier.
+- `PolarRateLimitError`: apply bounded backoff and honor `retryAfter` when present.
+- `PolarServerError`: retry selected 5xx failures with bounded exponential backoff and jitter.
+- `PolarClientError`: do not blindly retry authentication, authorization, validation, or not-found failures.
+
+Never create a new usage-event `external_id` during a retry. For other mutations, use an endpoint-supported idempotency mechanism or application-level reconciliation before retrying.

package/.agents/skills/polar-typescript-sdk/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Polar TypeScript SDK"
+  short_description: "Build reliable Polar billing integrations"
+  default_prompt: "Use $polar-typescript-sdk to implement a secure Polar billing integration in my TypeScript application."

package/.agents/skills/polar-typescript-sdk/references/migration-from-v0.md

@@ -0,0 +1,114 @@
+# Migrate from the `<1.0.0` SDK
+
+Use these instructions when an application depends on `@polar-sh/sdk<1.0.0`, imports the unversioned `Polar` class, or uses camelCase API fields. Migrate one integration boundary at a time and use the installed new SDK's generated signatures as the source of truth.
+
+## Contents
+
+- [Migration workflow](#migration-workflow)
+- [Keep the casing boundary explicit](#keep-the-casing-boundary-explicit)
+- [Replace client construction](#replace-client-construction)
+- [Migrate operation calls](#migrate-operation-calls)
+- [Replace pagination](#replace-pagination)
+- [Migrate errors, retries, and webhooks](#migrate-errors-retries-and-webhooks)
+
+## Migration workflow
+
+1. Inventory every SDK import, client construction, operation call, request object, response access, error handler, webhook receiver, retry configuration, and pagination loop.
+2. Select the new API version once and use its versioned imports consistently.
+3. Replace client setup before migrating operation calls.
+4. Convert API request and response fields from camelCase to `snake_case`.
+5. Replace pagination, error handling, and webhook validation explicitly.
+6. Remove all remaining unversioned SDK imports and old retry or pagination helpers.
+
+Do not run old and new clients against the same mutation as a comparison strategy. That can create duplicate customers, checkouts, orders, subscriptions, or usage events.
+
+## Keep the casing boundary explicit
+
+The old SDK automatically converted API request and response fields to camelCase. The new SDK does not perform field-name conversion:
+
+- Keep service and operation names in camelCase, such as `customerSessions`, `getStateExternal`, and `iterList`.
+- Write request, query, and response fields in API-style `snake_case`.
+- Do not recursively rename arbitrary `metadata`, custom-field data, or other user-defined object keys.
+
+```typescript
+// Before: @polar-sh/sdk<1.0.0
+const checkout = await polar.checkouts.create({
+  products: [productId],
+  externalCustomerId: "usr_123",
+  successUrl,
+});
+console.log(checkout.customerId);
+```
+
+```typescript
+// After
+const checkout = await polar.checkouts.create({
+  products: [productId],
+  external_customer_id: "usr_123",
+  success_url: successUrl,
+});
+console.log(checkout.customer_id);
+```
+
+Search for camelCase field access throughout application code, persistence mapping, webhook handling, and mocks. Type checking catches many request mistakes, but response values passed through `any`, JSON fixtures, and property-string access need deliberate review.
+
+## Replace client construction
+
+Replace the old class with the versioned `createPolar` factory:
+
+```typescript
+// Before: @polar-sh/sdk<1.0.0
+import { Polar } from "@polar-sh/sdk";
+
+const polar = new Polar({ accessToken });
+```
+
+```typescript
+// After
+import { createPolar } from "@polar-sh/sdk/2026-04";
+
+const polar = createPolar({ accessToken });
+```
+
+Use `createPolarCore` and individual functions from the selected version's `services` paths only when tree-shaking matters. Do not carry forward constructor options that are absent from `PolarOptions`.
+
+## Migrate operation calls
+
+- Expect normalized operation names such as `organizations.list` instead of `organizations.listOrganizations`.
+- Pass path parameters positionally.
+- Pass query parameters as an optional object after path parameters.
+- Pass request bodies as one typed object.
+- Inspect every selected service signature rather than assuming a mechanical rename.
+
+The old standalone functions and the new service factories have different names and binding conventions. Rebuild tree-shakable imports from the selected version's `services` exports instead of renaming the old functions.
+
+## Replace pagination
+
+The old SDK made a list response async iterable and yielded pages. The new SDK exposes `iter*` methods that yield individual resources.
+
+```typescript
+// Before: @polar-sh/sdk<1.0.0
+const pages = await polar.organizations.listOrganizations({});
+for await (const page of pages) {
+  processPage(page);
+}
+```
+
+```typescript
+// After
+for await (const organization of polar.organizations.iterList()) {
+  processOrganization(organization);
+}
+```
+
+Call `list` directly when the application needs page metadata. Do not wrap an `iter*` call in an extra `await` before iterating it.
+
+## Migrate errors, retries, and webhooks
+
+- Replace old SDK error classes with `PolarClientError`, `PolarNetworkError`, `PolarRateLimitError`, and `PolarServerError`, then handle version-specific endpoint errors before those broad classes.
+- Remove the old `retryConfig`; apply bounded application-level retries and honor `retryAfter` for rate limits. Retry mutations only when the endpoint is idempotent or the application can reconcile the result.
+- Replace imports from `@polar-sh/sdk/webhooks` with the versioned `webhooks` namespace.
+- Await `webhooks.validateEvent`, passing the unmodified request body, request headers, and signing secret.
+- Rename old webhook error checks to `webhooks.PolarWebhookVerificationError`, `webhooks.PolarWebhookUnknownTypeError`, and `webhooks.PolarWebhookError`.
+
+Preserve the behavior of acknowledging unknown but correctly signed event types. Read [Webhook processing](webhooks.md) when changing receiver behavior, deduplication, or benefit synchronization. Read [Usage-event ingestion](usage-events.md) before migrating metered event delivery or retry logic.

package/.agents/skills/polar-typescript-sdk/references/usage-events.md

@@ -0,0 +1,59 @@
+# Usage-event ingestion
+
+Use these instructions whenever implementing metered usage or sending events used by a Polar meter.
+
+## Ingest events
+
+Send events from trusted server-side code. Use the application's customer ID as `external_customer_id` when the Polar customer has the same `external_id`.
+
+```typescript
+import { createPolar } from "@polar-sh/sdk/2026-04";
+
+const accessToken = process.env.POLAR_ACCESS_TOKEN;
+if (!accessToken) {
+  throw new Error("POLAR_ACCESS_TOKEN is required");
+}
+
+const polar = createPolar({ accessToken });
+const result = await polar.events.ingest({
+  events: [
+    {
+      name: "ai_generation",
+      external_customer_id: "usr_123",
+      external_id: "usage_01K0E6Y8W4H7D3F2A1B9C5M6N7",
+      metadata: {
+        input_tokens: 1200,
+        output_tokens: 350,
+      },
+    },
+  ],
+});
+
+console.log({
+  inserted: result.inserted,
+  duplicates: result.duplicates ?? 0,
+});
+```
+
+Use an event name and metadata keys that exactly match the configured meter filter and aggregation. Preserve numeric values as numbers rather than formatted strings.
+
+## Make ingestion retry-safe
+
+Assign each logical event a stable, globally unique `external_id` when the application records the usage. Persist that identifier before sending the event.
+
+When a request times out or is retried:
+
+- Send the same logical event with the same `external_id`.
+- Do not generate a replacement ID.
+- Treat the `duplicates` count as successful deduplication, not as newly billed usage.
+- Reconcile unexpected partial batch results before discarding the local delivery record.
+
+Batch events when appropriate, but keep every event independently identifiable. Associate each event with exactly one `customer_id` or `external_customer_id`.
+
+## Understand timestamps and balances
+
+Events are immutable after ingestion. Set `timestamp` to an ISO 8601 string when preserving the time the usage occurred.
+
+Polar attributes an event to a billing period according to when Polar receives it, not only its supplied timestamp. Replaying an old event does not revise an already-closed invoice.
+
+Event ingestion records usage regardless of the customer's remaining meter balance. Query or cache customer state and enforce hard usage limits in the application before performing the metered action.

package/.agents/skills/polar-typescript-sdk/references/webhooks.md

@@ -0,0 +1,96 @@
+# Webhook processing
+
+Use these instructions whenever implementing or modifying a Polar webhook receiver.
+
+## Receiver requirements
+
+1. Run the webhook raw-body parser before any middleware that consumes or transforms the request body.
+2. Read the unmodified request body as a string or `Uint8Array`.
+3. Pass the raw body, request headers, and server-side signing secret to the versioned `webhooks.validateEvent`.
+4. Reject invalid signatures before parsing or processing the payload.
+5. Use the `webhook-id` header as a durable deduplication key.
+6. Persist or enqueue the verified event and respond with a 2xx within two seconds.
+7. Make the worker idempotent because failed deliveries can be retried.
+8. Choose incremental benefit-grant tracking or complete customer-state reconciliation deliberately.
+
+## Express receiver
+
+Use `express.raw` on the webhook route and register the route before `app.use(express.json())` or any other body parser. Once an earlier parser consumes the stream, `express.raw` cannot recover the signed bytes. If route ordering cannot guarantee this, retain the original `Buffer` through the earlier parser's `verify` option and validate that buffer; never reserialize `request.body`.
+
+Replace `enqueueVerifiedWebhook` with a durable, idempotent application operation. Enforce uniqueness on `webhookId`; an in-memory set is not sufficient.
+
+```typescript
+import express from "express";
+import { webhooks } from "@polar-sh/sdk/2026-04";
+
+const webhookSecret = process.env.POLAR_WEBHOOK_SECRET;
+if (!webhookSecret) {
+  throw new Error("POLAR_WEBHOOK_SECRET is required");
+}
+
+const app = express();
+
+// Register this route before app.use(express.json()).
+app.post(
+  "/webhooks/polar",
+  express.raw({ type: "application/json" }),
+  async (request, response, next) => {
+    const headers = {
+      "webhook-id": request.header("webhook-id") ?? "",
+      "webhook-timestamp": request.header("webhook-timestamp") ?? "",
+      "webhook-signature": request.header("webhook-signature") ?? "",
+    };
+
+    try {
+      const event = await webhooks.validateEvent(
+        request.body,
+        headers,
+        webhookSecret,
+      );
+      await enqueueVerifiedWebhook({
+        webhookId: headers["webhook-id"],
+        event,
+      });
+      response.sendStatus(202);
+    } catch (error) {
+      if (error instanceof webhooks.PolarWebhookVerificationError) {
+        response.status(403).json({ error: "Invalid webhook signature" });
+        return;
+      }
+      if (error instanceof webhooks.PolarWebhookUnknownTypeError) {
+        console.warn("Ignoring unsupported signed Polar webhook", {
+          eventType: error.eventType,
+        });
+        response.sendStatus(202);
+        return;
+      }
+      if (error instanceof webhooks.PolarWebhookError) {
+        response.status(400).json({ error: "Invalid webhook payload" });
+        return;
+      }
+      next(error);
+    }
+  },
+);
+
+app.use(express.json());
+```
+
+Acknowledging an unknown but correctly signed event avoids repeated delivery failures when the selected SDK version does not recognize a newer event type. If the application requires strict processing of every subscribed event, alert on the unknown type and upgrade deliberately.
+
+Pass unexpected errors to `next` so Express 4 and Express 5 error middleware can produce a 5xx response. Throwing from an async handler is forwarded automatically only by Express 5.
+
+## Track benefit grants
+
+Use `benefit_grant.created`, `benefit_grant.updated`, and `benefit_grant.revoked` when the application maintains a local grant ledger. These events carry the grant ID, benefit ID, customer, optional member, source subscription or order, grant state, and benefit-specific properties.
+
+- Upsert the grant by `event.data.id` on `benefit_grant.created` and `benefit_grant.updated`.
+- Mark that grant revoked on `benefit_grant.revoked`.
+- Correlate through `event.data.customer.external_id` when set, or a stored Polar customer ID otherwise; do not use email as the durable key.
+- Derive access from whether any grant with `is_granted` and without `is_revoked` remains for the customer, member, and benefit.
+
+Do not disable a feature merely because one grant was revoked. The same benefit can be granted through more than one subscription or order, so another active grant may still authorize access.
+
+Use `customer.state_changed` instead when the application wants a complete current snapshot without maintaining individual grants. Compute the desired access state from `event.data.granted_benefits`, then idempotently write both enabled and disabled states. Snapshot reconciliation is also useful for repairing an incremental ledger after missed or failed processing.
+
+Do not perform slow provisioning, network calls, or other substantial work in the receiver. Perform it in the durable worker after the verified event has been accepted.