@volter/twin-polar 2.0.36 → 3.0.0

package/dist/src/index.d.ts

@@ -1,9 +1,5 @@
-export { handlePolarTwinRequest, polarTwinSnapshot, POLAR_RESOURCE_TYPES } from './polar-twin.js';
-export type { PolarRequest, PolarResponse, PolarResourceType, PolarTwinSnapshot } from './polar-twin.js';
-export { createPolarTwinFetch, createPolarTwinServer, type PolarTwinFetchOptions } from './polar-server.js';
-export { mapCustomer, mapOrder, mapProduct, mapSubscription, pullPolarCustomers, pullPolarOrders, pullPolarProducts, pullPolarSubscriptions, pushPolarAction, syncPolarFromReal, polarClientOver, syncPolarFromRemote, performPolarAction, } from './polar-connector.js';
-export type { PolarCustomer, PolarLikeClient, PolarOrder, PolarProduct, PolarSubscription, PolarBudgetedOptions } from './polar-connector.js';
-export { POLAR_BUDGETED_METHODS, POLAR_BUDGET_CEILING, POLAR_BUDGET_MAX_RETRY_AFTER_S, POLAR_BUDGET_WINDOW_MS, POLAR_CALL_WEIGHTS, POLAR_RATE_BUDGET, PolarBudget, PolarBudgetError, polarBudgetPath, polarCallWeight, polarClientBudget, guardPolarClient, } from './polar-budget.js';
-export type { PolarBudgetErrorKind, PolarBudgetOptions, PolarBudgetReservation, PolarBudgetSnapshot } from './polar-budget.js';
-import { type TwinPack } from '@volter/world-core';
-export declare const pack: TwinPack;
+import { manifest } from './manifest.js';
+export { createPolarFetch } from './fetch.js';
+export { createPolarTwinServer } from './server.js';
+export { manifest };
+export declare const pack: import("@volter/world-core").PackDescriptor;

package/dist/src/index.js

@@ -1,55 +1,10 @@
-// @volter/twin-polar — the Polar (polar.sh) merchant-of-record billing API twin, built on the
-// shared @volter/world-core kernel. REST transport over api.polar.sh shapes; state lives entirely in
-// the kernel action log (no side-store). Customers, products, subscriptions, orders, checkouts,
-// benefits, discounts, meters, usage events, customer sessions, and webhook endpoints.
-// (Conformance/capability tooling lives in @volter/world-tooling, a dev dependency — NOT shipped.)
-export { handlePolarTwinRequest, polarTwinSnapshot, POLAR_RESOURCE_TYPES } from "./polar-twin.js";
-export { createPolarTwinFetch, createPolarTwinServer } from "./polar-server.js";
-export { mapCustomer, mapOrder, mapProduct, mapSubscription, pullPolarCustomers, pullPolarOrders, pullPolarProducts, pullPolarSubscriptions, pushPolarAction, syncPolarFromReal, polarClientOver, syncPolarFromRemote, performPolarAction, } from "./polar-connector.js";
-// The client-side rate budget — the fail-closed backstop every live call goes through. The
-// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
-// DECLARATION (window/ceiling/per-method weights) plus `guardPolarClient`, the choke point the
-// connector entrypoints apply unconditionally. Exported so an operator can inspect spend
-// (`snapshot`) and a caller can catch `PolarBudgetError` by type; there is deliberately no export
-// that disables the guard.
-export { POLAR_BUDGETED_METHODS, POLAR_BUDGET_CEILING, POLAR_BUDGET_MAX_RETRY_AFTER_S, POLAR_BUDGET_WINDOW_MS, POLAR_CALL_WEIGHTS, POLAR_RATE_BUDGET, PolarBudget, PolarBudgetError, polarBudgetPath, polarCallWeight, polarClientBudget, guardPolarClient, } from "./polar-budget.js";
-// Registry descriptor: the pack self-describes so tooling can discover it.
-import { registerPack } from '@volter/world-core';
-import { POLAR_RATE_BUDGET as RATE_BUDGET } from "./polar-budget.js";
-import { performPolarAction as perform, syncPolarFromRemote as refresh } from "./polar-connector.js";
-export const pack = {
-    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
-    // state system: perform one entry against Polar, refresh the root from it. Moved 2026-09-08.
-    protocol: '2',
-    refresh: { every: '5m', webhook: true, onDemand: { atMost: '30s' } },
-    stateSystem: { perform, refresh },
-    roundTrip: { method: 'POST', path: '/v1/products', body: { name: 'round trip', recurring_interval: 'month' }, headers: { authorization: 'Bearer polar_oat_round_trip' } },
-    // rule 5: a checkout names its product; when the head adopts Polar's id for the product, the kernel resolves it first
-    referenceTrip: { method: 'POST', path: '/v1/checkouts', body: { products: ['{{id}}'] }, headers: { authorization: 'Bearer polar_oat_round_trip' } },
-    references: [{ type: 'checkout', to: 'product', key: (f) => (typeof f.product_id === 'string' ? `product:${f.product_id}` : undefined), adopt: (_f, vendorId) => ({ product_id: vendorId.replace(/^product:/, '') }) }],
-    parityOrigin: 'http://twin',
-    shapeParity: 'held',
-    // The SAME object polar-budget.ts declares at module load — one source of truth, so registering
-    // the pack and importing the connector can never arm two different ceilings.
-    rateBudget: RATE_BUDGET,
-    vendor: 'polar',
-    transport: 'rest',
-    archetype: 'crud',
-    bin: 'world-polar',
-    resources: ['customer', 'product', 'subscription', 'order', 'checkout', 'benefit', 'discount', 'meter', 'event', 'customer_session', 'webhook_endpoint'],
-    specSource: 'polar-conformance.ts (endpoint/resource inventory from the Polar API docs at docs.polar.sh)',
-    description: 'Polar merchant-of-record billing twin — customers, products, subscriptions, orders, checkouts (with confirm → subscription/order), benefits, discounts, meters, usage events, customer sessions, and webhook endpoints. Kernel-backed.',
-    // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
-    // 2026-08-31). Both the production API host and Polar's own sandbox host are
-    // claimed — an integration picks one by configuration, and claiming only production would let
-    // sandbox traffic escape the world.
-    adoption: {
-        // Polar's official Python SDK (polarsource/polar-python).
-        pypi: ['polar-sdk'],
-        sdks: ['@polar-sh/sdk'], scopes: ['@polar-sh/'], envStems: ['POLAR'],
-    },
-    hosts: [{ host: 'api.polar.sh' }, { host: 'sandbox-api.polar.sh' }],
-    browserRouting: { apiPathPrefix: '/v1', loaderHost: 'https://api.polar.sh' },
-};
-// registered at import: the kernel learns the pack's state system and its references (protocol 2)
-registerPack(pack);
+// @volter/twin-polar — the polar twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
+import { packOf, registerPack } from '@volter/world-core';
+import { manifest } from "./manifest.js";
+import surface from './generated/surface.gen.json' with { type: 'json' };
+export { createPolarFetch } from "./fetch.js";
+export { createPolarTwinServer } from "./server.js";
+export { manifest };
+export const pack = registerPack(packOf(manifest, surface));

