@volter/twin-polar 0.1.2 → 2.0.1

package/dist/src/polar-connector.js

@@ -0,0 +1,146 @@
+// Polar CONNECTOR — the live-vendor pull/push path that gives the Polar twin the full
+// "git for SaaS" lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL  (real → twin):  fetch real Polar objects via the injected client (customers, products,
+//                       subscriptions, orders), map them to SyncResource[], and fold them into
+//                       the event log via syncPull (shadow-diff dedup, so a re-pull of identical
+//                       state is a no-op). Kernel subject ids are TYPE-PREFIXED to stay
+//                       collision-safe (mirrors the twin handler).
+// PUSH  (twin → real):  for every PENDING local action, call the injected client and
+//                       confirmAction on success — recording the confirmed fields as observed
+//                       and suppressing the local projection.
+//
+// The vendor I/O is an INJECTED client interface (`PolarLikeClient`): a fake in tests, a real
+// `new Polar({ accessToken })` in prod. The pack imports NO SDK and holds NO key.
+import { observeResources } from '@volter/world-core';
+//
+// ── The client-side RATE BUDGET is not optional here ────────────────────────────────────────
+// Polar publishes 500 requests/minute in production and 100/minute in sandbox per organization, and
+// is the one vendor in this batch that documents a Retry-After header — so the guard's cooldown is
+// armed by the vendor itself rather than inferred.
+// Every entrypoint below GUARDS the injected client before touching it (`guardPolarClient`, which is
+// idempotent — a caller who already wrapped is not double-charged, a caller who forgot is protected
+// anyway); there is deliberately no option that turns the budget off. See polar-budget.ts.
+import { polarBudgetOf, guardPolarClient } from "./polar-budget.js";
+const SERVICE = 'polar';
+// Kernel subject id (type-prefixed → collision-safe across types; mirrors polar-twin.ts).
+function kid(type, id) {
+    return `${type}:${id}`;
+}
+// ── PULL mappers (real Polar object → SyncResource) ──────────────────────────────────
+export function mapCustomer(c) {
+    return { type: 'customer', id: kid('customer', String(c.id)), fields: { created_at: c.created_at ?? null, modified_at: null, email: c.email ?? null, name: c.name ?? null, external_id: c.external_id ?? null, customer_type: 'individual', email_verified: false, locale: 'en', metadata: c.metadata ?? {} } };
+}
+export function mapProduct(p) {
+    return { type: 'product', id: kid('product', String(p.id)), fields: { created_at: p.created_at ?? null, modified_at: null, name: p.name ?? null, description: p.description ?? null, recurring_interval: p.recurring_interval ?? null, is_archived: p.is_archived ?? false, trial_interval: p.trial_interval ?? null, trial_interval_count: p.trial_interval_count ?? null, prices: p.prices ?? [], benefits: [], metadata: {} } };
+}
+export function mapSubscription(s) {
+    return { type: 'subscription', id: kid('subscription', String(s.id)), fields: { created_at: s.created_at ?? null, modified_at: null, status: s.status ?? 'active', amount: s.amount ?? 0, currency: s.currency ?? 'usd', recurring_interval: s.recurring_interval ?? 'month', customer_id: s.customer_id ?? null, product_id: s.product_id ?? null, current_period_end: s.current_period_end ?? null, cancel_at_period_end: s.cancel_at_period_end ?? false, metadata: {} } };
+}
+export function mapOrder(o) {
+    return { type: 'order', id: kid('order', String(o.id)), fields: { created_at: o.created_at ?? null, modified_at: null, status: o.status ?? 'paid', paid: o.status !== 'refunded', amount: o.amount ?? o.total_amount ?? 0, total_amount: o.total_amount ?? o.amount ?? 0, currency: o.currency ?? 'usd', customer_id: o.customer_id ?? null, product_id: o.product_id ?? null, subscription_id: o.subscription_id ?? null, metadata: {} } };
+}
+export async function pullPolarCustomers(rawClient, opts = {}) {
+    const client = guardPolarClient(rawClient, opts);
+    if (!client.customers)
+        return [];
+    return (await client.customers.list()).items.map(mapCustomer);
+}
+export async function pullPolarProducts(rawClient, opts = {}) {
+    const client = guardPolarClient(rawClient, opts);
+    if (!client.products)
+        return [];
+    return (await client.products.list()).items.map(mapProduct);
+}
+export async function pullPolarSubscriptions(rawClient, opts = {}) {
+    const client = guardPolarClient(rawClient, opts);
+    if (!client.subscriptions)
+        return [];
+    return (await client.subscriptions.list()).items.map(mapSubscription);
+}
+export async function pullPolarOrders(rawClient, opts = {}) {
+    const client = guardPolarClient(rawClient, opts);
+    if (!client.orders)
+        return [];
+    return (await client.orders.list()).items.map(mapOrder);
+}
+/**
+ * D7 entry point: pull from real Polar (customers + products + subscriptions + orders) and fold
+ * EVERY domain into the twin via ONE syncPull (shadow-diff dedup). Returns { observed,
+ * deltasAppended } — callers need not know vendor-specific pull mechanics.
+ */
+export async function syncPolarFromReal(rawClient, opts = {}) {
+    // Guard ONCE here and hand the guarded client down, so no domain pull can run unbudgeted.
+    const client = guardPolarClient(rawClient, polarBudgetOf(opts));
+    const occurredAt = opts.occurredAt ?? new Date().toISOString();
+    const resources = [
+        ...(await pullPolarCustomers(client)),
+        ...(await pullPolarProducts(client)),
+        ...(await pullPolarSubscriptions(client)),
+        ...(await pullPolarOrders(client)),
+    ];
+    // protocol 2: an observation lands on the head through the kernel's fold — one batch, one instant
+    const report = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+    return { observed: report.observed, deltasAppended: report.appended };
+}
+// ── PROTOCOL 2: the state system's two adapters, over the kernel's executor ──────────
+/** A PolarLikeClient over a RemoteExecute: the calls the SDK makes, as wire requests the executor carries. */
+export function polarClientOver(execute) {
+    const call = async (method, path, body) => {
+        const res = await execute({ method, path, headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+        if (res.status >= 300)
+            throw new Error(`polar: ${method} ${path} answered ${res.status}: ${res.body.slice(0, 200)}`);
+        return (res.body === '' ? {} : JSON.parse(res.body));
+    };
+    const list = (path) => async () => { const page = await call('GET', `${path}?limit=100`); return { items: page.items ?? [] }; };
+    return {
+        customers: { list: list('/v1/customers'), create: (params) => call('POST', '/v1/customers', params) },
+        products: { list: list('/v1/products'), create: (params) => call('POST', '/v1/products', params) },
+        subscriptions: { list: list('/v1/subscriptions') },
+        orders: { list: list('/v1/orders') },
+    };
+}
+/** The refresh adapter: pull Polar's customers, products, subscriptions and orders through the executor and fold them into the root. */
+export async function syncPolarFromRemote(execute, opts = {}) {
+    // guarded HERE too (idempotent), so the source tooth sees every entrypoint hold the budget
+    const budget = { ...(opts.budgetOptions ?? {}), ...(opts.root !== undefined && !opts.budgetOptions?.root ? { root: opts.root } : {}) };
+    const client = guardPolarClient(polarClientOver(execute), polarBudgetOf({ ...opts, budgetOptions: budget }));
+    return syncPolarFromReal(client, { ...opts, budgetOptions: budget });
+}
+/** The perform adapter: one entry crosses to Polar through the executor; a customer or product it names by a local id resolves first. */
+export async function performPolarAction(execute, action, ctx) {
+    const fields = { ...(action.fields ?? {}) };
+    for (const [field, type] of [['customer_id', 'customer'], ['product_id', 'product']]) {
+        if (typeof fields[field] === 'string')
+            fields[field] = ctx.resolve(type, kid(type, String(fields[field]).replace(new RegExp(`^${type}:`), ''))).replace(new RegExp(`^${type}:`), '');
+    }
+    const budget = { budgetOptions: { ...(ctx.root !== undefined ? { root: ctx.root } : {}) } };
+    const { externalId } = await pushPolarAction(guardPolarClient(polarClientOver(execute), polarBudgetOf(budget)), { operation: action.operation, subject: action.subject, fields }, budget);
+    return { externalId };
+}
+// ── PUSH ──────────────────────────────────────────────────────────────────────────
+// The twin operations this connector knows how to push to real Polar. Anything else FAILS
+// LOUDLY rather than being silently dropped.
+const PUSHABLE = new Set(['customer.create', 'product.create']);
+export async function pushPolarAction(rawClient, action, opts = {}) {
+    // Writes count against the SAME per-minute budget reads do, so the push path is budgeted too.
+    const client = guardPolarClient(rawClient, opts);
+    const op = action.operation ?? `${action.subject.type}.update`;
+    if (!PUSHABLE.has(op))
+        throw new Error(`polar push: unsupported operation '${op}' — refusing to silently drop a local write`);
+    const fields = action.fields ?? {};
+    let externalId = action.subject.id;
+    if (op === 'customer.create' && client.customers?.create) {
+        externalId = (await client.customers.create({ email: fields.email, name: fields.name, external_id: fields.external_id })).id;
+    }
+    else if (op === 'product.create' && client.products?.create) {
+        externalId = (await client.products.create({ name: fields.name, recurring_interval: fields.recurring_interval })).id;
+    }
+    return { externalId: externalId || action.subject.id };
+}
+/**
+ * Push the twin's PENDING local actions to real Polar and CONFIRM each. A confirmed action is
+ * no longer pending, so a re-push enacts NOTHING. Unpushable ops are skipped.
+ */
+// protocol 2: the pending-actions loop is the kernel's (the head performs each entry through `performPolarAction`);
+// the v1 `pushPendingPolarActions` is gone with the log it read.

package/dist/src/polar-server.d.ts

@@ -0,0 +1,14 @@
+/** Options every Polar-twin HTTP surface needs, independent of who owns the socket. */
+export interface PolarTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createPolarTwinFetch(options?: PolarTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createPolarTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/polar-server.js

@@ -0,0 +1,52 @@
+// Polar twin HTTP server — serve the full Polar API twin handler over HTTP so the real
+// `@polar-sh/sdk` (pointed at this base URL) works unmodified. JSON bodies pass through to the
+// handler. Writable by default; pass readOnly to reject writes with 405 (D3). State is the
+// kernel projection (no side-store) — see polar-twin.ts.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`); this file contributes only VALUES. The
+// vendor's 204 deletes return `{ status: 204, body: null }`, which the adapter's null-body rule
+// serves as a genuinely empty response. The server is one line of Bun.serve around that closure.
+import { serveHttp } from '@volter/world-core';
+import { handlePolarTwinRequest } from "./polar-twin.js";
+import { createTwinFetchFromHandler, statefulTwinManifest, twinPublicBase } from '@volter/world-core';
+export function createPolarTwinFetch(options = {}) {
+    const api = createTwinFetchFromHandler(handlePolarTwinRequest, {
+        ...options,
+        manifest: statefulTwinManifest({ vendor: 'polar', twinOf: 'the Polar billing API', stores: 'customers, checkouts, subscriptions, meters and usage events' }),
+        // where this twin is reached (origin plus any served-World mount path): the checkout's hosted page is minted there
+        extras: (request) => ({ publicBase: twinPublicBase(request) }),
+    });
+    // the hosted checkout page, at the twin's own address: what a person sees after "continue to checkout at
+    // Polar" in a walk — the product, the amount, a Pay button that confirms the checkout and returns to the
+    // app's success_url (in production this page is Polar's; the twin stands in for it, plainly labelled)
+    return async function polarFetch(request) {
+        const url = new URL(request.url);
+        const page = /^\/twin\/checkout\/([a-zA-Z0-9-]+)(\/pay)?$/.exec(url.pathname);
+        if (!page)
+            return api(request);
+        const id = page[1];
+        const read = await api(new Request(`${url.origin}/v1/checkouts/${id}`, { headers: { authorization: request.headers.get('authorization') ?? 'Bearer polar_oat_page' } }));
+        if (!read.ok)
+            return new Response('no such checkout', { status: 404 });
+        const c = (await read.json());
+        if (page[2] && request.method === 'POST') {
+            const done = await api(new Request(`${url.origin}/v1/checkouts/${id}/confirm`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer polar_oat_page' }, body: '{}' }));
+            if (!done.ok)
+                return new Response(`the checkout could not be confirmed (${done.status})`, { status: 502 });
+            return new Response(null, { status: 303, headers: { location: c.success_url ?? `${twinPublicBase(request)}/twin/checkout/${id}` } });
+        }
+        const money = `$${(Number(c.amount ?? 0) / 100).toFixed(2)} ${String(c.currency ?? 'usd').toUpperCase()}`;
+        const esc = (v) => String(v ?? '').replace(/[&<>"]/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[ch]);
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Checkout — Polar (twin)</title><style>body{font:16px/1.5 -apple-system,system-ui,sans-serif;margin:0;background:#f6f6f7;color:#111}main{max-width:480px;margin:48px auto;background:#fff;border:1px solid #e3e3e6;border-radius:12px;padding:28px 32px}h1{font-size:20px;margin:0 0 4px}.mode{color:#666;font-size:13px}.price{font-size:32px;font-weight:650;margin:12px 0}button{font:inherit;padding:10px 18px;border-radius:8px;border:0;background:#111;color:#fff;cursor:pointer}label{display:block;margin:12px 0 4px;font-size:13px;color:#555}input{width:100%;padding:8px 10px;border:1px solid #ccc;border-radius:6px;font:inherit}</style></head><body><main><p class="mode">Polar checkout · this page is the polar twin's stand-in for Polar's hosted checkout</p><h1>${esc(c.product?.name ?? 'Subscription')}</h1><p class="price">${esc(money)} <span class="mode">/ month</span></p>${c.status !== 'open' ? `<p>This checkout is ${esc(c.status)}.</p>` : `<form method="post" action="${esc(twinPublicBase(request))}/twin/checkout/${esc(id)}/pay"><label>Email</label><input name="email" value="${esc(c.customer_email ?? '')}" readonly /><label>Card</label><input name="card" value="4242 4242 4242 4242 · any date · any code" readonly /><p class="mode">A test card: nothing is charged here.</p><button type="submit">Pay ${esc(money)}</button></form>`}</main></body></html>`;
+        return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+    };
+}
+export async function createPolarTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createPolarTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/polar-twin.d.ts

@@ -0,0 +1,24 @@
+export type PolarRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    /** where the twin is reached when served over HTTP (`twinPublicBase`): the checkout's hosted page is there */
+    publicBase?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+};
+export type PolarResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export declare const POLAR_RESOURCE_TYPES: readonly ["customer", "product", "subscription", "order", "checkout", "benefit", "discount", "customer_session", "event", "meter", "webhook_endpoint"];
+export type PolarResourceType = typeof POLAR_RESOURCE_TYPES[number];
+export declare function handlePolarTwinRequest(req: PolarRequest): Promise<PolarResponse>;
+export type PolarTwinSnapshot = {
+    resourceTypes: readonly PolarResourceType[];
+    implementedEndpoints: readonly string[];
+};
+export declare function polarTwinSnapshot(): PolarTwinSnapshot;