@volter/twin-polar 2.0.37 → 3.0.0

package/dist/src/semantics/doors.js

@@ -0,0 +1,47 @@
+// The World's doors (docs/contributing/architecture.md, "Doors, screens and the gap"), each declared in the manifest's
+// `doors`: the organization's access tokens, as its settings page makes them (the API makes none), and the webhooks
+// the World sent the application's server, as that server received them.
+import { sha256 } from '@volter/world-core';
+import { bodyOf, environment, secret } from "./shared.js";
+/** An Organization Access Token as the settings page makes it (`polar_oat_…`, shown once): its name, scopes and
+ *  expiration (none: it does not expire), kept by its SHA-256. */
+// source: spec:/components/securitySchemes/oat "You can generate an **Organization Access Token** from your organization's settings."
+async function makeToken(ctx, comment, expiresInDays) {
+    const id = ctx.mint('_access_token');
+    const token = await secret(ctx, 'polar_oat_', `access-token:${id}`);
+    await ctx.record('_access_token', { comment, _environment: environment(ctx), _sha256: sha256(token), created_at: ctx.occurredAt, expires_at: expiresInDays === null ? null : new Date(Date.parse(ctx.occurredAt) + expiresInDays * 86_400_000).toISOString(), deleted: false }, id);
+    return { token, id };
+}
+/** POST /_twin/access-tokens {comment, expires_in_days?}: an Organization Access Token made on the settings page. */
+export async function accessTokens(ctx) {
+    const b = bodyOf(ctx);
+    const days = typeof b.expires_in_days === 'number' ? b.expires_in_days : null;
+    return Response.json(await makeToken(ctx, typeof b.comment === 'string' ? b.comment : 'token', days), { status: 201 });
+}
+/** DELETE /_twin/access-tokens/{n}: a token revoked on the settings page. */
+export async function revokeToken(ctx) {
+    const id = String(ctx.call.params.n);
+    if (!ctx.rowsRaw('_access_token').some((t) => t.id === id && t.deleted !== true))
+        return Response.json({ error: 'no such token' }, { status: 404 });
+    await ctx.record('_access_token', { deleted: true }, id);
+    return new Response(null, { status: 204 });
+}
+/** POST /_twin/app-credentials: the access token an application holds, as the runtime issues it (the descriptor's
+ *  credentialDoor). */
+export async function appCredentials(ctx) {
+    // the application's one token, made the first time the runtime asks and the same at every boot after
+    const token = await secret(ctx, 'polar_oat_', `access-token:app:${environment(ctx)}`);
+    if (!ctx.rowsRaw('_access_token', { withDeleted: true }).some((t) => t.id === `oat_app_${environment(ctx)}` && t._sha256 === sha256(token))) {
+        await ctx.record('_access_token', { comment: 'world', _environment: environment(ctx), _sha256: sha256(token), created_at: ctx.occurredAt, expires_at: null, deleted: false }, `oat_app_${environment(ctx)}`);
+    }
+    return Response.json({ access_token: token }, { status: 201 });
+}
+/** 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 async function deliveries(ctx) {
+    const q = new URL(ctx.call.request.url).searchParams;
+    const rows = ctx.rowsRaw('_webhook_delivery')
+        .filter((d) => (q.get('to') === null || d.url === q.get('to')) && (q.get('type') === null || d.event_type === q.get('type')))
+        .sort((a, b) => Number(a.sent_at) - Number(b.sent_at));
+    return Response.json({ data: rows.map((d) => ({ url: d.url, type: d.event_type, sent_at: d.sent_at, headers: d.headers, body: JSON.parse(String(d.body)) })) });
+}

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

@@ -0,0 +1,12 @@
+import type { EventWrite, HandlerContext, WriteHookContext } from '@volter/world-core';
+/** `POST /v1/events/ingest`: a batch of events. An event's `external_id` is the application's id for it: a second
+ *  ingest of it is a duplicate, not a second event. An `external_customer_id` names the customer by the application's
+ *  id; it does not create an unresolved customer. */
+export declare function events_ingest(ctx: HandlerContext): Promise<Response>;
+/** `GET /v1/events/`: the organization's events, newest first, by customer (Polar's id or the application's), name,
+ *  source, a meter's filter, or a time window. */
+export declare function events_list(ctx: HandlerContext): Promise<Response>;
+/** A webhook's `data`: the written object as the API answers it. */
+export declare function data(ctx: WriteHookContext, write: EventWrite): Record<string, unknown>;
+/** Private routing value: sandbox endpoints only receive sandbox writes. */
+export declare function values(ctx: WriteHookContext): Record<string, unknown>;