package/dist/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/src/manifest.js

@@ -0,0 +1,123 @@
+import { data, values } from "./semantics/events.js";
+import { states } from "./semantics/states.js";
+export const manifest = {
+    vendor: 'polar',
+    service: 'polar',
+    tenant: { field: 'organization_id' },
+    body: { json: 'always' },
+    // every id Polar answers is `format: uuid4`
+    ids: { template: '{uuid}' },
+    time: 'iso',
+    // spec ResourceNotFound, NotPermitted, Unauthorized: `{ error: <kind>, detail }`
+    error: { error: '{code}', detail: '{message}' },
+    readOnly: { status: 403, code: 'NotPermitted', message: 'This twin was started read-only; writes are refused.' },
+    malformedBody: { status: 422, code: 'RequestValidationError', message: 'JSON decode error' },
+    notFound: { status: 404, code: 'ResourceNotFound', message: 'Not found' },
+    // `{ items, pagination: { total_count, max_page } }`, 1-based `page`, `limit` 10 by default (spec: products:list)
+    list: { style: 'envelope', envelope: { items: '{data}', pagination: { total_count: '{total_count}', max_page: '{max_page}' } }, limit: { param: 'limit', default: 10, max: 100 }, page: { param: 'page', link: false } },
+    deleted: {},
+    auth: {
+        header: 'authorization', scheme: 'Bearer', gateWhenAbsent: false, invalidKeys: [],
+        // spec securitySchemes: `oat` and `pat` are bearer tokens; the front (./semantics/around.ts) checks each operation's
+        // credential by what its security names, so the kernel's gate lets every request through to it
+        missing: { status: 401, code: 'Unauthorized', message: 'Unauthorized' },
+        invalid: { status: 401, code: 'Unauthorized', message: 'Unauthorized' },
+    },
+    events: {
+        scheme: { kind: 'webhook-id', prefix: 'webhook', secretKey: 'utf8' },
+        types: {
+            'checkout.create': 'checkout.created', 'order.create': 'order.created', 'order.pay': 'order.paid',
+        },
+        // source: spec:/components/schemas/WebhookOrderPaidPayload "Sent when an order is paid."
+        envelope: { type: '$type', timestamp: '$time.iso', data: '$data' },
+        endpoints: { storedAs: 'webhook_endpoint', url: 'url', secret: 'secret', filter: 'events', enabled: 'enabled', match: { _environment: '$environment' } },
+        record: '_webhook_delivery',
+        render: data, values,
+    },
+    // the core would serve these from the resources below; no application of the demand calls them (journeys/demand.json)
+    unmodeled: [
+        'checkouts:update', 'meters:get', 'meters:update', 'orders:create', 'orders:get', 'orders:update',
+        'subscriptions:create', 'subscriptions:get', 'subscriptions:update', 'subscriptions:revoke',
+        'webhooks:get_webhook_endpoint', 'webhooks:update_webhook_endpoint', 'webhooks:delete_webhook_endpoint',
+    ],
+    // a vendor-backed World's root: Polar's webhooks sent to the World's ingest door, signed as every Polar event is
+    // (Standard Webhooks, as `events.scheme`), each naming its type in `type` and carrying its object at `data`
+    // source: spec:/components/schemas/WebhookOrderPaidPayload "Sent when an order is paid."
+    ingest: {
+        scheme: { kind: 'webhook-id', prefix: 'webhook', secretKey: 'utf8' },
+        type: { body: 'type' },
+        object: 'data',
+        types: {
+            'customer.created': { resource: 'customer' }, 'customer.updated': { resource: 'customer' }, 'customer.deleted': { resource: 'customer', deleted: true },
+            'product.created': { resource: 'product' }, 'product.updated': { resource: 'product' },
+            'checkout.created': { resource: 'Checkout' }, 'checkout.updated': { resource: 'Checkout' },
+            'order.created': { resource: 'Order' }, 'order.paid': { resource: 'Order' }, 'order.updated': { resource: 'Order' }, 'order.refunded': { resource: 'Order' },
+            'subscription.created': { resource: 'Subscription' }, 'subscription.active': { resource: 'Subscription' }, 'subscription.updated': { resource: 'Subscription' },
+            'subscription.canceled': { resource: 'Subscription' }, 'subscription.uncanceled': { resource: 'Subscription' }, 'subscription.revoked': { resource: 'Subscription' },
+        },
+    },
+    // the fail-closed ceiling on live calls against Polar (world-core rateBudget.ts, architecture D8): the sandbox's limit,
+    // the lower of the two Polar documents, a fifth of production's
+    // source: https://polar.sh/docs/api-reference/introduction "500 requests per minute"
+    // source: https://polar.sh/docs/api-reference/introduction "100 requests per minute"
+    rateBudget: {
+        // the vendor's documented allowance this budget stays inside (cited above)
+        allowance: { perMinute: 100, source: 'https://polar.sh/docs/api-reference/introduction' },
+        windowMs: 60_000, ceiling: 90, defaultWeight: 1, maxRetryAfterSeconds: 300, rules: [],
+        reason: 'Polar documents 500 requests a minute per organization, customer or OAuth2 client in production and 100 in the sandbox, answering 429 with Retry-After over it (polar.sh/docs/api-reference/introduction, Rate Limits); 90 a minute stays under the sandbox\'s limit.',
+    },
+    // GET /twin: what the twin is of and what it keeps
+    discovery: {
+        twinOf: "Polar (api.polar.sh) as Volter's billing and Open Autonomy's patronage call it: meters and products, checkouts paid on the hosted checkout page and read back, the orders they make, customers and their state by the application's own id, customer sessions for the portal, usage events, and the signed webhooks of an organization's endpoints",
+        stores: "the organization's meters and products, customers, checkouts and the subscriptions and orders they make, usage events, customer sessions, webhook endpoints, and the webhooks it sent",
+    },
+    doors: [
+        { id: 'accessTokens', method: 'POST', path: '/_twin/access-tokens', note: '{ comment, expires_in_days? }: an Organization Access Token made on the settings page (shown once)' },
+        { id: 'revokeToken', method: 'DELETE', path: '/_twin/access-tokens/{n}', note: 'a token revoked on the settings page' },
+        { id: 'appCredentials', method: 'POST', path: '/_twin/app-credentials', note: 'the access token an application holds, as the runtime issues it' },
+        { id: 'deliveries', method: 'GET', path: '/_twin/deliveries', note: '?to=<url>&type=<event>: every webhook Polar sent, in order, as the receiving server got it' },
+    ],
+    screens: [
+        { id: 'checkout', kind: 'flow', host: 'buy.polar.sh', path: '/{client_secret}', demand: "every checkout an application sends a customer to (Twin's biller, Open Autonomy's patronage)", status: 'done', controls: ['email', 'pay'], source: 'https://polar.sh/docs/features/checkout/session' },
+        { id: 'portal', kind: 'flow', host: 'polar.sh', path: '/{slug}/portal', demand: "a customer session's customer_portal_url (Twin's biller, Manage billing)", status: 'done', controls: [], source: 'https://polar.sh/docs/features/customer-portal' },
+    ],
+    resources: {
+        _access_token: { idPrefix: 'oat_', ids: '{prefix}{n}' },
+        _customer_meter: { idPrefix: '', ids: '{uuid}' },
+        _order_item: { idPrefix: '', ids: '{uuid}' },
+        _event_key: { idPrefix: 'event_key_' },
+        _price: { idPrefix: '', ids: '{uuid}' },
+        _seq_order: { idPrefix: '', ids: '{n}' },
+        // the stored types the handlers make, declared so their ids are minted (ctx.mint)
+        customer: { orderBy: { param: 'sorting', default: '-created_at', fields: ['created_at'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } }, idPrefix: '', refresh: { list: 'customers:list', items: 'items' } },
+        product: { orderBy: { param: 'sorting', default: '-created_at', fields: ['created_at'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } }, idPrefix: '', refresh: { list: 'products:list' } },
+        event: { orderBy: { param: 'sorting', default: '-timestamp', fields: ['timestamp'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } }, idPrefix: '', refresh: { list: 'events:list', items: 'items' } },
+        customer_session: { idPrefix: '', refresh: { none: "a customer session is a token answered once, by its create; the API lists none and reads none back" } },
+        // a meter as the spec's Meter requires it: what the server assigns beside what the request gives
+        Meter: { orderBy: { param: 'sorting', default: '-created_at', fields: ['created_at', 'name'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } },
+            storedAs: 'meter', idPrefix: '', ...states.Meter, filters: ['name'], order: { field: 'created_at', direction: 'desc' }, refresh: { list: 'meters:list' },
+            // source: spec:/components/schemas/MeterCreate/properties/unit "scalar"
+            assigned: { unit: { value: 'scalar' }, created_at: { now: true }, modified_at: { value: null }, archived_at: { value: null }, metadata: { value: {} } },
+        },
+        WebhookEndpoint: { orderBy: { param: 'sorting', default: '-created_at', fields: ['created_at'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } }, storedAs: 'webhook_endpoint', idPrefix: '', ...states.WebhookEndpoint, order: { field: 'created_at', direction: 'desc' }, refresh: { list: 'webhooks:list_webhook_endpoints' } },
+        Checkout: { orderBy: { param: 'sorting', default: '-created_at', fields: ['created_at'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } }, storedAs: 'checkout', idPrefix: '', ...states.Checkout, refresh: { list: 'checkouts:list' } },
+        Subscription: { orderBy: { param: 'sorting', default: '-started_at', fields: ['started_at'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } }, storedAs: 'subscription', idPrefix: '', ...states.Subscription, refresh: { list: 'subscriptions:list' } },
+        Order: { orderBy: { param: 'sorting', default: '-created_at', fields: ['created_at'], invalid: { status: 422, code: 'RequestValidationError', message: 'Invalid sorting criterion' } }, storedAs: 'order', idPrefix: '', ...states.Order, refresh: { list: 'orders:list' } },
+    },
+    // the descriptor, as data (twin-world's architecture, "The descriptor"): the pack registers packOf(manifest, surface)
+    descriptor: {
+        protocol: '3',
+        transport: 'rest',
+        archetype: 'crud',
+        bin: 'world-polar',
+        resources: ['customer', 'product', 'checkout', 'subscription', 'order', 'event', 'meter', 'customer_session', 'webhook_endpoint'],
+        specSource: 'Polar\'s OpenAPI document, 2026-04 (spec/openapi.json.gz, provenance in spec/SOURCE.md)',
+        description: 'Polar twin — meters and products with their prices, checkouts with the hosted checkout page, the orders and subscriptions a paid checkout makes, customers and their state (subscriptions and meters) by the application\'s own id, customer sessions, usage events, webhook endpoints, and webhooks signed as Polar\'s SDK verifies them.',
+        adoption: { sdks: ['@polar-sh/sdk'], pypi: ['polar-sdk'], scopes: ['@polar-sh/'], envStems: ['POLAR'] },
+        // a World's applications hold an Organization Access Token the settings page made; the API refuses any other
+        credentialDoor: { path: '/_twin/app-credentials', body: {}, fill: { POLAR_ACCESS_TOKEN: 'access_token', POLAR_API_KEY: 'access_token', POLAR_ORGANIZATION_TOKEN: 'access_token' } },
+        // the API (production and sandbox) and the hosted checkout
+        hosts: [{ host: 'api.polar.sh' }, { host: 'sandbox-api.polar.sh' }, { host: 'buy.polar.sh' }, { host: 'polar.sh', pathPattern: '^/[^/]+/portal' }, { host: 'sandbox.polar.sh' }],
+        endpointEnvNone: '@polar-sh/sdk reads no base-URL variable: its `server` option picks production or sandbox, both claimed by the host rules.',
+    },
+};

