@volter/twin-polar 0.1.2 → 2.0.1

package/src/polar-twin.ts

@@ -1,5 +1,5 @@
 // Polar API twin REQUEST HANDLER — the canonical api.polar.sh surface for the twin, backed by
-// the event/action-log kernel (@volter/twin). Contract:
+// the event/action-log kernel (@volter/world-core). Contract:
 //   handlePolarTwinRequest({ method, path, body, root, readOnly }) -> { status, body }
 // Response SHAPES mirror real Polar (UUID4 ids, `{ items, pagination }` list envelopes, the
 // FastAPI-style error envelopes) so the real `@polar-sh/sdk` works unmodified. HTTP wrapper:
@@ -17,7 +17,7 @@
 // required for correctness) — while the PUBLIC `id` emitted to clients is the bare UUID4 that
 // Polar returns. `kid()` builds the subject id; rows() strips the prefix back off for the view.
 import { createHash } from 'node:crypto';
-import { applyTwinWrite, projectResources, worldNow } from '@volter/twin';
+import { applyTwinWrite, projectResources, resolveSubjectId, worldNow } from '@volter/world-core';
 
 const SERVICE = 'polar';
 const ORG_ID = '00000000-0000-4000-8000-0000000000a1'; // the twin's single organization id
@@ -26,6 +26,9 @@ 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;
@@ -44,7 +47,7 @@ export type PolarResourceType = typeof POLAR_RESOURCE_TYPES[number];
 // Polar returns `{ type: 'ResourceNotFound', detail: '... not found.' }` for 404 and a
 // FastAPI `HTTPValidationError` (`{ detail: [{ type, loc, msg }] }`) for 422.
 function notFound(detail: string): PolarResponse {
-  return { status: 404, body: { type: 'ResourceNotFound', detail } };
+  return { status: 404, body: { error: 'ResourceNotFound', detail } };
 }
 function validationError(loc: (string | number)[], msg: string, type = 'value_error'): PolarResponse {
   return { status: 422, body: { detail: [{ type, loc: ['body', ...loc], msg, input: null }] } };
@@ -111,11 +114,11 @@ function kid(type: string, id: string): string {
 
 // ── projection helpers ──────────────────────────────────────────────────────────────
 // Live (non-soft-deleted) rows of a type, with the kernel subject prefix stripped back to the
-// bare public id. `_deleted` is the twin-internal soft-delete overlay (the log is append-only).
+// bare public id. A delete is the kernel's tombstone (`deleted: true`, cleared by the next write — protocol 2).
 function rows(type: string, root?: string): Array<Record<string, unknown>> {
   const prefix = `${type}:`;
   return projectResources(SERVICE, root)
-    .filter((r) => r.type === type && r.id.startsWith(prefix) && (r as Record<string, unknown>)._deleted !== true)
+    .filter((r) => r.type === type && r.id.startsWith(prefix) && (r as Record<string, unknown>).deleted !== true)
     .map((r) => ({ ...r, id: r.id.slice(prefix.length) }));
 }
 function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
@@ -173,7 +176,7 @@ function customerView(r: Record<string, unknown>): Record<string, unknown> {
   };
 }
 
-function productView(r: Record<string, unknown>): Record<string, unknown> {
+function productView(r: Record<string, unknown>, root?: string): Record<string, unknown> {
   const v = view(r);
   return {
     id: v.id,
@@ -182,16 +185,40 @@ function productView(r: Record<string, unknown>): Record<string, unknown> {
     name: v.name ?? null,
     description: v.description ?? null,
     recurring_interval: v.recurring_interval ?? null,
+    recurring_interval_count: v.recurring_interval != null ? Number(v.recurring_interval_count ?? 1) : null,
     is_recurring: v.recurring_interval != null,
     is_archived: v.is_archived ?? false,
+    visibility: v.visibility ?? 'public',
+    trial_interval: v.trial_interval ?? null, trial_interval_count: v.trial_interval_count ?? null,
+    meter_interval: null, meter_interval_count: null,
     organization_id: ORG_ID,
     metadata: v.metadata ?? {},
-    prices: Array.isArray(v.prices) ? v.prices : [],
+    prices: (Array.isArray(v.prices) ? (v.prices as Array<Record<string, unknown>>) : []).map((pr) => priceView(pr, String(v.id), v.recurring_interval as string | null, String(v.created_at), root)),
     benefits: Array.isArray(v.benefits) ? v.benefits : [],
     medias: [],
     attached_custom_fields: [],
   };
 }
+/** A price as Polar returns it (ProductPriceFixed for a fixed amount, ProductPriceFree for none): the stored row filled to the wire shape. */
+function priceView(pr: Record<string, unknown>, productId: string, recurring: string | null, createdAt: string, root?: string): Record<string, unknown> {
+  const amount = pr.price_amount != null ? Number(pr.price_amount) : null;
+  if (pr.amount_type === 'metered_unit' || pr.meter_id != null) { // a metered price (usage beyond the plan): Polar's ProductPriceMeteredUnit, with its meter
+    const meter = pr.meter_id ? getRow('meter', String(pr.meter_id), root) : undefined;
+    return {
+      id: pr.id ?? uuidFrom('price', `${productId}:metered:${String(pr.meter_id)}`), created_at: pr.created_at ?? createdAt, modified_at: pr.modified_at ?? null,
+      amount_type: 'metered_unit', is_archived: pr.is_archived ?? false, product_id: productId, source: 'catalog',
+      type: recurring ? 'recurring' : 'one_time', recurring_interval: recurring, tax_behavior: null,
+      price_currency: pr.price_currency ?? 'usd', unit_amount: String(pr.unit_amount ?? '0'), cap_amount: pr.cap_amount ?? null,
+      meter_id: pr.meter_id ?? null, meter: { id: pr.meter_id ?? null, name: meter?.name ?? 'meter', unit: meter?.unit ?? 'unit', custom_label: null, custom_multiplier: null },
+    };
+  }
+  return {
+    id: pr.id ?? uuidFrom('price', `${productId}:${amount ?? 'free'}`), created_at: pr.created_at ?? createdAt, modified_at: pr.modified_at ?? null,
+    amount_type: amount != null ? 'fixed' : 'free', is_archived: pr.is_archived ?? false, product_id: productId, source: 'catalog',
+    type: recurring ? 'recurring' : 'one_time', recurring_interval: recurring, tax_behavior: null,
+    ...(amount != null ? { price_currency: pr.price_currency ?? 'usd', price_amount: amount } : {}),
+  };
+}
 
 function subscriptionView(r: Record<string, unknown>, root?: string): Record<string, unknown> {
   const v = view(r);
@@ -211,6 +238,9 @@ function subscriptionView(r: Record<string, unknown>, root?: string): Record<str
     started_at: v.started_at ?? v.created_at,
     ends_at: v.ends_at ?? null,
     ended_at: v.ended_at ?? null,
+    trial_start: v.trial_start ?? null, trial_end: v.trial_end ?? null,
+    customer_cancellation_reason: null, customer_cancellation_comment: null,
+    seats: null, units: null, meters: [], custom_field_data: {},
     customer_id: v.customer_id ?? null,
     product_id: v.product_id ?? null,
     discount_id: v.discount_id ?? null,
@@ -245,9 +275,22 @@ function orderView(r: Record<string, unknown>): Record<string, unknown> {
   };
 }
 
-function checkoutView(r: Record<string, unknown>): Record<string, unknown> {
+function checkoutView(r: Record<string, unknown>, root?: string): Record<string, unknown> {
   const v = view(r);
+  const product = v.product_id ? getRow('product', String(v.product_id), root) : undefined;
+  const productOut = product ? productView({ ...product, type: 'product' }, root) : null;
+  const price = productOut && Array.isArray(productOut.prices) ? ((productOut.prices as Record<string, unknown>[])[0] ?? null) : null;
+  const amount = Number(v.amount ?? 0);
   return {
+    return_url: v.return_url ?? null, tax_behavior: null, allow_trial: null, active_trial_interval: null, active_trial_interval_count: null, trial_end: null,
+    trial_interval: null, trial_interval_count: null, organization_id: ORG_ID,
+    product_price_id: price ? String(price.id) : null, allow_discount_codes: true, require_billing_address: false, is_discount_applicable: false,
+    is_free_product_price: amount === 0, is_payment_required: amount > 0, is_payment_setup_required: productOut?.is_recurring === true, is_payment_form_required: amount > 0,
+    is_business_customer: false, customer_ip_address: null, customer_billing_name: null, customer_billing_address: null, customer_tax_id: null,
+    payment_processor_metadata: {}, billing_address_fields: { country: 'required', state: 'disabled', city: 'disabled', postal_code: 'disabled', line1: 'disabled', line2: 'disabled' },
+    external_customer_id: v.external_customer_id ?? null, customer_external_id: v.external_customer_id ?? null,
+    products: productOut ? [productOut] : [], product: productOut, product_price: price, prices: {}, discount: null, attached_custom_fields: [], customer_metadata: {}, custom_field_data: {},
+    net_amount: amount, tax_amount: null, total_amount: amount, currency: v.currency ?? 'usd', subscription_id: v.subscription_id ?? null,
     id: v.id,
     created_at: v.created_at,
     modified_at: v.modified_at ?? null,
@@ -260,20 +303,12 @@ function checkoutView(r: Record<string, unknown>): Record<string, unknown> {
     embed_origin: v.embed_origin ?? null,
     amount: v.amount ?? 0,
     discount_amount: 0,
-    net_amount: v.amount ?? 0,
-    tax_amount: 0,
-    total_amount: v.amount ?? 0,
-    currency: v.currency ?? 'usd',
     product_id: v.product_id ?? null,
-    products: Array.isArray(v.products) ? v.products : [],
     discount_id: v.discount_id ?? null,
     customer_id: v.customer_id ?? null,
     customer_email: v.customer_email ?? null,
     customer_name: v.customer_name ?? null,
-    subscription_id: v.subscription_id ?? null,
-    organization_id: ORG_ID,
     metadata: v.metadata ?? {},
-    customer_metadata: {},
   };
 }
 
@@ -320,6 +355,7 @@ function meterView(r: Record<string, unknown>): Record<string, unknown> {
     created_at: v.created_at,
     modified_at: v.modified_at ?? null,
     name: v.name ?? null,
+    unit: v.unit ?? 'unit', custom_label: null, custom_multiplier: null, archived_at: null,
     aggregation: v.aggregation ?? { func: 'count' },
     filter: v.filter ?? { conjunction: 'and', clauses: [] },
     organization_id: ORG_ID,
@@ -358,7 +394,7 @@ function webhookView(r: Record<string, unknown>): Record<string, unknown> {
 function customerState(customerId: string, root?: string): Record<string, unknown> {
   const cust = getRow('customer', customerId, root);
   const subs = rows('subscription', root)
-    .filter((s) => s.customer_id === customerId && s.status === 'active')
+    .filter((s) => s.customer_id === customerId && (s.status === 'active' || s.status === 'trialing')) // Polar's active statuses are {trialing, active}
     .map((s) => subscriptionView(s, root));
   const meters = rows('event', root)
     .filter((e) => e.customer_id === customerId)
@@ -367,20 +403,70 @@ function customerState(customerId: string, root?: string): Record<string, unknow
       if (Number.isFinite(cost)) { if (cost < 0) acc.credited += Math.abs(cost); else acc.consumed += cost; }
       return acc;
     }, { consumed: 0, credited: 0 });
+  // Polar's real customer state carries one entry PER METER, each meter aggregating the
+  // customer's events its filter admits by its aggregation function (sum/count/max/min/avg over a
+  // metadata property). A root with no meters keeps the earlier placeholder balance (cost_usd).
+  const defined = rows('meter', root);
+  const mine = rows('event', root).filter((e) => e.customer_id === customerId);
+  const active_meters = defined.length === 0
+    ? [{ id: uuidFrom('customer_meter', customerId), meter_id: '00000000-0000-4000-8000-0000000000b1', consumed_units: meters.consumed, credited_units: meters.credited, balance: meters.credited - meters.consumed }]
+    : defined.map((m) => {
+        const matched = mine.filter((e) => meterAdmits(m.filter as Record<string, unknown> | undefined, e));
+        const consumed = meterAggregate(m.aggregation as Record<string, unknown> | undefined, matched);
+        return { id: uuidFrom('customer_meter', `${customerId}:${m.id}`), created_at: m.created_at, modified_at: null, meter_id: m.id, consumed_units: consumed, credited_units: 0, balance: -consumed };
+      });
   return {
     ...(cust ? customerView(cust) : { id: customerId }),
     active_subscriptions: subs,
     granted_benefits: [],
-    active_meters: [{
-      id: uuidFrom('customer_meter', customerId),
-      meter_id: '00000000-0000-4000-8000-0000000000b1',
-      consumed_units: meters.consumed,
-      credited_units: meters.credited,
-      balance: meters.credited - meters.consumed,
-    }],
+    active_meters,
   };
 }
 
+/** Does a meter's filter admit an event? Polar's filter: `{conjunction: and|or, clauses: [{property, operator, value} | filter]}`;
+ *  a clause's property is `name`, `source`, or a metadata key (`metadata.x` or bare). Operators: eq, ne, gt, gte, lt, lte, like, not_like. */
+function meterAdmits(filter: Record<string, unknown> | undefined, e: Record<string, unknown>): boolean {
+  const clauses = Array.isArray(filter?.clauses) ? (filter!.clauses as Array<Record<string, unknown>>) : [];
+  if (clauses.length === 0) return true;
+  const one = (c: Record<string, unknown>): boolean => {
+    if ('clauses' in c) return meterAdmits(c, e);
+    const prop = String(c.property ?? '');
+    const actual = prop === 'name' || prop === 'source' ? e[prop] : ((e.metadata as Record<string, unknown> | undefined)?.[prop.replace(/^metadata\./, '')]);
+    const want = c.value; const op = String(c.operator ?? 'eq');
+    switch (op) {
+      case 'eq': return actual === want || String(actual) === String(want);
+      case 'ne': return !(actual === want || String(actual) === String(want));
+      case 'gt': return Number(actual) > Number(want); case 'gte': return Number(actual) >= Number(want);
+      case 'lt': return Number(actual) < Number(want); case 'lte': return Number(actual) <= Number(want);
+      case 'like': return String(actual ?? '').includes(String(want)); case 'not_like': return !String(actual ?? '').includes(String(want));
+      default: return false;
+    }
+  };
+  return String(filter?.conjunction ?? 'and') === 'or' ? clauses.some(one) : clauses.every(one);
+}
+/** A meter's aggregation over the admitted events: count, or sum/max/min/avg of a metadata property. */
+function meterAggregate(agg: Record<string, unknown> | undefined, events: Array<Record<string, unknown>>): number {
+  const func = String(agg?.func ?? 'count');
+  if (func === 'count') return events.length;
+  const prop = String(agg?.property ?? '').replace(/^metadata\./, '');
+  const values = events.map((e) => Number((e.metadata as Record<string, unknown> | undefined)?.[prop])).filter((n) => Number.isFinite(n));
+  if (values.length === 0) return 0;
+  if (func === 'sum') return values.reduce((a, b) => a + b, 0);
+  if (func === 'max') return Math.max(...values); if (func === 'min') return Math.min(...values);
+  if (func === 'avg') return values.reduce((a, b) => a + b, 0) / values.length;
+  return values.reduce((a, b) => a + b, 0);
+}
+/** The customer an external id names, or one created for it — Polar creates the customer on first use of an external id. */
+async function customerForExternalId(ext: string, req: PolarRequest, email?: string | null): Promise<Record<string, unknown>> {
+  const existing = rows('customer', req.root).find((c) => c.external_id === ext);
+  if (existing) return existing;
+  const cid = mintId('customer', req, ext);
+  return write('customer', cid, {
+    created_at: nowIso(req.occurredAt), modified_at: null, email: email ?? `${ext}@external.twin`, name: null, external_id: ext,
+    customer_type: 'individual', email_verified: false, locale: 'en', metadata: {},
+  }, 'customer.create', req);
+}
+
 // ── route handler ────────────────────────────────────────────────────────────────────
 export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarResponse> {
   const method = req.method.toUpperCase();
@@ -391,6 +477,10 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
   // segments after the /v1 prefix, e.g. /v1/customers/abc → ["customers","abc"]
   const all = path.replace(/^\/+/, '').split('/').filter(Boolean);
   const seg = all[0] === 'v1' ? all.slice(1) : all;
+  // protocol 2: after a landing adopted the vendor's id, a caller on a branch may still address a product or a
+  // customer by the local id — resolved through the alias map once, here at the boundary (a `type:` prefix is tolerated)
+  const bare = (type: string, id: string): string => resolveSubjectId(SERVICE, type, kid(type, id.replace(new RegExp(`^${type}:`), '')), req.root).replace(new RegExp(`^${type}:`), '');
+  if ((seg[0] === 'products' || seg[0] === 'customers') && seg[1] && seg[1] !== 'external') seg[1] = bare(seg[0].slice(0, -1), decodeURIComponent(seg[1]));
   const idAt = (i: number) => decodeURIComponent(seg[i] ?? '');
 
   if (req.readOnly && method !== 'GET') {
@@ -431,6 +521,12 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
       return { status: 200, body: listEnvelope(items) };
     }
     // GET /customers/:id/state
+    // GET /customers/external/:external_id and …/state — the customer by YOUR id (Polar's real routes)
+    if (seg[1] === 'external' && (seg.length === 3 || (seg.length === 4 && seg[3] === 'state')) && method === 'GET') {
+      const c = rows('customer', req.root).find((x) => x.external_id === idAt(2));
+      if (!c) return notFound('Customer not found.');
+      return { status: 200, body: seg.length === 4 ? customerState(String(c.id), req.root) : customerView({ ...c, type: 'customer' }) };
+    }
     if (seg.length === 3 && seg[2] === 'state' && method === 'GET') {
       if (!getRow('customer', idAt(1), req.root)) return notFound('Customer not found.');
       return { status: 200, body: customerState(idAt(1), req.root) };
@@ -450,7 +546,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
     if (seg.length === 2 && method === 'DELETE') {
       const c = getRow('customer', idAt(1), req.root);
       if (!c) return notFound('Customer not found.');
-      await write('customer', idAt(1), { _deleted: true }, 'customer.delete', req);
+      await write('customer', idAt(1), { deleted: true }, 'customer.delete', req);
       return { status: 204, body: null };
     }
   }
@@ -467,18 +563,19 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
         created_at: nowIso(req.occurredAt), modified_at: null,
         name: body.name, description: body.description ?? null,
         recurring_interval: body.recurring_interval ?? null,
+        trial_interval: body.trial_interval ?? null, trial_interval_count: body.trial_interval_count ?? null, // the product's trial, as Polar keeps it
         is_archived: false, prices, benefits: [], metadata: body.metadata ?? {},
       }, 'product.create', req);
-      return { status: 201, body: productView({ ...p, type: 'product' }) };
+      return { status: 201, body: productView({ ...p, type: 'product' }, req.root) };
     }
     if (seg.length === 1 && method === 'GET') {
       let items = rows('product', req.root);
       if (query.is_archived !== undefined) items = items.filter((p) => Boolean(p.is_archived) === (query.is_archived === 'true'));
-      return { status: 200, body: listEnvelope(items.map((p) => productView({ ...p, type: 'product' }))) };
+      return { status: 200, body: listEnvelope(items.map((p) => productView({ ...p, type: 'product' }, req.root))) };
     }
     if (seg.length === 2 && method === 'GET') {
       const p = getRow('product', idAt(1), req.root);
-      return p ? { status: 200, body: productView({ ...p, type: 'product' }) } : notFound('Product not found.');
+      return p ? { status: 200, body: productView({ ...p, type: 'product' }, req.root) } : notFound('Product not found.');
     }
     if (seg.length === 2 && method === 'PATCH') {
       const p = getRow('product', idAt(1), req.root);
@@ -486,7 +583,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
       const patch: Record<string, unknown> = { modified_at: nowIso(req.occurredAt) };
       for (const k of ['name', 'description', 'recurring_interval', 'is_archived', 'metadata']) if (k in body) patch[k] = body[k];
       const updated = await write('product', idAt(1), patch, 'product.update', req);
-      return { status: 200, body: productView({ ...updated, type: 'product' }) };
+      return { status: 200, body: productView({ ...updated, type: 'product' }, req.root) };
     }
   }
 
@@ -512,7 +609,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
     if (seg.length === 2 && method === 'DELETE') {
       const b = getRow('benefit', idAt(1), req.root);
       if (!b) return notFound('Benefit not found.');
-      await write('benefit', idAt(1), { _deleted: true }, 'benefit.delete', req);
+      await write('benefit', idAt(1), { deleted: true }, 'benefit.delete', req);
       return { status: 204, body: null };
     }
   }
@@ -551,7 +648,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
     if (seg.length === 2 && method === 'DELETE') {
       const d = getRow('discount', idAt(1), req.root);
       if (!d) return notFound('Discount not found.');
-      await write('discount', idAt(1), { _deleted: true }, 'discount.delete', req);
+      await write('discount', idAt(1), { deleted: true }, 'discount.delete', req);
       return { status: 204, body: null };
     }
   }