package/dist/src/semantics/events.js

@@ -0,0 +1,60 @@
+import { rowOf, admits, among, bodyOf, eventFields, environment, CHECKOUT, checkoutView, customerBy, EVENT, eventView, invalid, METER, missing, newest, newId, notFound, orderView, rowsOf, } from "./shared.js";
+/** `POST /v1/events/ingest`: a batch of events. An event's `external_id` is the application's id for it: a second
+ *  ingest of it is a duplicate, not a second event. An `external_customer_id` names the customer by the application's
+ *  id; it does not create an unresolved customer. */
+// source: spec:events:ingest "Ingest batch of events."
+export async function events_ingest(ctx) {
+    const events = bodyOf(ctx).events;
+    if (!Array.isArray(events))
+        return missing('events');
+    // Validate the complete batch before mutating it. External identities may remain unresolved.
+    // source: spec:events:ingest "Validation Error"
+    for (const [i, e] of events.entries()) {
+        if (!e || typeof e.name !== 'string')
+            return invalid(['events', i, 'name'], 'Field required', 'missing');
+        if (e.customer_id !== undefined && !customerBy(ctx, { id: e.customer_id }))
+            return invalid(['events', i, 'customer_id'], 'Customer does not exist.');
+    }
+    let inserted = 0;
+    let duplicates = 0;
+    for (const e of events) {
+        if (e.external_id != null && rowsOf(ctx, '_event_key').some((x) => x.external_id === e.external_id)) {
+            duplicates += 1;
+            continue;
+        }
+        const customer = e.customer_id !== undefined ? customerBy(ctx, { id: e.customer_id }) : e.external_customer_id !== undefined ? customerBy(ctx, { external: e.external_customer_id }) : undefined;
+        const id = newId(ctx, EVENT);
+        await ctx.write(EVENT, id, { ...eventFields(ctx, { id, timestamp: e.timestamp ?? ctx.occurredAt, name: e.name, customer_id: customer?.id ?? null, external_customer_id: e.external_customer_id ?? null, metadata: e.metadata ?? {} }), _environment: environment(ctx), _received_at: ctx.occurredAt }, 'event.ingest');
+        if (e.external_id != null)
+            await ctx.record('_event_key', { external_id: e.external_id, _environment: environment(ctx) });
+        inserted += 1;
+    }
+    return Response.json({ inserted, duplicates });
+}
+/** `GET /v1/events/`: the organization's events, newest first, by customer (Polar's id or the application's), name,
+ *  source, a meter's filter, or a time window. */
+// source: spec:events:list "List events."
+export async function events_list(ctx) {
+    const meter = ctx.params.meter_id === undefined ? undefined : rowOf(ctx, METER, String(ctx.params.meter_id));
+    if (ctx.params.meter_id !== undefined && (!meter || meter.deleted === true))
+        return notFound('Meter');
+    // source: spec:events:list "Filter events after this timestamp."
+    const after = ctx.params.start_timestamp === undefined ? undefined : Date.parse(String(ctx.params.start_timestamp));
+    const before = ctx.params.end_timestamp === undefined ? undefined : Date.parse(String(ctx.params.end_timestamp));
+    const q = String(ctx.params.query ?? '').toLowerCase();
+    const rows = rowsOf(ctx, EVENT)
+        .filter((e) => among(ctx, 'customer_id', e.customer_id) && among(ctx, 'external_customer_id', e.external_customer_id) && among(ctx, 'name', e.name) && among(ctx, 'source', 'user'))
+        .filter((e) => !meter || admits(meter.filter, e))
+        .filter((e) => (after === undefined || Date.parse(String(e.timestamp)) > after) && (before === undefined || Date.parse(String(e.timestamp)) < before))
+        .filter((e) => q === '' || String(e.name).toLowerCase().includes(q))
+        .sort(newest('timestamp'));
+    return ctx.list(EVENT, rows.map((e) => eventView(ctx, e)));
+}
+/** A webhook's `data`: the written object as the API answers it. */
+export function data(ctx, write) {
+    const id = String(write.body.id ?? '');
+    const row = rowOf(ctx, write.storedType, id) ?? write.body;
+    return write.storedType === CHECKOUT ? checkoutView(ctx, row) : orderView(ctx, row);
+}
+/** Private routing value: sandbox endpoints only receive sandbox writes. */
+export function values(ctx) { return { '$environment': environment(ctx) }; }

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

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const polarSemantics: Record<string, Handler>;