package/dist/src/screens/checkout.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function screen(ctx: HandlerContext): Promise<Response>;

package/dist/src/screens/checkout.js

@@ -0,0 +1,25 @@
+import { checkouts_client_confirm, checkouts_client_get } from "../semantics/checkouts.js";
+const esc = (v) => String(v ?? '').replace(/[&<>"]/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[ch]);
+export async function screen(ctx) {
+    const secret = String(ctx.call.params.client_secret);
+    const paying = new URL(ctx.call.request.url).pathname.replace(/\/+$/, '').endsWith('/pay');
+    const base = ctx.publicBase.replace(/\/+$/, '');
+    const read = await checkouts_client_get(ctx);
+    if (!read.ok)
+        return new Response('This checkout does not exist.', { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+    const c = (await read.json());
+    if (paying && ctx.call.request.method === 'POST') {
+        const form = new URLSearchParams(ctx.text);
+        // the page pays as Polar's own page does: the client API's confirm, with the email the customer gave
+        const done = await checkouts_client_confirm({ ...ctx, body: { customer_email: form.get('email') || c.customer_email, confirmation_token_id: await ctx.secret(`test-stripe-confirmation:${c.id}`) } });
+        if (!done.ok)
+            return new Response(`The payment could not be completed (${done.status}).`, { status: done.status, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+        return new Response(null, { status: 303, headers: { location: c.success_url.replace('{CHECKOUT_ID}', c.id) } });
+    }
+    const money = `$${(Number(c.amount) / 100).toFixed(2)}`;
+    const per = c.product?.recurring_interval ? ` / ${c.product.recurring_interval}` : '';
+    const body = c.status !== 'open'
+        ? `<p>This checkout is ${esc(c.status)}.</p>`
+        : `<form method="post" action="${esc(base)}/${esc(secret)}/pay"><label>Email<input name="email" type="email" required value="${esc(c.customer_email)}"></label><label>Card<input value="4242 4242 4242 4242" readonly></label><button type="submit">Pay ${esc(money)}${esc(per)}</button></form>`;
+    return new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Checkout</title><style>body{font:16px/1.5 system-ui,sans-serif;background:#f7f7f8;margin:0}main{max-width:440px;margin:48px auto;background:#fff;border:1px solid #e5e5e8;border-radius:12px;padding:28px}h1{font-size:20px;margin:0}p.price{font-size:30px;font-weight:600;margin:10px 0 20px}label{display:block;font-size:13px;color:#555;margin:12px 0}input{display:block;width:100%;box-sizing:border-box;padding:9px;border:1px solid #ccc;border-radius:8px;font:inherit;margin-top:4px}button{margin-top:16px;width:100%;padding:11px;border:0;border-radius:8px;background:#0062ff;color:#fff;font:inherit;cursor:pointer}</style></head><body><main><h1>${esc(c.product?.name ?? 'Checkout')}</h1><p class="price">${esc(money)}<small>${esc(per)}</small></p>${body}</main></body></html>`, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+}

package/dist/src/screens/portal.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function screen(ctx: HandlerContext): Promise<Response>;

package/dist/src/screens/portal.js

@@ -0,0 +1,18 @@
+import { rowOf, CUSTOMER, customerView, orderView, ORDER, productView, PRODUCT, rowsOf, SESSION, SUBSCRIPTION } from "../semantics/shared.js";
+const esc = (v) => String(v ?? '').replace(/[&<>"]/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[ch]);
+// source: https://polar.sh/docs/features/customer-portal/navigate-customers "no email code required"
+// source: https://polar.sh/docs/features/customer-portal "active subscriptions"
+export async function screen(ctx) {
+    const token = new URL(ctx.call.request.url).searchParams.get('customer_session_token');
+    const session = rowsOf(ctx, SESSION).find((s) => s.token === token && String(s.expires_at) > ctx.occurredAt);
+    if (!session)
+        return new Response('Unauthorized', { status: 401 });
+    const customer = rowOf(ctx, CUSTOMER, String(session.customer_id));
+    if (!customer)
+        return new Response('Customer not found', { status: 404 });
+    const subscriptions = rowsOf(ctx, SUBSCRIPTION).filter((s) => s.customer_id === customer.id && ['active', 'trialing'].includes(String(s.status)));
+    const orders = rowsOf(ctx, ORDER).filter((o) => o.customer_id === customer.id).sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
+    const plans = subscriptions.map((s) => `<li>${esc(productView(ctx, rowOf(ctx, PRODUCT, String(s.product_id))).name)}: ${esc(s.status)}</li>`).join('');
+    const history = orders.map((o) => { const v = orderView(ctx, o); return `<li>${esc(v.invoice_number)} — ${esc(v.currency)} ${(Number(v.total_amount) / 100).toFixed(2)}</li>`; }).join('');
+    return new Response(`<!doctype html><html lang="en"><title>Customer portal</title><main><h1>Billing for ${esc(customerView(ctx, customer).email)}</h1><h2>Subscriptions</h2><ul>${plans || '<li>No active subscriptions</li>'}</ul><h2>Purchase history</h2><ul>${history || '<li>No purchases</li>'}</ul><a href="${esc(session.return_url)}">Return to the application</a></main></html>`, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+}

package/dist/src/semantics/around.d.ts

@@ -0,0 +1,2 @@
+import { type HandlerContext } from '@volter/world-core';
+export declare function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response>;

package/dist/src/semantics/around.js

@@ -0,0 +1,25 @@
+// POLAR'S FRONT: every request's credential, by what its operation takes (the operation's `credentials`, the security
+// schemes the published document names for it, as the derive keeps them). An organization's operation (`oat`, `pat`)
+// needs one of the organization's access tokens (made on the settings page: a World door, kept by its SHA-256); a
+// customer portal operation (`customer_session`, `member_session`) needs a live customer session's token; the
+// checkout's client operations, OAuth's endpoints and the portal's email verification need none. A missing or unknown
+// credential is Polar's 401. Where the documentation stops: the refusal's words, as the API answers them. One operation
+// is read otherwise: the checkout's confirm names a signed-in Polar user's credential (`oidc`, `pat`), which the buyer
+// on the checkout page does not have and no organization token stands for; the twin takes the checkout's client secret,
+// in its path, as the confirm's credential, as the page's other client operations do.
+// source: spec:/components/securitySchemes/oat "Organization Access Token"
+import { sha256 } from '@volter/world-core';
+import { environment } from "./shared.js";
+const unauthorized = () => Response.json({ error: 'Unauthorized', detail: 'Unauthorized' }, { status: 401 });
+export async function around(ctx, next) {
+    const takes = ctx.call.operation.id === 'checkouts:client_confirm' ? [] : ctx.call.operation.credentials ?? [];
+    const bearer = /^Bearer\s+(\S+)/i.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1];
+    if (takes.includes('oat') || takes.includes('pat')) {
+        if (!bearer)
+            return unauthorized();
+        const held = ctx.rowsRaw('_access_token').some((t) => (t._environment ?? 'production') === environment(ctx) && t._sha256 === sha256(bearer) && t.deleted !== true && (t.expires_at === null || Date.parse(String(t.expires_at)) > Date.parse(ctx.occurredAt)));
+        if (!held)
+            return unauthorized();
+    }
+    return next();
+}

package/dist/src/semantics/checkouts.d.ts

@@ -0,0 +1,14 @@
+import type { HandlerContext } from '@volter/world-core';
+/** `POST /v1/checkouts/`: a session for the first product named, at its first price, open for 24 hours. */
+export declare function checkouts_create(ctx: HandlerContext): Promise<Response>;
+/** `GET /v1/checkouts/{id}`: the session as the application reads it back (its status once the customer has paid). */
+export declare function checkouts_get(ctx: HandlerContext): Promise<Response>;
+/** `GET /v1/checkouts/`: the organization's checkout sessions, newest first, by customer, product, status or the
+ *  customer's email. */
+export declare function checkouts_list(ctx: HandlerContext): Promise<Response>;
+export declare function checkouts_client_get(ctx: HandlerContext): Promise<Response>;
+/** `POST /v1/checkouts/client/{client_secret}/confirm`: the customer pays. The customer is found or made, the order
+ *  is paid, a recurring product's subscription starts (trialing through the product's trial), and the checkout
+ *  succeeds. A product's benefits are granted too; no application of the demand gives a product one (the benefits'
+ *  API is the gap), so none is granted here. */
+export declare function checkouts_client_confirm(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/checkouts.js

@@ -0,0 +1,131 @@
+import { rowOf, among, bodyOf, checkoutFields, customerFields, subscriptionFields, createSession, environment, CHECKOUT, checkoutView, newest, CUSTOMER, customerBy, fail, invalid, missing, newId, notFound, organizationView, priceView, PRODUCT, rowsOf, secret, SUBSCRIPTION, addInterval, makeOrder, } from "./shared.js";
+const DAY = 86_400_000;
+// source: https://raw.githubusercontent.com/polarsource/polar/main/server/polar/config.py "CHECKOUT_TTL_SECONDS: int = 60 * 60 * 24"
+/** `POST /v1/checkouts/`: a session for the first product named, at its first price, open for 24 hours. */
+// source: spec:checkouts:create "Create a checkout session."
+export async function checkouts_create(ctx) {
+    const body = bodyOf(ctx);
+    const products = Array.isArray(body.products) ? body.products.map(String) : [];
+    // source: spec:/components/schemas/CheckoutProductsCreate "products"
+    if (products.length === 0)
+        return missing('products');
+    const product = rowOf(ctx, PRODUCT, products[0]);
+    // the spec documents no 404 here: a product or customer that does not exist is the request's validation error, on
+    // the field that named it (where the documentation stops: the message's words)
+    // source: spec:checkouts:create "Validation Error"
+    if (!product || product.deleted === true)
+        return invalid(['products', 0], 'Product does not exist.');
+    // source: https://polar.sh/docs/features/checkout/session "Ad-hoc prices are temporary prices that exist only for that specific checkout session"
+    const adHoc = [];
+    for (const p of body.prices?.[products[0]] ?? []) {
+        const priceId = ctx.mint('_price');
+        await ctx.record('_price', {}, priceId);
+        adHoc.push({ ...p, id: priceId, source: 'ad_hoc' });
+    }
+    const price = (adHoc.length ? adHoc : product.prices ?? [])[0];
+    const amount = price?.amount_type === 'fixed' ? Number(price.price_amount ?? 0) : Number(body.amount ?? 0);
+    const customer = body.customer_id !== undefined ? customerBy(ctx, { id: body.customer_id }) : undefined;
+    if (body.customer_id !== undefined && !customer)
+        return invalid(['customer_id'], 'Customer does not exist.');
+    const id = newId(ctx, CHECKOUT);
+    await ctx.write(CHECKOUT, id, { ...checkoutFields(ctx, {
+            id, created_at: ctx.occurredAt, modified_at: null, status: 'open', client_secret: await secret(ctx, 'polar_c_', `checkout:${id}`),
+            expires_at: new Date(Date.parse(ctx.occurredAt) + DAY).toISOString(), product_id: product.id, products, product_price_id: price?.id ?? null, amount,
+            prices: { [String(product.id)]: (adHoc.length ? adHoc.map((p) => priceView(ctx, p, product)) : product.prices) }, currency: price?.price_currency ?? 'usd', success_url: body.success_url ?? null, return_url: body.return_url ?? null, embed_origin: body.embed_origin ?? null, customer_ip_address: body.customer_ip_address ?? null, allow_discount_codes: body.allow_discount_codes ?? true, require_billing_address: body.require_billing_address ?? false, allow_trial: body.allow_trial ?? null, is_business_customer: body.is_business_customer ?? false,
+            customer_id: customer?.id ?? null, customer_email: body.customer_email ?? customer?.email ?? null, customer_name: body.customer_name ?? null,
+            external_customer_id: body.external_customer_id ?? body.customer_external_id ?? null, metadata: body.metadata ?? {}, customer_metadata: body.customer_metadata ?? {},
+        }), _environment: environment(ctx) }, 'checkout.create');
+    return Response.json(checkoutView(ctx, rowOf(ctx, CHECKOUT, id)), { status: 201 });
+}
+const bySecret = (ctx) => rowsOf(ctx, CHECKOUT).find((c) => c.client_secret === ctx.call.params.client_secret);
+/** The client API answers CheckoutPublic: the checkout and its organization. */
+// source: spec:/components/schemas/CheckoutPublic "CheckoutPublic"
+const publicView = (ctx, c) => {
+    const { trial_interval: _ti, trial_interval_count: _tc, metadata: _m, external_customer_id: _e, subscription_id: _s, customer_metadata: _cm, ...visible } = checkoutView(ctx, c);
+    return { ...visible, organization: organizationView(ctx) };
+};
+/** `GET /v1/checkouts/{id}`: the session as the application reads it back (its status once the customer has paid). */
+// source: spec:checkouts:get "Get a checkout session by ID."
+export async function checkouts_get(ctx) {
+    const c = rowOf(ctx, CHECKOUT, String(ctx.call.params.id));
+    return c && c.deleted !== true ? Response.json(checkoutView(ctx, c)) : notFound('Checkout');
+}
+/** `GET /v1/checkouts/`: the organization's checkout sessions, newest first, by customer, product, status or the
+ *  customer's email. */
+// source: spec:checkouts:list "List checkout sessions."
+export async function checkouts_list(ctx) {
+    const q = String(ctx.params.query ?? '').toLowerCase();
+    const rows = rowsOf(ctx, CHECKOUT)
+        .filter((c) => among(ctx, 'customer_id', c.customer_id) && among(ctx, 'external_customer_id', c.external_customer_id) && among(ctx, 'product_id', c.product_id) && among(ctx, 'status', c.status))
+        // source: spec:checkouts:list "Filter by customer email."
+        .filter((c) => q === '' || String(c.customer_email ?? '').toLowerCase().includes(q))
+        .sort(newest('created_at'));
+    return ctx.list('Checkout', rows.map((c) => checkoutView(ctx, c)));
+}
+// source: spec:checkouts:client_get "Get a checkout session by client secret."
+export async function checkouts_client_get(ctx) {
+    const c = bySecret(ctx);
+    return c ? Response.json(publicView(ctx, c)) : notFound('Checkout');
+}
+/** `POST /v1/checkouts/client/{client_secret}/confirm`: the customer pays. The customer is found or made, the order
+ *  is paid, a recurring product's subscription starts (trialing through the product's trial), and the checkout
+ *  succeeds. A product's benefits are granted too; no application of the demand gives a product one (the benefits'
+ *  API is the gap), so none is granted here. */
+// source: spec:checkouts:client_confirm "Orders and subscriptions will be processed."
+export async function checkouts_client_confirm(ctx) {
+    const c = bySecret(ctx);
+    if (!c)
+        return notFound('Checkout');
+    // source: spec:checkouts:client_confirm "The checkout session is expired."
+    if (c.status === 'expired')
+        return fail(410, 'ExpiredCheckoutError', 'The checkout session is expired.');
+    const refused = ctx.legal('Checkout', 'status', 'checkouts:client_confirm', c.status, 'confirmed', String(c.id), 'external');
+    if (refused)
+        return ctx.refuse(refused);
+    const body = bodyOf(ctx);
+    // source: spec:/components/schemas/CheckoutConfirmStripe/properties/confirmation_token_id "Required for fixed prices and custom prices."
+    if (c.is_payment_required && !body.confirmation_token_id)
+        return missing('confirmation_token_id');
+    const email = (body.customer_email ?? c.customer_email);
+    // the customer: the one named, the one the application's own id names, or the one with the email; else a new one
+    let customer = c.customer_id ? customerBy(ctx, { id: c.customer_id }) : c.external_customer_id ? customerBy(ctx, { external: c.external_customer_id }) : undefined;
+    if (!customer && email)
+        customer = rowsOf(ctx, CUSTOMER).find((x) => String(x.email).toLowerCase() === email.toLowerCase());
+    if (!customer) {
+        if (!email)
+            return missing('customer_email');
+        const cid = newId(ctx, CUSTOMER);
+        await ctx.write(CUSTOMER, cid, { ...customerFields(ctx, { id: cid, created_at: ctx.occurredAt, modified_at: null, email, name: body.customer_name ?? c.customer_name ?? null, external_id: c.external_customer_id ?? null, email_verified: false, metadata: {} }), _environment: environment(ctx) }, 'customer.create');
+        customer = rowOf(ctx, CUSTOMER, cid);
+    }
+    const customerId = String(customer.id);
+    const product = rowOf(ctx, PRODUCT, String(c.product_id));
+    // source: spec:checkouts:client_confirm "the customer already has an active subscription"
+    const existing = product.recurring_interval != null ? rowsOf(ctx, SUBSCRIPTION).find((s) => s.customer_id === customerId && s.product_id === product.id && ['trialing', 'active'].includes(String(s.status))) : undefined;
+    if (existing)
+        return ctx.refuse(ctx.legal('Subscription', 'status', 'checkouts:client_confirm', existing.status, undefined, String(existing.id), 'external'));
+    const at = ctx.occurredAt;
+    await ctx.write(CHECKOUT, String(c.id), { status: 'confirmed', customer_id: customerId, customer_email: customer.email, modified_at: at }, 'checkout.update');
+    // the subscription of a recurring product: its period from now, or its trial first
+    let subscriptionId = null;
+    if (product.recurring_interval) {
+        subscriptionId = newId(ctx, SUBSCRIPTION);
+        const trial = product.trial_interval != null;
+        const end = addInterval(at, String(trial ? product.trial_interval : product.recurring_interval), Number(trial ? product.trial_interval_count ?? 1 : product.recurring_interval_count ?? 1));
+        await ctx.write(SUBSCRIPTION, subscriptionId, { ...subscriptionFields(ctx, {
+                id: subscriptionId, created_at: at, modified_at: null, amount: c.amount, currency: c.currency ?? 'usd', recurring_interval: product.recurring_interval,
+                recurring_interval_count: product.recurring_interval_count ?? 1, status: 'incomplete', current_period_start: at, current_period_end: end,
+                trial_start: trial ? at : null, trial_end: trial ? end : null, cancel_at_period_end: false, canceled_at: null, started_at: at, ends_at: null, ended_at: null,
+                customer_id: customerId, product_id: product.id, checkout_id: c.id, prices: c.prices[String(product.id)], metadata: c.metadata ?? {},
+            }), _environment: environment(ctx) }, 'subscription.create');
+        // source: spec:/components/schemas/SubscriptionStatus "trialing"
+        await ctx.write(SUBSCRIPTION, subscriptionId, { status: trial ? 'trialing' : 'active', modified_at: at }, 'subscription.activate');
+    }
+    // source: https://polar.sh/docs/features/subscriptions/trials "they will not be charged immediately"
+    if (!product.trial_interval)
+        await makeOrder(ctx, { ...c, customer_id: customerId, subscription_id: subscriptionId }, subscriptionId ? 'subscription_create' : 'purchase');
+    const session = await createSession(ctx, customer);
+    const confirmed = { ...publicView(ctx, rowOf(ctx, CHECKOUT, String(c.id))), customer_session_token: session.token };
+    await ctx.write(CHECKOUT, String(c.id), { status: 'succeeded', subscription_id: subscriptionId, modified_at: at }, 'checkout.update');
+    return Response.json(confirmed);
+}

package/dist/src/semantics/clock.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function clock(ctx: HandlerContext): Promise<void>;

package/dist/src/semantics/clock.js

@@ -0,0 +1,22 @@
+import { addInterval, CHECKOUT, makeOrder, rowsOf, SUBSCRIPTION } from "./shared.js";
+export async function clock(ctx) {
+    // source: spec:checkouts:client_confirm "The checkout session is expired."
+    for (const c of rowsOf(ctx, CHECKOUT).filter((c) => c.status === 'open' && String(c.expires_at) <= ctx.occurredAt)) {
+        const due = await ctx.at(String(c.expires_at));
+        await due.write(CHECKOUT, String(c.id), { status: 'expired', modified_at: due.occurredAt }, 'checkout.update');
+    }
+    // source: https://polar.sh/docs/features/subscriptions/introduction "At the end of each billing period, Polar advances the subscription to the next cycle and creates a new order"
+    for (const s of rowsOf(ctx, SUBSCRIPTION).filter((s) => ['trialing', 'active'].includes(String(s.status)))) {
+        let end = String(s.current_period_end);
+        while (end <= ctx.occurredAt) {
+            const due = await ctx.at(end);
+            const next = addInterval(end, String(s.recurring_interval), Number(s.recurring_interval_count ?? 1));
+            // source: https://polar.sh/docs/features/subscriptions/trials "Once the trial period ends, the customer will be automatically charged for the subscription, and their billing cycle will begin."
+            await due.write(SUBSCRIPTION, String(s.id), { status: 'active', current_period_start: end, current_period_end: next, modified_at: end }, 'subscription.update');
+            await makeOrder(due, { ...s, subscription_id: s.id }, s.status === 'trialing' ? 'subscription_create' : 'subscription_cycle', s.status === 'trialing' ? undefined : { start: String(s.current_period_start), end });
+            s.current_period_start = end;
+            s.status = 'active';
+            end = next;
+        }
+    }
+}

package/dist/src/semantics/customer-sessions.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function customer_sessions_create(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/customer-sessions.js

@@ -0,0 +1,12 @@
+import { bodyOf, customerBy, createSession, invalid, missing } from "./shared.js";
+// source: spec:customer-sessions:create "Create a customer session."
+export async function customer_sessions_create(ctx) {
+    const body = bodyOf(ctx);
+    if (body.customer_id === undefined && body.external_customer_id === undefined)
+        return missing('customer_id');
+    const customer = body.customer_id !== undefined ? customerBy(ctx, { id: body.customer_id }) : customerBy(ctx, { external: body.external_customer_id });
+    // source: spec:customer-sessions:create "Validation Error"
+    if (!customer)
+        return invalid([body.customer_id !== undefined ? 'customer_id' : 'external_customer_id'], 'Customer does not exist.');
+    return Response.json(await createSession(ctx, customer, body.return_url), { status: 201 });
+}

package/dist/src/semantics/customers.d.ts

@@ -0,0 +1,9 @@
+import type { HandlerContext } from '@volter/world-core';
+/** `POST /v1/customers/`: an individual customer, its email required. */
+export declare function customers_create(ctx: HandlerContext): Promise<Response>;
+/** `GET /v1/customers/{id}`: the customer as the API answers it. */
+export declare function customers_get(ctx: HandlerContext): Promise<Response>;
+export declare function customers_get_state_external(ctx: HandlerContext): Promise<Response>;
+/** `GET /v1/customers/`: the organization's customers, newest first, by exact email, a query over name, email and
+ *  external id, or whether they hold a live subscription. */
+export declare function customers_list(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/customers.js

@@ -0,0 +1,61 @@
+import { rowOf, bodyOf, customerFields, environment, CUSTOMER, customerBy, customerState, customerView, invalid, missing, newest, newId, notFound, rowsOf, SUBSCRIPTION } from "./shared.js";
+const FIELDS = ['email', 'name', 'external_id', 'billing_name', 'billing_address', 'tax_id', 'locale', 'metadata'];
+/** A customer's email or external id already held by another: Polar's 422. */
+function taken(ctx, fields, except) {
+    const emailTaken = typeof fields.email === 'string' && rowsOf(ctx, CUSTOMER).some((c) => c.id !== except && String(c.email).toLowerCase() === String(fields.email).toLowerCase());
+    return emailTaken ? duplicateEmail() : fields.external_id != null && rowsOf(ctx, CUSTOMER).some((c) => c.id !== except && c.external_id === fields.external_id) ? duplicateExternal() : undefined;
+}
+/** `POST /v1/customers/`: an individual customer, its email required. */
+// source: spec:customers:create "Create a customer."
+export async function customers_create(ctx) {
+    const body = bodyOf(ctx);
+    if (typeof body.email !== 'string' || body.email === '')
+        return missing('email');
+    const refused = taken(ctx, body);
+    if (refused)
+        return refused;
+    const id = newId(ctx, CUSTOMER);
+    const fields = { id, created_at: ctx.occurredAt, modified_at: null, email_verified: false };
+    for (const k of FIELDS)
+        if (k in body)
+            fields[k] = body[k];
+    await ctx.write(CUSTOMER, id, { ...customerFields(ctx, fields), _environment: environment(ctx) }, 'customer.create');
+    return Response.json(customerView(ctx, rowOf(ctx, CUSTOMER, id)), { status: 201 });
+}
+const byExternal = (ctx) => customerBy(ctx, { external: decodeURIComponent(ctx.call.params.external_id ?? '') });
+/** `GET /v1/customers/{id}`: the customer as the API answers it. */
+// source: spec:customers:get "Get a customer by ID."
+export async function customers_get(ctx) {
+    const c = customerBy(ctx, { id: ctx.call.params.id });
+    return c ? Response.json(customerView(ctx, c)) : notFound('Customer');
+}
+// source: spec:customers:get_state_external "Get a customer state by external ID."
+export async function customers_get_state_external(ctx) {
+    const c = byExternal(ctx);
+    return c ? Response.json(await customerState(ctx, c)) : notFound('Customer');
+}
+/** `GET /v1/customers/`: the organization's customers, newest first, by exact email, a query over name, email and
+ *  external id, or whether they hold a live subscription. */
+// source: spec:customers:list "List customers."
+export async function customers_list(ctx) {
+    const q = String(ctx.params.query ?? '').toLowerCase();
+    // source: spec:customers:list "Filter by active customers, i.e. customers with at least one trialing, active or past_due subscription."
+    const live = new Set(rowsOf(ctx, SUBSCRIPTION).filter((s) => ['trialing', 'active', 'past_due'].includes(String(s.status))).map((s) => s.customer_id));
+    const active = ctx.params.active === undefined ? undefined : String(ctx.params.active) === 'true';
+    const rows = rowsOf(ctx, CUSTOMER)
+        .filter((c) => ctx.params.email === undefined || String(c.email ?? '').toLowerCase() === String(ctx.params.email).toLowerCase())
+        .filter((c) => q === '' || [c.name, c.email, c.external_id].some((v) => typeof v === 'string' && v.toLowerCase().includes(q)))
+        .filter((c) => active === undefined || live.has(c.id) === active)
+        .sort(newest('created_at'));
+    return ctx.list(CUSTOMER, rows.map((c) => customerView(ctx, c)));
+}
+// source: spec:customers:create "Validation Error"
+// Where the documentation stops: the error wording for the duplicate external id.
+function duplicateExternal() {
+    return invalid(['external_id'], 'A customer with this external ID already exists.');
+}
+// source: spec:customers:create "Validation Error"
+// Where documentation stops: the duplicate-email error message.
+function duplicateEmail() {
+    return invalid(['email'], 'A customer with this email address already exists.');
+}

package/dist/src/semantics/doors.d.ts

@@ -0,0 +1,11 @@
+import { type HandlerContext } from '@volter/world-core';
+/** POST /_twin/access-tokens {comment, expires_in_days?}: an Organization Access Token made on the settings page. */
+export declare function accessTokens(ctx: HandlerContext): Promise<Response>;
+/** DELETE /_twin/access-tokens/{n}: a token revoked on the settings page. */
+export declare function revokeToken(ctx: HandlerContext): Promise<Response>;
+/** POST /_twin/app-credentials: the access token an application holds, as the runtime issues it (the descriptor's
+ *  credentialDoor). */
+export declare function appCredentials(ctx: HandlerContext): Promise<Response>;
+/** GET /_twin/deliveries[?to=<url>][&type=<event>]: every webhook Polar sent (the kernel's record of each delivery, in
+ *  the order sent): what the application's server was told, and when. */
+export declare function deliveries(ctx: HandlerContext): Promise<Response>;