@volter/twin-polar 2.0.37 → 3.0.0

package/dist/src/semantics/shared.js

@@ -0,0 +1,327 @@
+/** A customer by its id or its external id. */
+export function customerBy(ctx, key) {
+    return key.id !== undefined ? rowsOf(ctx, CUSTOMER).find((c) => c.id === key.id) : rowsOf(ctx, CUSTOMER).find((c) => c.external_id === key.external);
+}
+export const ORGANIZATION = 'organization';
+export const CUSTOMER = 'customer';
+export const PRODUCT = 'product';
+export const CHECKOUT = 'checkout';
+export const SUBSCRIPTION = 'subscription';
+export const ORDER = 'order';
+export const EVENT = 'event';
+export const METER = 'meter';
+export const SESSION = 'customer_session';
+export const ENDPOINT = 'webhook_endpoint';
+/** Where Polar's hosted pages are: the checkout (`buy.polar.sh`) and the portal (`polar.sh`), rewritten to the twin. */
+export const CHECKOUT_ORIGIN = 'https://buy.polar.sh';
+export const PORTAL_ORIGIN = 'https://polar.sh';
+// ── answers ────────────────────────────────────────────────────────────────────────────────────
+// source: spec:/components/schemas/ResourceNotFound "ResourceNotFound"
+/** Polar's error body: `{ error: <kind>, detail }`. */
+export const fail = (status, error, detail) => Response.json({ error, detail }, { status });
+export const notFound = (what) => fail(404, 'ResourceNotFound', `${what} not found.`);
+/** FastAPI's 422, one error per field. */
+// source: spec:/components/schemas/HTTPValidationError "HTTPValidationError"
+export const invalid = (loc, msg, type = 'value_error') => Response.json({ detail: [{ type, loc: ['body', ...loc], msg, input: null }] }, { status: 422 });
+export const missing = (field) => invalid([field], 'Field required', 'missing');
+export const bodyOf = (ctx) => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? ctx.body : {});
+// ── ids and the organization ───────────────────────────────────────────────────────────────────
+/** A new subject's id: a UUID the kernel mints from the tree (ctx.mint), under the resource the manifest declares for its
+ *  stored type. */
+const DECLARED = { checkout: 'Checkout', subscription: 'Subscription', order: 'Order', webhook_endpoint: 'WebhookEndpoint' };
+export const newId = (ctx, type) => ctx.mint(DECLARED[type] ?? type);
+/** A secret of Polar's form (`polar_cst_…`, `polar_c_…`, `polar_whs_…`, `polar_oat_…`): its prefix and 43 letters and
+ *  digits drawn from a secret the World holds for the seed (ctx.secret), so none is computed from the ids it names. */
+export async function secret(ctx, prefix, seed) {
+    const a = await ctx.secret(`polar-secret:${seed}`);
+    const b = await ctx.secret(`polar-secret:${seed}:2`);
+    return `${prefix}${`${a}${b}`.replace(/[^A-Za-z0-9]/g, '').slice(0, 43)}`;
+}
+/** The World's one organization: the one its token names. */
+export const ORG_ID = '1dbfc517-0bbf-4301-9ba8-555ca42b9737';
+export const orgId = (ctx) => environment(ctx) === 'sandbox' ? '2dbfc517-0bbf-4301-9ba8-555ca42b9737' : ORG_ID;
+export const organizationView = (ctx) => {
+    const o = rowOf(ctx, ORGANIZATION, 'org') ?? {};
+    return {
+        created_at: o.created_at ?? '2026-01-01T00:00:00Z', modified_at: null, id: orgId(ctx), name: o.name ?? 'Twin organization', slug: o.slug ?? 'twin',
+        avatar_url: null, proration_behavior: 'prorate', allow_customer_updates: true, email: null, website: null, socials: [], status: 'active',
+        details_submitted_at: null, onboarding_resubmission_requested_at: null, sso_enforced: false, default_presentment_currency: 'usd',
+        default_tax_behavior: 'location', feature_settings: {}, subscription_settings: { allow_multiple_subscriptions: false, allow_customer_updates: true, proration_behavior: 'prorate', benefit_revocation_grace_period: 0, prevent_trial_abuse: false },
+        customer_email_settings: {}, customer_portal_settings: {}, dispute_settings: {}, embed_hosts: [], embed_hosts_enforced: false, account_id: null, payout_account_id: null, capabilities: {},
+    };
+};
+// ── views: each object with every field its schema requires ───────────────────────────────────
+/** Whether a row's field is among the values a list's query names (one value or several), or the query names none. */
+export const among = (ctx, key, value) => ctx.params[key] === undefined || [].concat(ctx.params[key]).map(String).includes(String(value));
+/** Newest first by a timestamp field. */
+export const newest = (field) => (a, b) => String(b[field]).localeCompare(String(a[field]));
+/** Stored rows without the kernel's bookkeeping. */
+export const environment = (ctx) => new URL(ctx.call.request.url).hostname.startsWith('sandbox') ? 'sandbox' : 'production';
+export const rowsOf = (ctx, type) => ctx.rowsRaw(type).filter((r) => r.deleted !== true && (r._environment ?? (r.organization_id === '2dbfc517-0bbf-4301-9ba8-555ca42b9737' ? 'sandbox' : 'production')) === environment(ctx));
+export const rowOf = (ctx, type, id) => rowsOf(ctx, type).find((r) => r.id === id);
+/** The stored vendor shape; bookkeeping is private, including the environment boundary. */
+export const vendorFields = (ctx, row) => Object.fromEntries(Object.entries(ctx.own(row)).filter(([k]) => !k.startsWith('_')));
+export const customerView = (ctx, c) => vendorFields(ctx, c);
+export const productView = (ctx, p) => vendorFields(ctx, p);
+export const subscriptionView = (ctx, s) => vendorFields(ctx, s);
+export const orderView = (ctx, o) => vendorFields(ctx, o);
+export const eventView = (ctx, e) => vendorFields(ctx, e);
+export const checkoutView = (ctx, c) => vendorFields(ctx, c);
+// source: spec:/components/schemas/CustomerIndividual "CustomerIndividual"
+export function customerFields(ctx, c) {
+    return {
+        id: c.id, created_at: c.created_at, modified_at: c.modified_at ?? null, metadata: c.metadata ?? {}, external_id: c.external_id ?? null,
+        email: c.email, email_verified: c.email_verified ?? false, type: 'individual', name: c.name ?? null, billing_name: c.billing_name ?? null,
+        billing_address: c.billing_address ?? null, tax_id: c.tax_id ?? null, locale: c.locale ?? null, organization_id: orgId(ctx),
+        default_payment_method_id: null, deleted_at: c.deleted_at ?? null, first_user_event_at: c.first_user_event_at ?? null,
+        avatar_url: `https://www.gravatar.com/avatar/${String(c.email ?? '')}?d=404`,
+    };
+}
+/** A price as the schema of its amount type requires (ProductPriceFixed, ProductPriceFree, ProductPriceCustom,
+ *  ProductPriceMeteredUnit). */
+// source: spec:/components/schemas/ProductPriceFixed "ProductPriceFixed"
+export function priceView(ctx, p, product) {
+    const base = {
+        created_at: product.created_at, modified_at: null, id: p.id, source: p.source ?? 'catalog', amount_type: p.amount_type, price_currency: p.price_currency ?? 'usd',
+        tax_behavior: null, is_archived: p.is_archived ?? false, product_id: product.id,
+    };
+    if (p.amount_type === 'fixed')
+        return { ...base, price_amount: p.price_amount };
+    if (p.amount_type === 'custom')
+        return { ...base, minimum_amount: p.minimum_amount ?? null, maximum_amount: p.maximum_amount ?? null, preset_amount: p.preset_amount ?? null };
+    if (p.amount_type !== 'metered_unit')
+        return base;
+    const meter = rowOf(ctx, METER, String(p.meter_id));
+    // source: spec:/components/schemas/ProductPriceMeter "A meter associated to a metered price."
+    // source: spec:/components/schemas/MeterCreate/properties/unit "scalar"
+    return { ...base, unit_amount: String(p.unit_amount ?? '0'), cap_amount: p.cap_amount ?? null, meter_id: p.meter_id,
+        meter: { id: p.meter_id, name: meter?.name ?? '', unit: meter?.unit ?? 'scalar', custom_label: meter?.custom_label ?? null, custom_multiplier: meter?.custom_multiplier ?? null } };
+}
+// source: spec:/components/schemas/Product "Product"
+export function productFields(ctx, p) {
+    return {
+        id: p.id, created_at: p.created_at, modified_at: p.modified_at ?? null, trial_interval: p.trial_interval ?? null, trial_interval_count: p.trial_interval_count ?? null,
+        name: p.name, description: p.description ?? null, visibility: p.visibility ?? 'public', recurring_interval: p.recurring_interval ?? null,
+        recurring_interval_count: p.recurring_interval ? Number(p.recurring_interval_count ?? 1) : null, meter_interval: null, meter_interval_count: null,
+        is_recurring: p.recurring_interval != null, is_archived: p.is_archived ?? false, organization_id: orgId(ctx), metadata: p.metadata ?? {},
+        prices: p.prices ?? [],
+        benefits: [],
+        medias: [], attached_custom_fields: [],
+    };
+}
+// source: spec:/components/schemas/Subscription "Subscription"
+export function subscriptionFields(ctx, s) {
+    const customer = rowOf(ctx, CUSTOMER, String(s.customer_id));
+    const product = rowOf(ctx, PRODUCT, String(s.product_id));
+    return {
+        created_at: s.created_at, modified_at: s.modified_at ?? null, id: s.id, amount: s.amount ?? 0, currency: s.currency ?? 'usd',
+        recurring_interval: s.recurring_interval, recurring_interval_count: Number(s.recurring_interval_count ?? 1), status: s.status,
+        current_period_start: s.current_period_start, current_period_end: s.current_period_end ?? null, current_meter_period_start: null, current_meter_period_end: null,
+        trial_start: s.trial_start ?? null, trial_end: s.trial_end ?? null, cancel_at_period_end: s.cancel_at_period_end ?? false, canceled_at: s.canceled_at ?? null,
+        started_at: s.started_at ?? null, ends_at: s.ends_at ?? null, ended_at: s.ended_at ?? null, pause_at_period_end: false, paused_at: null, resumes_at: null,
+        customer_id: s.customer_id, product_id: s.product_id, discount_id: s.discount_id ?? null, checkout_id: s.checkout_id ?? null,
+        customer_cancellation_reason: s.customer_cancellation_reason ?? null, customer_cancellation_comment: s.customer_cancellation_comment ?? null,
+        metadata: s.metadata ?? {}, custom_field_data: {},
+        customer: customer ? customerView(ctx, customer) : null, product: product ? productView(ctx, product) : null, discount: null,
+        prices: s.prices ?? product?.prices ?? [], meters: s.meters ?? [], pending_update: null,
+    };
+}
+// source: spec:/components/schemas/Order "Order"
+export function orderFields(ctx, o) {
+    const customer = rowOf(ctx, CUSTOMER, String(o.customer_id));
+    const product = o.product_id ? rowOf(ctx, PRODUCT, String(o.product_id)) : undefined;
+    const sub = o.subscription_id ? rowOf(ctx, SUBSCRIPTION, String(o.subscription_id)) : undefined;
+    const total = Number(o.total_amount ?? 0);
+    const refunded = Number(o.refunded_amount ?? 0);
+    return {
+        id: o.id, created_at: o.created_at, modified_at: o.modified_at ?? null, status: o.status, paid: o.status !== 'pending',
+        subtotal_amount: total, discount_amount: 0, net_amount: total, tax_amount: 0, total_amount: total, applied_balance_amount: 0, due_amount: 0,
+        refunded_amount: refunded, refunded_tax_amount: 0, currency: o.currency ?? 'usd', billing_reason: o.billing_reason, billing_name: null, billing_address: null,
+        invoice_number: `TWIN-${String(o.number ?? 1).padStart(4, '0')}`, is_invoice_generated: false, receipt_number: null,
+        customer_id: o.customer_id, product_id: o.product_id ?? null, discount_id: null, subscription_id: o.subscription_id ?? null, checkout_id: o.checkout_id ?? null,
+        metadata: o.metadata ?? {}, custom_field_data: {}, platform_fee_amount: 0, platform_fee_currency: null,
+        customer: customer ? customerView(ctx, customer) : null,
+        product: product ? (({ prices: _p, benefits: _b, medias: _m, attached_custom_fields: _a, ...rest }) => rest)(productView(ctx, product)) : null,
+        discount: null, subscription: sub ? (({ customer: _c, product: _pr, discount: _d, prices: _ps, meters: _ms, pending_update: _u, ...rest }) => rest)(subscriptionView(ctx, sub)) : null,
+        items: o.items ?? [],
+        description: product?.name ?? 'Order', refundable_amount: total - refunded, refundable_tax_amount: 0,
+    };
+}
+/** A usage event as the API answers it (UserEvent): with its customer. */
+// source: spec:/components/schemas/UserEvent "An event you created through the ingestion API."
+// Where the documentation stops: a user event's `label` (its type's "human readable label"); the twin gives its name
+export function eventFields(ctx, e) {
+    const customer = e.customer_id ? rowOf(ctx, CUSTOMER, String(e.customer_id)) : undefined;
+    return {
+        id: e.id, timestamp: e.timestamp, organization_id: orgId(ctx), customer_id: e.customer_id ?? null, customer: customer && customer.deleted !== true ? customerView(ctx, customer) : null,
+        external_customer_id: e.external_customer_id ?? null, member_id: null, external_member_id: null, child_count: 0, parent_id: null,
+        label: e.name, name: e.name, source: 'user', metadata: e.metadata ?? {},
+    };
+}
+// source: spec:/components/schemas/Checkout "Checkout"
+export function checkoutFields(ctx, c) {
+    const product = rowOf(ctx, PRODUCT, String(c.product_id));
+    const pv = product ? productView(ctx, product) : null;
+    const prices = c.prices?.[String(c.product_id)] ?? pv?.prices ?? [];
+    const price = prices.find((p) => p.id === c.product_price_id) ?? prices[0] ?? null;
+    const amount = Number(c.amount ?? 0);
+    return {
+        id: c.id, created_at: c.created_at, modified_at: c.modified_at ?? null, payment_processor: 'stripe', status: c.status, client_secret: c.client_secret,
+        url: `${CHECKOUT_ORIGIN}/${String(c.client_secret)}`, expires_at: c.expires_at, success_url: c.success_url ?? `${CHECKOUT_ORIGIN}/${String(c.client_secret)}/confirmation`,
+        return_url: c.return_url ?? null, embed_origin: c.embed_origin ?? null, amount, discount_amount: 0, net_amount: amount, tax_amount: null, tax_behavior: null,
+        total_amount: amount, currency: c.currency ?? 'usd', allow_trial: c.allow_trial ?? null, active_trial_interval: product?.trial_interval ?? null, active_trial_interval_count: product?.trial_interval_count ?? null,
+        trial_end: null, organization_id: orgId(ctx), product_id: c.product_id, product_price_id: price?.id ?? null, discount_id: null, allow_discount_codes: c.allow_discount_codes ?? true,
+        require_billing_address: c.require_billing_address ?? false, is_discount_applicable: false, is_free_product_price: amount === 0, is_payment_required: amount > 0,
+        is_payment_setup_required: pv?.is_recurring === true, is_payment_form_required: amount > 0, customer_id: c.customer_id ?? null, is_business_customer: c.is_business_customer ?? false,
+        customer_name: c.customer_name ?? null, customer_email: c.customer_email ?? null, customer_ip_address: c.customer_ip_address ?? null, customer_billing_name: null,
+        customer_billing_address: null, customer_tax_id: null, payment_method_type: null, payment_processor_metadata: {},
+        billing_address_fields: { country: 'required', state: 'disabled', city: 'disabled', postal_code: 'disabled', line1: 'disabled', line2: 'disabled' },
+        trial_interval: null, trial_interval_count: null, metadata: c.metadata ?? {}, external_customer_id: c.external_customer_id ?? null, custom_field_data: {},
+        products: pv ? [pv] : [], product: pv, product_price: price, prices: pv ? { [String(pv.id)]: prices } : {}, discount: null,
+        subscription_id: c.subscription_id ?? null, attached_custom_fields: [], customer_metadata: c.customer_metadata ?? {},
+    };
+}
+// ── a customer's meters ────────────────────────────────────────────────────────────────────────
+/** Whether a meter's filter admits an event: clauses on `name`, `source` or a metadata key, joined by the filter's
+ *  conjunction, nested filters among them. */
+// source: spec:/components/schemas/Filter "Filter"
+export function admits(filter, e) {
+    const clauses = filter?.clauses ?? [];
+    if (clauses.length === 0)
+        return true;
+    const one = (c) => {
+        if ('clauses' in c)
+            return admits(c, e);
+        const prop = String(c.property ?? '');
+        const actual = prop === 'name' || prop === 'source' ? e[prop] : (e.metadata ?? {})[prop.replace(/^metadata\./, '')];
+        const want = c.value;
+        switch (String(c.operator ?? 'eq')) {
+            case 'eq': return String(actual) === String(want);
+            default: return compareClause(String(c.operator), actual, want);
+        }
+    };
+    return String(filter?.conjunction ?? 'and') === 'or' ? clauses.some(one) : clauses.every(one);
+}
+/** A meter's aggregation over the events it admits: a count, or the sum, max, min or average of a metadata property. */
+// source: spec:/components/schemas/PropertyAggregation "PropertyAggregation"
+export function aggregate(agg, events) {
+    const func = String(agg?.func ?? 'count');
+    if (func === 'count')
+        return events.length;
+    const prop = String(agg?.property ?? '').replace(/^metadata\./, '');
+    // source: https://polar.sh/docs/features/usage-based-billing/meters "Counts the number of unique values of a property."
+    if (func === 'unique')
+        return new Set(events.map((e) => (e.metadata ?? {})[prop])).size;
+    const values = events.map((e) => Number((e.metadata ?? {})[prop])).filter(Number.isFinite);
+    if (values.length === 0)
+        return 0;
+    if (func === 'max')
+        return Math.max(...values);
+    if (func === 'min')
+        return Math.min(...values);
+    const sum = values.reduce((a, b) => a + b, 0);
+    return func === 'avg' ? sum / values.length : sum;
+}
+/** A customer's meter: consumed (the fold over its events), credited (its meter-credit grants), and the balance. */
+// source: spec:/components/schemas/CustomerStateMeter "The balance of the meter, i.e. the difference between credited and consumed units."
+export function customerMeter(ctx, customerId, meter) {
+    const events = rowsOf(ctx, EVENT).filter((e) => e.customer_id === customerId && admits(meter.filter, e));
+    const consumed = aggregate(meter.aggregation, events);
+    const credited = 0; // No demanded product grants meter credits; benefits are outside the served surface.
+    return { consumed, credited, balance: credited - consumed };
+}
+/** A customer's state: its active subscriptions, granted benefits and meters. */
+// source: spec:customers:get_state "The customer state includes information about the customer's active subscriptions and benefits."
+export async function customerState(ctx, c) {
+    const id = String(c.id);
+    for (const meter of rowsOf(ctx, METER)) {
+        if (!rowsOf(ctx, '_customer_meter').some((r) => r.customer_id === id && r.meter_id === meter.id)) {
+            const meterId = ctx.mint('_customer_meter');
+            await ctx.record('_customer_meter', { id: meterId, customer_id: id, meter_id: meter.id, _environment: environment(ctx) }, meterId);
+        }
+    }
+    const subs = rowsOf(ctx, SUBSCRIPTION).filter((s) => s.customer_id === id && (s.status === 'active' || s.status === 'trialing'));
+    return {
+        ...customerView(ctx, c),
+        active_subscriptions: subs.map((s) => {
+            const v = subscriptionView(ctx, s);
+            return { id: v.id, created_at: v.created_at, modified_at: v.modified_at, metadata: v.metadata, status: v.status, amount: v.amount, currency: v.currency, recurring_interval: v.recurring_interval, current_period_start: v.current_period_start, current_period_end: v.current_period_end, trial_start: v.trial_start, trial_end: v.trial_end, cancel_at_period_end: v.cancel_at_period_end, canceled_at: v.canceled_at, started_at: v.started_at, ends_at: v.ends_at, product_id: v.product_id, discount_id: v.discount_id, meters: [], custom_field_data: {} };
+        }),
+        granted_benefits: [],
+        active_meters: rowsOf(ctx, METER).map((m) => {
+            const { consumed, credited, balance } = customerMeter(ctx, id, m);
+            return { id: rowsOf(ctx, '_customer_meter').find((r) => r.customer_id === id && r.meter_id === m.id).id, created_at: m.created_at, modified_at: null, meter_id: m.id, consumed_units: consumed, credited_units: credited, balance };
+        }),
+    };
+}
+// source: https://polar.sh/docs/features/subscriptions/introduction "creates a new order"
+export async function makeOrder(ctx, source, reason, period) {
+    const id = newId(ctx, ORDER);
+    const number = Number(ctx.mint('_seq_order'));
+    await ctx.record('_seq_order', {}, String(number));
+    const product = rowOf(ctx, PRODUCT, String(source.product_id));
+    const prices = (source.prices && !Array.isArray(source.prices) ? source.prices[String(product.id)] : source.prices);
+    const items = [];
+    for (const price of prices ?? product.prices) {
+        let amount = price.amount_type === 'fixed' ? Number(price.price_amount) : price.amount_type === 'custom' ? Number(source.amount ?? 0) : 0;
+        // source: spec:/components/schemas/ProductPriceMeteredUnit/properties/unit_amount "The price per unit in cents."
+        // source: https://polar.sh/docs/features/usage-based-billing/event-ingestion "Polar never issues retroactive invoices or credits for late events."
+        if (price.amount_type === 'metered_unit' && period) {
+            const meter = rowOf(ctx, METER, String(price.meter_id));
+            const events = rowsOf(ctx, EVENT).filter((e) => e.customer_id === source.customer_id && String(e._received_at ?? e.timestamp) >= period.start && String(e._received_at ?? e.timestamp) < period.end && admits(meter.filter, e));
+            amount = Math.ceil(aggregate(meter.aggregation, events) * Number(price.unit_amount));
+            if (price.cap_amount != null)
+                amount = Math.min(amount, Number(price.cap_amount));
+        }
+        const itemId = ctx.mint('_order_item');
+        await ctx.record('_order_item', {}, itemId);
+        items.push({ id: itemId, created_at: ctx.occurredAt, modified_at: null, label: product.name, amount, tax_amount: 0, proration: false, product_price_id: price.id });
+    }
+    const total = items.reduce((n, item) => n + Number(item.amount), 0);
+    const fields = orderFields(ctx, {
+        id, created_at: ctx.occurredAt, modified_at: null, status: 'pending', total_amount: total, currency: source.currency ?? 'usd', refunded_amount: 0,
+        billing_reason: reason, customer_id: source.customer_id, product_id: source.product_id, subscription_id: source.subscription_id ?? null,
+        checkout_id: source.checkout_id ?? source.id, metadata: source.metadata ?? {}, number, items,
+    });
+    await ctx.write(ORDER, id, { ...fields, _environment: environment(ctx) }, 'order.create');
+    await ctx.write(ORDER, id, { status: 'paid', paid: true, modified_at: ctx.occurredAt }, 'order.pay');
+}
+// source: https://polar.sh/docs/features/subscriptions/introduction "Daily, weekly, monthly or yearly."
+export function addInterval(at, interval, count) {
+    const d = new Date(at);
+    if (interval === 'day' || interval === 'week')
+        d.setUTCDate(d.getUTCDate() + count * (interval === 'week' ? 7 : 1));
+    else {
+        const day = d.getUTCDate();
+        d.setUTCDate(1);
+        if (interval === 'year')
+            d.setUTCFullYear(d.getUTCFullYear() + count);
+        else
+            d.setUTCMonth(d.getUTCMonth() + count);
+        const last = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+        d.setUTCDate(Math.min(day, last));
+    }
+    return d.toISOString();
+}
+// source: https://polar.sh/docs/features/usage-based-billing/meters "Operators are the operators that you want to use to filter the events."
+function compareClause(operator, actual, want) {
+    switch (operator) {
+        case 'ne': return 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;
+    }
+}
+// source: spec:/components/schemas/CustomerSession "CustomerSession"
+export async function createSession(ctx, customer, returnUrl = null) {
+    const id = newId(ctx, SESSION);
+    const token = await secret(ctx, 'polar_cst_', `session:${id}`);
+    const fields = { id, created_at: ctx.occurredAt, modified_at: null, token, expires_at: new Date(Date.parse(ctx.occurredAt) + 3_600_000).toISOString(), return_url: returnUrl,
+        customer_portal_url: `${PORTAL_ORIGIN}/${String(organizationView(ctx).slug)}/portal?customer_session_token=${token}`, customer_id: customer.id, customer: customerView(ctx, customer) };
+    await ctx.write(SESSION, id, { ...fields, _environment: environment(ctx) }, 'customer_session.create');
+    return fields;
+}

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