@@ -583,25 +680,30 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
     if (seg.length === 2 && seg[1] === 'ingest' && method === 'POST') {
       const events = Array.isArray(body.events) ? (body.events as Array<Record<string, unknown>>) : null;
       if (!events) return validationError(['events'], 'Field required', 'missing');
-      let inserted = 0;
-      for (const e of events) {
-        if (!e.name) return validationError(['events', 'name'], 'Field required', 'missing');
-        const id = mintId('event', req);
+      let inserted = 0; let duplicates = 0;
+      for (const [i, e] of events.entries()) {
+        if (!e.name) return validationError(['events', i, 'name'], 'Field required', 'missing');
+        // `external_id` is YOUR id for the event — a second ingest of it is a duplicate, not a second event
+        if (e.external_id && rows('event', req.root).some((x) => x.external_id === e.external_id)) { duplicates += 1; continue; }
+        // an external customer id names (or creates) the customer; the event lands on that customer
+        let customerId = e.customer_id ? String(e.customer_id) : null;
+        if (!customerId && e.external_customer_id) customerId = String((await customerForExternalId(String(e.external_customer_id), req)).id);
+        const id = mintId('event', req, String(e.external_id ?? i));
         await write('event', id, {
           timestamp: e.timestamp ?? nowIso(req.occurredAt), created_at: nowIso(req.occurredAt),
-          name: e.name, customer_id: e.customer_id ?? null,
+          name: e.name, customer_id: customerId, external_id: e.external_id ?? null,
           external_customer_id: e.external_customer_id ?? null,
           source: 'user', metadata: e.metadata ?? {},
         }, 'event.ingest', req);
         inserted += 1;
       }
-      return { status: 200, body: { inserted, duplicates: 0 } };
+      return { status: 200, body: { inserted, duplicates } };
     }
     if (seg.length === 1 && method === 'GET') {
       const customerId = query.customer_id;
-      const name = query.name;
+      const name = query.name; const ext = query.external_customer_id;
       const items = rows('event', req.root)
-        .filter((e) => (!customerId || e.customer_id === customerId) && (!name || e.name === name))
+        .filter((e) => (!customerId || e.customer_id === customerId) && (!name || e.name === name) && (!ext || e.external_customer_id === ext))
         .map((e) => eventView({ ...e, type: 'event' }));
       return { status: 200, body: listEnvelope(items) };
     }
@@ -623,7 +725,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
       const token = `polar_cst_${mintSecret('customer_session_token', req, String(cust.id))}`;
       const s = await write('customer_session', id, {
         created_at: nowIso(req.occurredAt), modified_at: null,
-        token, expires_at: laterIso(req.occurredAt), customer_id: cust.id,
+        token, expires_at: laterIso(req.occurredAt), customer_id: cust.id, return_url: body.return_url ?? null,
         customer_portal_url: `https://polar.sh/twin/portal?customer_session_token=${token}`,
       }, 'customer_session.create', req);
       const v = view({ ...s, type: 'customer_session' });
@@ -634,7 +736,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
   // ── CHECKOUTS ──
   if (seg[0] === 'checkouts') {
     if (seg.length === 1 && method === 'POST') {
-      const products = Array.isArray(body.products) ? (body.products as string[]) : (body.product_id ? [String(body.product_id)] : []);
+      const products = (Array.isArray(body.products) ? (body.products as string[]) : (body.product_id ? [String(body.product_id)] : [])).map((id) => bare('product', String(id)));
       if (products.length === 0) return validationError(['products'], 'Field required', 'missing');
       const productId = products[0]!;
       const product = getRow('product', productId, req.root);
@@ -645,21 +747,23 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
       const c = await write('checkout', id, {
         created_at: nowIso(req.occurredAt), modified_at: null,
         status: 'open', client_secret: `polar_checkout_${mintSecret('checkout_client_secret', req, id)}`,
-        url: `https://polar.sh/twin/checkout/${id}`, expires_at: laterIso(req.occurredAt),
+        // the hosted checkout page: at the twin's own address when it is served over HTTP (a person in a walk can open it), else the vendor's
+        url: req.publicBase ? `${req.publicBase}/twin/checkout/${id}` : `https://polar.sh/twin/checkout/${id}`, expires_at: laterIso(req.occurredAt),
         success_url: body.success_url ?? null, embed_origin: body.embed_origin ?? null,
         amount, currency: 'usd', product_id: productId, products,
         customer_id: body.customer_id ?? null, customer_email: body.customer_email ?? null,
         customer_name: body.customer_name ?? null, discount_id: body.discount_id ?? null,
+        external_customer_id: body.external_customer_id ?? null, // your id for the customer: confirm links or creates the customer by it
         metadata: body.metadata ?? {},
       }, 'checkout.create', req);
-      return { status: 201, body: checkoutView({ ...c, type: 'checkout' }) };
+      return { status: 201, body: checkoutView({ ...c, type: 'checkout' }, req.root) };
     }
     if (seg.length === 1 && method === 'GET') {
-      return { status: 200, body: listEnvelope(rows('checkout', req.root).map((c) => checkoutView({ ...c, type: 'checkout' }))) };
+      return { status: 200, body: listEnvelope(rows('checkout', req.root).map((c) => checkoutView({ ...c, type: 'checkout' }, req.root))) };
     }
     if (seg.length === 2 && method === 'GET') {
       const c = getRow('checkout', idAt(1), req.root);
-      return c ? { status: 200, body: checkoutView({ ...c, type: 'checkout' }) } : notFound('Checkout not found.');
+      return c ? { status: 200, body: checkoutView({ ...c, type: 'checkout' }, req.root) } : notFound('Checkout not found.');
     }
     // POST /checkouts/:id/confirm — confirm the checkout: create customer (if needed),
     // subscription/order, and flip the checkout to confirmed (the twin "completes" payment).
@@ -670,6 +774,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
       // Resolve / create the customer.
       let customerId = c.customer_id ? String(c.customer_id) : null;
       const email = body.customer_email ?? c.customer_email ?? null;
+      if (!customerId && c.external_customer_id) customerId = String((await customerForExternalId(String(c.external_customer_id), req, email as string | null)).id);
       if (!customerId && email) {
         const existing = rows('customer', req.root).find((x) => x.email === email);
         if (existing) customerId = String(existing.id);
@@ -686,13 +791,18 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
       const product = c.product_id ? getRow('product', String(c.product_id), req.root) : undefined;
       const recurring = product?.recurring_interval ?? null;
       const at = nowIso(req.occurredAt);
+      // a product with a trial starts the subscription `trialing` with trial_start/trial_end, as Polar does; the first charge comes when the trial ends
+      const trialUnit = product?.trial_interval ? String(product.trial_interval) : null; const trialCount = Number(product?.trial_interval_count ?? 0);
+      const trialMs = trialUnit && trialCount > 0 ? trialCount * (trialUnit === 'day' ? 86_400_000 : trialUnit === 'week' ? 7 * 86_400_000 : trialUnit === 'month' ? 30 * 86_400_000 : 365 * 86_400_000) : 0;
+      const trialEnd = trialMs ? new Date(Date.parse(at) + trialMs).toISOString() : null;
       let subscriptionId: string | null = null;
       if (recurring) {
         subscriptionId = mintId('subscription', req);
         await write('subscription', subscriptionId, {
-          created_at: at, modified_at: null, status: 'active',
+          created_at: at, modified_at: null, status: trialEnd ? 'trialing' : 'active',
           amount: c.amount ?? 0, currency: 'usd', recurring_interval: recurring,
-          current_period_start: at, current_period_end: laterIso(req.occurredAt),
+          current_period_start: at, current_period_end: trialEnd ?? laterIso(req.occurredAt),
+          ...(trialEnd ? { trial_start: at, trial_end: trialEnd } : {}),
           started_at: at, cancel_at_period_end: false, canceled_at: null,
           customer_id: customerId, product_id: c.product_id, checkout_id: c.id, metadata: {},
         }, 'subscription.create', req);
@@ -706,7 +816,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
       }, 'order.create', req);
       await write('checkout', idAt(1), { status: 'confirmed', modified_at: at, customer_id: customerId, subscription_id: subscriptionId }, 'checkout.confirm', req);
       const updated = getRow('checkout', idAt(1), req.root)!;
-      return { status: 200, body: checkoutView({ ...updated, type: 'checkout' }) };
+      return { status: 200, body: checkoutView({ ...updated, type: 'checkout' }, req.root) };
     }
   }
 
@@ -792,7 +902,7 @@ export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarRe
     if (seg.length === 3 && method === 'DELETE') {
       const w = getRow('webhook_endpoint', idAt(2), req.root);
       if (!w) return notFound('Webhook endpoint not found.');
-      await write('webhook_endpoint', idAt(2), { _deleted: true }, 'webhook_endpoint.delete', req);
+      await write('webhook_endpoint', idAt(2), { deleted: true }, 'webhook_endpoint.delete', req);
       return { status: 204, body: null };
     }
   }