package/dist/src/semantics/index.js

@@ -0,0 +1,27 @@
+import * as checkouts from "./checkouts.js";
+import * as customer_sessions from "./customer-sessions.js";
+import * as customers from "./customers.js";
+import * as events from "./events.js";
+import * as orders from "./orders.js";
+import * as products from "./products.js";
+import * as subscriptions from "./subscriptions.js";
+import * as webhooks from "./webhooks.js";
+export const polarSemantics = {
+    "checkouts:client_confirm": checkouts.checkouts_client_confirm,
+    "checkouts:client_get": checkouts.checkouts_client_get,
+    "checkouts:create": checkouts.checkouts_create,
+    "checkouts:get": checkouts.checkouts_get,
+    "checkouts:list": checkouts.checkouts_list,
+    "customer-sessions:create": customer_sessions.customer_sessions_create,
+    "customers:create": customers.customers_create,
+    "customers:get": customers.customers_get,
+    "customers:get_state_external": customers.customers_get_state_external,
+    "customers:list": customers.customers_list,
+    "events:ingest": events.events_ingest,
+    "events:list": events.events_list,
+    "orders:list": orders.orders_list,
+    "products:create": products.products_create,
+    "products:list": products.products_list,
+    "subscriptions:list": subscriptions.subscriptions_list,
+    "webhooks:create_webhook_endpoint": webhooks.webhooks_create_webhook_endpoint,
+};

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