@@ -0,0 +1,27 @@
+import type { StateField } from '@volter/world-core';
+export declare const states: {
+    Checkout: {
+        state: {
+            status: StateField;
+        };
+        notState: string[];
+    };
+    Subscription: {
+        state: {
+            status: StateField;
+        };
+        notState: string[];
+    };
+    Order: {
+        state: {
+            status: StateField;
+        };
+        notState: string[];
+    };
+    Meter: {
+        notState: string[];
+    };
+    WebhookEndpoint: {
+        notState: string[];
+    };
+};

package/dist/src/semantics/states.js

@@ -0,0 +1,43 @@
+/** A checkout's status: open until the customer confirms it on the hosted page (an outside party), then Polar takes the
+ *  payment; it expires 24 hours after it was made. */
+// source: spec:/components/schemas/CheckoutStatus "succeeded"
+const checkoutStatus = {
+    initial: 'open',
+    transitions: [
+        {
+            operation: 'checkouts:client_confirm', actor: 'external', from: ['open'], to: 'confirmed',
+            source: 'spec:checkouts:client_confirm "The checkout is expired, the customer already has an active subscription, or the organization is not ready to accept payments."',
+        },
+        { operation: 'checkouts:client_confirm', actor: 'external', from: ['confirmed', 'succeeded', 'failed', 'expired'], refusal: { status: 403, code: 'CheckoutForbiddenError', message: 'The checkout is expired, the customer already has an active subscription, or the organization is not ready to accept payments.' }, source: 'spec:checkouts:client_confirm "The checkout is expired, the customer already has an active subscription, or the organization is not ready to accept payments."' },
+        { actor: 'vendor', from: ['confirmed'], to: 'succeeded', source: 'spec:checkouts:client_confirm "Orders and subscriptions will be processed."' },
+        { actor: 'time', from: ['open'], to: 'expired', source: 'spec:checkouts:client_confirm "The checkout session is expired."' },
+    ],
+};
+/** A subscription's status: it starts incomplete until its first payment (active, or trialing through a trial), and is
+ *  canceled when its period ends after a cancellation. No operation the twin serves moves it further: the
+ *  subscriptions' API (update, revoke) is the gap, no application of the demand calling it. */
+// source: spec:/components/schemas/SubscriptionStatus "incomplete"
+const subscriptionStatus = {
+    initial: 'incomplete',
+    transitions: [
+        { operation: 'checkouts:client_confirm', actor: 'external', from: ['active', 'trialing'], refusal: { status: 403, code: 'CheckoutForbiddenError', message: 'The customer already has an active subscription.' }, source: 'spec:checkouts:client_confirm "the customer already has an active subscription"' },
+        { actor: 'vendor', from: ['incomplete'], to: 'active', source: 'spec:/components/schemas/SubscriptionStatus "active"' },
+        { actor: 'vendor', from: ['incomplete'], to: 'trialing', source: 'spec:/components/schemas/SubscriptionStatus "trialing"' },
+        { actor: 'time', from: ['trialing'], to: 'active', 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."' },
+    ],
+};
+/** An order's status: pending until paid; a refund moves a paid order. */
+// source: spec:/components/schemas/OrderStatus "partially_refunded"
+const orderStatus = {
+    initial: 'pending',
+    transitions: [
+        { actor: 'vendor', from: ['pending'], to: 'paid', source: 'spec:/components/schemas/OrderStatus "paid"' },
+    ],
+};
+export const states = {
+    Checkout: { state: { status: checkoutStatus }, notState: ['is_business_customer', 'is_discount_applicable', 'is_free_product_price', 'is_payment_form_required', 'is_payment_required', 'is_payment_setup_required'] },
+    Subscription: { state: { status: subscriptionStatus }, notState: ['recurring_interval', 'cancel_at_period_end'] },
+    Order: { state: { status: orderStatus }, notState: ['billing_reason', 'is_invoice_generated', 'paid'] },
+    Meter: { notState: ['unit'] },
+    WebhookEndpoint: { notState: ['format'] },
+};

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

@@ -0,0 +1,4 @@
+import type { HandlerContext } from '@volter/world-core';
+/** `GET /v1/subscriptions/`: the organization's subscriptions, the latest started first, by customer (Polar's id or the
+ *  application's), product or status. */
+export declare function subscriptions_list(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/subscriptions.js

@@ -0,0 +1,15 @@
+import { among, customerBy, newest, rowsOf, SUBSCRIPTION, subscriptionView } from "./shared.js";
+/** `GET /v1/subscriptions/`: the organization's subscriptions, the latest started first, by customer (Polar's id or the
+ *  application's), product or status. */
+// source: spec:subscriptions:list "List subscriptions."
+export async function subscriptions_list(ctx) {
+    const external = ctx.params.external_customer_id === undefined ? undefined : [].concat(ctx.params.external_customer_id).map((x) => String(customerBy(ctx, { external: String(x) })?.id));
+    // source: spec:subscriptions:list "Filter by active or inactive subscription."
+    const active = ctx.params.active === undefined ? undefined : String(ctx.params.active) === 'true';
+    const rows = rowsOf(ctx, SUBSCRIPTION)
+        .filter((s) => among(ctx, 'customer_id', s.customer_id) && among(ctx, 'product_id', s.product_id) && among(ctx, 'status', s.status))
+        .filter((s) => external === undefined || external.includes(String(s.customer_id)))
+        .filter((s) => active === undefined || ['trialing', 'active', 'past_due'].includes(String(s.status)) === active)
+        .sort(newest('started_at'));
+    return ctx.list('Subscription', rows.map((s) => subscriptionView(ctx, s)));
+}

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

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function tenant(ctx: HandlerContext): string;

package/dist/src/semantics/tenant.js

@@ -0,0 +1,2 @@
+import { orgId } from "./shared.js";
+export function tenant(ctx) { return orgId(ctx); }

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

@@ -0,0 +1,4 @@
+import type { HandlerContext } from '@volter/world-core';
+/** `POST /v1/webhooks/endpoints`: an endpoint for the events named, its signing secret drawn from the World
+ *  (`polar_whs_`, ctx.secret) and answered. */
+export declare function webhooks_create_webhook_endpoint(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/webhooks.js

@@ -0,0 +1,30 @@
+import { bodyOf, environment, ENDPOINT, invalid, missing, newId, orgId, secret } from "./shared.js";
+const FORMATS = ['raw', 'discord', 'slack'];
+/** `POST /v1/webhooks/endpoints`: an endpoint for the events named, its signing secret drawn from the World
+ *  (`polar_whs_`, ctx.secret) and answered. */
+// source: spec:webhooks:create_webhook_endpoint "Create a webhook endpoint."
+export async function webhooks_create_webhook_endpoint(ctx) {
+    const body = bodyOf(ctx);
+    // source: spec:/components/schemas/WebhookEndpointCreate "The URL where the webhook events will be sent."
+    if (typeof body.url !== 'string' || body.url === '')
+        return missing('url');
+    if (!/^https?:\/\/[^\s]+$/.test(body.url))
+        return invalid(['url'], 'Input should be a valid URL', 'url_parsing');
+    // source: spec:/components/schemas/WebhookFormat "WebhookFormat"
+    if (body.format === undefined)
+        return missing('format');
+    if (!FORMATS.includes(String(body.format)))
+        return invalid(['format'], "Input should be 'raw', 'discord' or 'slack'", 'enum');
+    // source: spec:/components/schemas/WebhookEndpointCreate "The events that will trigger the webhook."
+    if (!Array.isArray(body.events))
+        return missing('events');
+    const id = newId(ctx, ENDPOINT);
+    const signing = await secret(ctx, 'polar_whs_', `endpoint:${id}`);
+    const endpoint = {
+        created_at: ctx.occurredAt, modified_at: null, id, url: body.url, name: body.name ?? null, format: body.format, secret: signing,
+        organization_id: orgId(ctx), events: body.events, enabled: true,
+    };
+    await ctx.write(ENDPOINT, id, { ...endpoint, _environment: environment(ctx) }, 'webhook_endpoint.create');
+    // source: spec:/components/schemas/WebhookEndpoint "The secret used to sign the webhook events."
+    return Response.json(endpoint, { status: 201 });
+}

package/dist/src/server.d.ts

@@ -0,0 +1,7 @@
+import { type PackFetchOptions } from '@volter/world-core';
+export declare function createPolarTwinServer(options?: PackFetchOptions & {
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/server.js

@@ -0,0 +1,7 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp } from '@volter/world-core';
+import { createPolarFetch } from "./fetch.js";
+export async function createPolarTwinServer(options = {}) {
+    const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createPolarFetch(options) });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/generated/pack-facts.json

@@ -0,0 +1,69 @@
+{
+  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
+  "packs": {
+    "polar": {
+      "adoption": {
+        "sdks": [
+          "@polar-sh/sdk"
+        ],
+        "pypi": [
+          "polar-sdk"
+        ],
+        "scopes": [
+          "@polar-sh/"
+        ],
+        "envStems": [
+          "POLAR"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "api.polar.sh"
+        },
+        {
+          "host": "sandbox-api.polar.sh"
+        },
+        {
+          "host": "buy.polar.sh"
+        },
+        {
+          "host": "polar.sh",
+          "pathPattern": "^/[^/]+/portal"
+        },
+        {
+          "host": "sandbox.polar.sh"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "customer",
+        "product",
+        "checkout",
+        "subscription",
+        "order",
+        "event",
+        "meter",
+        "customer_session",
+        "webhook_endpoint"
+      ],
+      "endpointEnvNone": "@polar-sh/sdk reads no base-URL variable: its `server` option picks production or sandbox, both claimed by the host rules.",
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "POLAR_ACCESS_TOKEN": "access_token",
+          "POLAR_API_KEY": "access_token",
+          "POLAR_ORGANIZATION_TOKEN": "access_token"
+        }
+      },
+      "serveExport": "createPolarTwinServer"
+    }
+  },
+  "undeclared": []
+}