@@ -0,0 +1,4 @@
+import type { HandlerContext } from '@volter/world-core';
+/** `GET /v1/orders/`: the organization's orders, newest first, filtered by the checkout, customer, product,
+ *  subscription or status named. */
+export declare function orders_list(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/orders.js

@@ -0,0 +1,11 @@
+import { ORDER, orderView, rowsOf } from "./shared.js";
+const FILTERS = ['checkout_id', 'customer_id', 'product_id', 'subscription_id', 'status'];
+/** `GET /v1/orders/`: the organization's orders, newest first, filtered by the checkout, customer, product,
+ *  subscription or status named. */
+// source: spec:orders:list "List orders."
+export async function orders_list(ctx) {
+    const rows = rowsOf(ctx, ORDER)
+        .filter((o) => FILTERS.every((k) => ctx.params[k] === undefined || [].concat(ctx.params[k]).map(String).includes(String(o[k]))))
+        .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
+    return ctx.list('Order', rows.map((o) => orderView(ctx, o)));
+}

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

@@ -0,0 +1,5 @@
+import type { HandlerContext } from '@volter/world-core';
+/** `POST /v1/products/`: a product with its prices, each given an id. */
+export declare function products_create(ctx: HandlerContext): Promise<Response>;
+/** `GET /v1/products/`: filtered by archived, recurring, a query over names, or a benefit they grant. */
+export declare function products_list(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/products.js

@@ -0,0 +1,43 @@
+import { rowOf, bodyOf, environment, productFields, priceView, invalid, missing, newId, PRODUCT, productView, rowsOf } from "./shared.js";
+const AMOUNT_TYPES = new Set(['fixed', 'free', 'custom', 'metered_unit', 'seat_based']);
+/** `POST /v1/products/`: a product with its prices, each given an id. */
+// source: spec:products:create "Create a product."
+export async function products_create(ctx) {
+    const body = bodyOf(ctx);
+    if (typeof body.name !== 'string' || body.name === '')
+        return missing('name');
+    const prices = Array.isArray(body.prices) ? body.prices : [];
+    if (prices.length === 0)
+        return missing('prices');
+    const bad = prices.findIndex((p) => !AMOUNT_TYPES.has(String(p.amount_type)));
+    if (bad >= 0)
+        return invalid(['prices', bad, 'amount_type'], 'Input tag does not match any of the expected tags', 'union_tag_invalid');
+    const id = newId(ctx, PRODUCT);
+    const stored = [];
+    for (const price of prices) {
+        const priceId = ctx.mint('_price');
+        await ctx.record('_price', {}, priceId);
+        stored.push(priceView(ctx, { ...price, id: priceId }, { ...body, id, created_at: ctx.occurredAt }));
+    }
+    await ctx.write(PRODUCT, id, { ...productFields(ctx, {
+            id, created_at: ctx.occurredAt, modified_at: null, name: body.name, description: body.description ?? null, recurring_interval: body.recurring_interval ?? null,
+            recurring_interval_count: body.recurring_interval_count ?? (body.recurring_interval ? 1 : null), trial_interval: body.trial_interval ?? null,
+            trial_interval_count: body.trial_interval_count ?? null, visibility: body.visibility ?? 'public', is_archived: false, prices: stored, benefit_ids: [], metadata: body.metadata ?? {},
+        }), _environment: environment(ctx) }, 'product.create');
+    return Response.json(productView(ctx, rowOf(ctx, PRODUCT, id)), { status: 201 });
+}
+/** `GET /v1/products/`: filtered by archived, recurring, a query over names, or a benefit they grant. */
+// source: spec:products:list "List products."
+export async function products_list(ctx) {
+    const flag = (v) => (v === undefined ? undefined : String(v) === 'true');
+    const archived = flag(ctx.params.is_archived);
+    const recurring = flag(ctx.params.is_recurring);
+    const q = String(ctx.params.query ?? '').toLowerCase();
+    const rows = rowsOf(ctx, PRODUCT)
+        .filter((p) => archived === undefined || Boolean(p.is_archived) === archived)
+        .filter((p) => recurring === undefined || (p.recurring_interval != null) === recurring)
+        .filter((p) => q === '' || String(p.name).toLowerCase().includes(q))
+        .filter((p) => ctx.params.benefit_id === undefined || (p.benefit_ids ?? []).includes(String(ctx.params.benefit_id)))
+        .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
+    return ctx.list(PRODUCT, rows.map((p) => productView(ctx, p)));
+}

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

@@ -0,0 +1,82 @@
+import type { HandlerContext, WriteHookContext } from '@volter/world-core';
+export type Row = Record<string, unknown>;
+type Reader = Pick<HandlerContext, 'row' | 'rowsRaw' | 'crypto' | 'own' | 'call'> | Pick<WriteHookContext, 'row' | 'rowsRaw' | 'crypto' | 'own' | 'call'>;
+/** A customer by its id or its external id. */
+export declare function customerBy(ctx: Reader, key: {
+    id?: unknown;
+    external?: unknown;
+}): Row | undefined;
+export declare const ORGANIZATION = "organization";
+export declare const CUSTOMER = "customer";
+export declare const PRODUCT = "product";
+export declare const CHECKOUT = "checkout";
+export declare const SUBSCRIPTION = "subscription";
+export declare const ORDER = "order";
+export declare const EVENT = "event";
+export declare const METER = "meter";
+export declare const SESSION = "customer_session";
+export declare 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 declare const CHECKOUT_ORIGIN = "https://buy.polar.sh";
+export declare const PORTAL_ORIGIN = "https://polar.sh";
+/** Polar's error body: `{ error: <kind>, detail }`. */
+export declare const fail: (status: number, error: string, detail: string) => Response;
+export declare const notFound: (what: string) => Response;
+/** FastAPI's 422, one error per field. */
+export declare const invalid: (loc: Array<string | number>, msg: string, type?: string) => Response;
+export declare const missing: (field: string) => Response;
+export declare const bodyOf: (ctx: HandlerContext) => Row;
+export declare const newId: (ctx: Pick<HandlerContext, "mint">, type: string) => string;
+/** 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 declare function secret(ctx: Pick<HandlerContext, 'secret'>, prefix: string, seed: string): Promise<string>;
+/** The World's one organization: the one its token names. */
+export declare const ORG_ID = "1dbfc517-0bbf-4301-9ba8-555ca42b9737";
+export declare const orgId: (ctx: Pick<HandlerContext, "call">) => string;
+export declare const organizationView: (ctx: Reader) => Row;
+/** Whether a row's field is among the values a list's query names (one value or several), or the query names none. */
+export declare const among: (ctx: Pick<HandlerContext, "params">, key: string, value: unknown) => boolean;
+/** Newest first by a timestamp field. */
+export declare const newest: (field: string) => (a: Row, b: Row) => number;
+/** Stored rows without the kernel's bookkeeping. */
+export declare const environment: (ctx: Pick<HandlerContext, "call">) => string;
+export declare const rowsOf: (ctx: Reader, type: string) => Row[];
+export declare const rowOf: (ctx: Reader, type: string, id: string) => Row | undefined;
+/** The stored vendor shape; bookkeeping is private, including the environment boundary. */
+export declare const vendorFields: (ctx: Pick<HandlerContext, "own">, row: Row) => Row;
+export declare const customerView: (ctx: Reader, c: Row) => Row;
+export declare const productView: (ctx: Reader, p: Row) => Row;
+export declare const subscriptionView: (ctx: Reader, s: Row) => Row;
+export declare const orderView: (ctx: Reader, o: Row) => Row;
+export declare const eventView: (ctx: Reader, e: Row) => Row;
+export declare const checkoutView: (ctx: Reader, c: Row) => Row;
+export declare function customerFields(ctx: Reader, c: Row): Row;
+/** A price as the schema of its amount type requires (ProductPriceFixed, ProductPriceFree, ProductPriceCustom,
+ *  ProductPriceMeteredUnit). */
+export declare function priceView(ctx: Reader, p: Row, product: Row): Row;
+export declare function productFields(ctx: Reader, p: Row): Row;
+export declare function subscriptionFields(ctx: Reader, s: Row): Row;
+export declare function orderFields(ctx: Reader, o: Row): Row;
+/** A usage event as the API answers it (UserEvent): with its customer. */
+export declare function eventFields(ctx: Reader, e: Row): Row;
+export declare function checkoutFields(ctx: Reader, c: Row): Row;
+/** 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. */
+export declare function admits(filter: Row | undefined, e: Row): boolean;
+/** A meter's aggregation over the events it admits: a count, or the sum, max, min or average of a metadata property. */
+export declare function aggregate(agg: Row | undefined, events: Row[]): number;
+/** A customer's meter: consumed (the fold over its events), credited (its meter-credit grants), and the balance. */
+export declare function customerMeter(ctx: Reader, customerId: string, meter: Row): {
+    consumed: number;
+    credited: number;
+    balance: number;
+};
+/** A customer's state: its active subscriptions, granted benefits and meters. */
+export declare function customerState(ctx: HandlerContext, c: Row): Promise<Row>;
+export declare function makeOrder(ctx: HandlerContext, source: Row, reason: string, period?: {
+    start: string;
+    end: string;
+}): Promise<void>;
+export declare function addInterval(at: string, interval: string, count: number): string;
+export declare function createSession(ctx: HandlerContext, customer: Row, returnUrl?: unknown): Promise<Row>;
+export {};