@volter/twin-stripe 2.0.38 → 3.0.0

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

@@ -0,0 +1,27 @@
+export declare const STRIPE_CONSENT_SKIN = "\nbody { background: #f6f9fc; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Ubuntu, sans-serif; }\n.consent-badge { background: #ffffff; border: 1px solid #e3e8ee; color: #1a1f36; }\n.consent-vendor { background: #635bff; border-color: #635bff; }\n.consent-link { border-color: #c1c9d2; }\n.consent-box { background: #ffffff; border-color: #e3e8ee; }\n.consent-who small, .consent-permission summary small, .consent-note { color: #697386; }\n.consent-actions { border-color: #e3e8ee; }\n.consent-deny { background: #ffffff; border-color: #c1c9d2; color: #1a1f36; }\n.consent-allow { background: #635bff; border-color: #635bff; color: #ffffff; }\n";
+/** The form fields a page's POST carries, as a browser posts them. */
+export declare function formOf(request: Request): Promise<Record<string, string>>;
+export declare const seeOther: (location: string) => Response;
+export declare const DECLINES: Record<string, string>;
+export declare const luhn: (digits: string) => boolean;
+export declare const money: (minor: unknown, currency: unknown) => string;
+export declare const COUNTRIES: {
+    value: string;
+    label: string;
+}[];
+/** Cards that are saved but decline when charged. */
+export declare const DECLINES_WHEN_CHARGED: Record<string, string>;
+/** The expiry as the customer typed it. Stripe's field formats itself as it is typed: the digits `1230` read `12 / 30`,
+ *  and a first digit above 1 is a month on its own (`5` reads `05 / `), so a person types the digits straight through
+ *  (Checkout's own field, seen on checkout.stripe.com; docs.stripe.com/payments/checkout names no format to type). The
+ *  page's script (@volter/world-ui Payment, `format: 'card-expiry'`) shows it formatted; this reads what is posted either
+ *  way: `MM / YY`, `MM/YYYY`, or the bare digits `MMYY`, `MYY` (`530`) and `MMYYYY`; a month past 12 is read, and refused
+ *  as invalid by cardAnswer. */
+export declare function parseExpiry(raw: string): {
+    month: number;
+    year: number;
+} | undefined;
+/** The card's answer: undefined when it pays, else what Checkout says under the button. */
+export declare function cardAnswer(v: Record<string, string>, nowSeconds: number, chargesNow: boolean): string | undefined;
+/** Stripe's answer for a page of one of its hosts the twin does not serve. */
+export declare const notFound: () => Response;

package/dist/src/screens/shared.js

@@ -0,0 +1,87 @@
+// What Stripe's screens share (docs/contributing/architecture.md, "Pack layout": screens/shared.tsx): the skin over
+// @volter/world-ui's consent piece for the flows where a person agrees to something (connected-account onboarding,
+// identity verification, linking a bank), a page's form, and the card a customer types on Checkout and the portal.
+export const STRIPE_CONSENT_SKIN = `
+body { background: #f6f9fc; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; }
+.consent-badge { background: #ffffff; border: 1px solid #e3e8ee; color: #1a1f36; }
+.consent-vendor { background: #635bff; border-color: #635bff; }
+.consent-link { border-color: #c1c9d2; }
+.consent-box { background: #ffffff; border-color: #e3e8ee; }
+.consent-who small, .consent-permission summary small, .consent-note { color: #697386; }
+.consent-actions { border-color: #e3e8ee; }
+.consent-deny { background: #ffffff; border-color: #c1c9d2; color: #1a1f36; }
+.consent-allow { background: #635bff; border-color: #635bff; color: #ffffff; }
+`;
+/** The form fields a page's POST carries, as a browser posts them. */
+export async function formOf(request) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+export const seeOther = (location) => new Response(null, { status: 302, headers: { location } });
+export const DECLINES = {
+    '4000000000000002': 'Your card was declined.',
+    '4000000000009995': 'Your card has insufficient funds.',
+    '4000000000000069': 'Your card has expired.',
+    '4000000000000127': "Your card's security code is incorrect.",
+};
+export const luhn = (digits) => {
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let d = Number(digits[digits.length - 1 - i]);
+        if (i % 2 === 1) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return digits.length >= 12 && sum % 10 === 0;
+};
+export const money = (minor, currency) => {
+    const c = typeof currency === 'string' ? currency.toUpperCase() : 'USD';
+    const zeroDecimal = ['JPY', 'KRW', 'VND', 'CLP', 'ISK', 'UGX', 'XAF', 'XOF'].includes(c);
+    return new Intl.NumberFormat('en-US', { style: 'currency', currency: c }).format((Number(minor) || 0) / (zeroDecimal ? 1 : 100));
+};
+export const COUNTRIES = [['US', 'United States'], ['GB', 'United Kingdom'], ['CA', 'Canada'], ['DE', 'Germany'], ['FR', 'France'], ['AU', 'Australia'], ['JP', 'Japan']].map(([value, label]) => ({ value: value, label: label }));
+/** Cards that are saved but decline when charged. */
+export const DECLINES_WHEN_CHARGED = { '4000000000000341': 'Your card was declined.' };
+/** The expiry as the customer typed it. Stripe's field formats itself as it is typed: the digits `1230` read `12 / 30`,
+ *  and a first digit above 1 is a month on its own (`5` reads `05 / `), so a person types the digits straight through
+ *  (Checkout's own field, seen on checkout.stripe.com; docs.stripe.com/payments/checkout names no format to type). The
+ *  page's script (@volter/world-ui Payment, `format: 'card-expiry'`) shows it formatted; this reads what is posted either
+ *  way: `MM / YY`, `MM/YYYY`, or the bare digits `MMYY`, `MYY` (`530`) and `MMYYYY`; a month past 12 is read, and refused
+ *  as invalid by cardAnswer. */
+export function parseExpiry(raw) {
+    const split = /^\s*(\d{1,2})\s*\/\s*(\d{2}|\d{4})\s*$/.exec(raw);
+    const digits = raw.replace(/\s/g, '');
+    const bare = split ? undefined : /^(\d{2})(\d{2}|\d{4})$/.exec(digits) ?? /^([2-9])(\d{2})$/.exec(digits);
+    const m = split ?? bare;
+    if (!m)
+        return undefined;
+    return { month: Number(m[1]), year: m[2].length === 2 ? 2000 + Number(m[2]) : Number(m[2]) };
+}
+/** The card's answer: undefined when it pays, else what Checkout says under the button. */
+export function cardAnswer(v, nowSeconds, chargesNow) {
+    const digits = (v.cardNumber ?? '').replace(/\D/g, '');
+    if (!digits)
+        return 'Your card number is incomplete.';
+    if (DECLINES[digits])
+        return DECLINES[digits];
+    if (chargesNow && DECLINES_WHEN_CHARGED[digits])
+        return DECLINES_WHEN_CHARGED[digits];
+    if (!luhn(digits))
+        return 'Your card number is invalid.';
+    const exp = parseExpiry(v.cardExpiry ?? '');
+    if (!exp)
+        return "Your card's expiration date is incomplete.";
+    const { month, year } = exp;
+    if (month < 1 || month > 12)
+        return "Your card's expiration date is invalid.";
+    const now = new Date(nowSeconds * 1000);
+    if (year < now.getUTCFullYear() || (year === now.getUTCFullYear() && month < now.getUTCMonth() + 1))
+        return "Your card's expiration year is in the past.";
+    if (!/^\d{3,4}$/.test(v.cardCvc ?? ''))
+        return "Your card's security code is incomplete.";
+    return undefined;
+}
+/** Stripe's answer for a page of one of its hosts the twin does not serve. */
+export const notFound = () => new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8' } });

package/dist/src/screens/stripe-js.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerContext } from '@volter/world-core';
+/** js.stripe.com's script for a GET of its path; Stripe's 404 for anything else there. */
+export declare function screen(ctx: HandlerContext): Promise<Response>;

package/dist/src/screens/stripe-js.js

@@ -0,0 +1,135 @@
+import { notFound } from "./shared.js";
+/** The release train a script path names: `/v3`, `/v3/` or `/v3/stripe.js` → 3, `/<train>/stripe.js` → the train. */
+function stripeJsTrain(pathname) {
+    if (/^\/v3(\/|\/stripe\.js)?$/.test(pathname))
+        return 3;
+    return /^\/([a-z]+)\/stripe\.js$/.exec(pathname)?.[1];
+}
+function script(version) {
+    return `(function () {
+  var version = ${JSON.stringify(version)};
+  function gap(name) {
+    return function () { throw new Error("Stripe.js (Volter twin): stripe." + name + " is not modelled by this twin yet"); };
+  }
+  function Stripe(publishableKey) {
+    if (typeof publishableKey !== "string" || !publishableKey) throw new Error("Stripe.js (Volter twin): Stripe() needs a publishable key");
+    var api = "https://api.stripe.com/v1";
+    // the card fields every mounted element holds, the last mounted first
+    var mounted = [];
+    function cardOf(elements) {
+      var el = (elements && elements._mounted && elements._mounted[elements._mounted.length - 1]) || mounted[mounted.length - 1];
+      if (!el) return null;
+      var exp = String(el.expiry.value || "").split("/");
+      return { number: String(el.number.value || "").replace(/\s+/g, ""), exp_month: exp[0] ? String(Number(exp[0])) : "", exp_year: exp[1] ? String(2000 + Number(exp[1]) % 100) : "", cvc: String(el.cvc.value || "") };
+    }
+    function form(fields) {
+      return Object.keys(fields).filter(function (k) { return fields[k] !== undefined && fields[k] !== ""; }).map(function (k) { return encodeURIComponent(k) + "=" + encodeURIComponent(fields[k]); }).join("&");
+    }
+    function confirm(kind, options) {
+      options = options || {};
+      var elements = options.elements;
+      var secret = options.clientSecret || (elements && elements._options && elements._options.clientSecret);
+      if (typeof secret !== "string" || secret.indexOf("_secret_") < 0) return Promise.resolve({ error: { type: "invalid_request_error", message: "A clientSecret is required." } });
+      var id = secret.split("_secret_")[0];
+      var card = cardOf(elements);
+      var params = options.confirmParams || {};
+      var fields = { client_secret: secret };
+      if (card) { fields["payment_method_data[type]"] = "card"; fields["payment_method_data[card][number]"] = card.number; fields["payment_method_data[card][exp_month]"] = card.exp_month; fields["payment_method_data[card][exp_year]"] = card.exp_year; fields["payment_method_data[card][cvc]"] = card.cvc; }
+      if (params.return_url) fields.return_url = params.return_url;
+      var path = kind === "payment" ? "/payment_intents/" : "/setup_intents/";
+      return fetch(api + path + encodeURIComponent(id) + "/confirm", { method: "POST", headers: { authorization: "Bearer " + publishableKey, "content-type": "application/x-www-form-urlencoded" }, body: form(fields) })
+        .then(function (res) { return res.json().then(function (body) { return { ok: res.ok, body: body }; }); })
+        .then(function (r) {
+          if (!r.ok) return { error: r.body.error || { type: "api_error", message: "The confirmation failed." } };
+          var key = kind === "payment" ? "paymentIntent" : "setupIntent";
+          var out = {}; out[key] = r.body;
+          if (options.redirect === "if_required" || !params.return_url) return out;
+          var q = kind === "payment" ? "payment_intent" : "setup_intent";
+          var target = new URL(params.return_url);
+          target.searchParams.set(q, r.body.id);
+          target.searchParams.set(q + "_client_secret", secret);
+          target.searchParams.set("redirect_status", r.body.status === "succeeded" ? "succeeded" : r.body.status === "processing" ? "processing" : "failed");
+          window.location.assign(target.toString());
+          return new Promise(function () {});
+        });
+    }
+    function element(type, group) {
+      var handlers = {};
+      function emit(name, event) { (handlers[name] || []).forEach(function (h) { h(event); }); }
+      var el = {
+        _type: type,
+        mount: function (target) {
+          var node = typeof target === "string" ? document.querySelector(target) : target;
+          if (!node) throw new Error("Stripe.js (Volter twin): mount() found no element " + String(target));
+          node.innerHTML = "";
+          var wrap = document.createElement("div");
+          wrap.setAttribute("data-volter-twin-element", type);
+          function input(name, placeholder) { var i = document.createElement("input"); i.name = name; i.placeholder = placeholder; i.autocomplete = "off"; i.addEventListener("input", change); wrap.appendChild(i); return i; }
+          el.number = input("cardnumber", "Card number");
+          el.expiry = input("exp-date", "MM / YY");
+          el.cvc = input("cvc", "CVC");
+          node.appendChild(wrap);
+          mounted.push(el); group._mounted.push(el);
+          setTimeout(function () { emit("ready", { elementType: type }); }, 0);
+        },
+        on: function (name, handler) { (handlers[name] = handlers[name] || []).push(handler); return el; },
+        off: function (name, handler) { handlers[name] = (handlers[name] || []).filter(function (h) { return h !== handler; }); return el; },
+        update: function () {}, focus: function () { if (el.number) el.number.focus(); }, blur: function () {},
+        clear: function () { [el.number, el.expiry, el.cvc].forEach(function (i) { if (i) i.value = ""; }); change(); },
+        unmount: function () {}, destroy: function () { mounted = mounted.filter(function (m) { return m !== el; }); }
+      };
+      function change() {
+        var c = { number: el.number && el.number.value, expiry: el.expiry && el.expiry.value, cvc: el.cvc && el.cvc.value };
+        emit("change", { elementType: type, empty: !c.number && !c.expiry && !c.cvc, complete: !!(c.number && c.expiry && c.cvc), value: { type: "card" } });
+      }
+      return el;
+    }
+    var known = {
+      _registerWrapper: function () {},
+      elements: function (options) {
+        var group = { _options: options || {}, _mounted: [], _created: {} };
+        group.create = function (type) { var e = element(type, group); group._created[type] = e; return e; };
+        group.getElement = function (type) { return group._created[typeof type === "string" ? type : "card"] || null; };
+        group.update = function (next) { group._options = Object.assign({}, group._options, next || {}); };
+        group.fetchUpdates = function () { return Promise.resolve({}); };
+        group.submit = function () {
+          var card = cardOf(group);
+          if (!card || !card.number || !card.exp_month || !card.cvc) return Promise.resolve({ error: { type: "validation_error", message: "Your card details are incomplete." } });
+          return Promise.resolve({});
+        };
+        return group;
+      },
+      confirmPayment: function (options) { return confirm("payment", options); },
+      confirmSetup: function (options) { return confirm("setup", options); },
+      redirectToCheckout: function (options) {
+        if (!options || typeof options.sessionId !== "string" || !options.sessionId) return gap("redirectToCheckout without a sessionId")();
+        window.location.assign("https://checkout.stripe.com/c/pay/" + encodeURIComponent(options.sessionId));
+        return new Promise(function () {});
+      },
+      collectFinancialConnectionsAccounts: function (options) {
+        if (!options || typeof options.clientSecret !== "string" || !options.clientSecret) return gap("collectFinancialConnectionsAccounts without a clientSecret")();
+        window.location.assign("https://js.stripe.com/v3/financial-connections/" + encodeURIComponent(options.clientSecret));
+        return new Promise(function () {});
+      }
+    };
+    return new Proxy(known, {
+      get: function (target, name) {
+        if (name in target) return target[name];
+        if (typeof name === "symbol" || name === "then") return undefined;
+        return gap(String(name));
+      }
+    });
+  }
+  Stripe.version = version;
+  window.Stripe = Stripe;
+})();
+`;
+}
+/** js.stripe.com's script for a GET of its path; Stripe's 404 for anything else there. */
+export async function screen(ctx) {
+    const request = ctx.call.request;
+    const train = request.method === 'GET' || request.method === 'HEAD' ? stripeJsTrain(new URL(request.url).pathname) : undefined;
+    if (train === undefined)
+        return notFound();
+    return new Response(script(train), { headers: { 'content-type': 'application/javascript; charset=utf-8', 'access-control-allow-origin': '*' } });
+}

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

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

package/dist/src/semantics/account_links.js

@@ -0,0 +1,22 @@
+import { nowUnix } from "../engine/stripe.js";
+import { accountMissing, fail } from "./shared.js";
+// ── hosted onboarding links and embedded-component sessions ──
+export async function PostAccountLinks(ctx) {
+    const account = typeof ctx.params.account === 'string' ? ctx.params.account : '';
+    if (!account)
+        return fail(ctx, 'Missing required param: account.', 400, 'parameter_missing');
+    if (!ctx.get('account', account))
+        return accountMissing(ctx, account, 400);
+    const linkType = typeof ctx.params.type === 'string' ? ctx.params.type : '';
+    if (linkType !== 'account_onboarding' && linkType !== 'account_update')
+        return fail(ctx, 'Invalid account link type: must be account_onboarding or account_update.', 400, 'parameter_invalid_string_enum');
+    // the owner is sent back to return_url when done, and to refresh_url for a new link once this one is used or expired
+    for (const k of ['refresh_url', 'return_url'])
+        if (typeof ctx.params[k] !== 'string' || !ctx.params[k])
+            return fail(ctx, `Missing required param: ${k}.`, 400, 'parameter_missing');
+    const now = Number(nowUnix(ctx.occurredAt));
+    const id = ctx.mint('account_link');
+    const link = { object: 'account_link', created: now, expires_at: now + 300, url: `https://connect.stripe.com/setup/${id}` };
+    await ctx.write('account_link', id, { ...link, account, type: linkType, refresh_url: ctx.params.refresh_url, return_url: ctx.params.return_url, used: false }, 'account_link.create');
+    return ctx.reply(link);
+}

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

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

package/dist/src/semantics/accounts.js

@@ -0,0 +1,38 @@
+import { externalList } from "../engine/common.js";
+import { controllerOf, expressRequirements, keptKyc } from "../engine/connect.js";
+import { ACCOUNT_TYPES, accountCapabilities, accountRequirements, accountSettings, nowUnix } from "../engine/stripe.js";
+import { accountMissing, accountRow, at, connectReview, created, fail, list, newest } from "./shared.js";
+export async function GetAccountsAccountExternalAccounts(ctx) {
+    const account = at(ctx, 'account');
+    if (!accountRow(ctx, account))
+        return accountMissing(ctx, account);
+    return list(ctx, 'external_account', newest(ctx, 'external_account').filter((e) => e.account === account));
+}
+// the requested capabilities become Stripe's status map, and settings its canonical shape
+export async function PostAccounts(ctx) {
+    const params = ctx.params;
+    const type = typeof params.type === 'string' ? params.type : 'standard';
+    if (!ACCOUNT_TYPES.has(type))
+        return fail(ctx, 'Invalid account type: must be one of express, standard, or custom.', 400, 'parameter_invalid_string_enum');
+    const { capabilities: _caps, settings: _settings, ...accountParams } = keptKyc(params);
+    const id = ctx.mint('account');
+    const made = await created(ctx, 'account', { ...accountParams, id, type }, {
+        business_type: null, charges_enabled: false, payouts_enabled: false, details_submitted: false,
+        capabilities: accountCapabilities(params), requirements: type === 'express' ? expressRequirements(params) : accountRequirements(),
+        country: typeof params.country === 'string' ? params.country : 'US',
+        default_currency: 'usd', email: params.email ?? null, metadata: {}, livemode: false,
+        settings: accountSettings(params.settings), business_profile: {},
+        controller: controllerOf(type), external_accounts: externalList(id, []),
+        future_requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+        tos_acceptance: { date: null, ip: null, user_agent: null },
+    });
+    await connectReview(ctx, String(made.id));
+    return ctx.reply(ctx.get('account', String(made.id)));
+}
+// a single-use Express dashboard link, not stored
+export async function PostAccountsAccountLoginLinks(ctx) {
+    const id = at(ctx, 'account');
+    if (!ctx.get('account', id))
+        return accountMissing(ctx, id);
+    return ctx.reply({ object: 'login_link', created: nowUnix(ctx.occurredAt), url: `https://connect.twin.local/express/${id}` });
+}

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

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

package/dist/src/semantics/{apps-secrets.js → apps.js}

@@ -1,12 +1,14 @@
-import { created, fail, list, newest, kept } from "./shared.js";
-const SECRET = 'apps.secret';
-function scopeKeyOf(ctx) {
-    const scope = ctx.params.scope && typeof ctx.params.scope === 'object' ? ctx.params.scope : undefined;
-    const scopeType = scope && typeof scope.type === 'string' ? scope.type : 'account';
-    return scopeType === 'user' ? `user:${String(scope.user)}` : 'account';
+import { SECRET } from "../engine/apps-secrets.js";
+import { nowUnix } from "../engine/stripe.js";
+import { created, fail, named, scopeKeyOf } from "./shared.js";
+export async function GetAppsSecretsFind(ctx) {
+    const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
+    if (!name)
+        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+    const s = named(ctx, name);
+    return s ? ctx.reply(s) : fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
 }
-const named = (ctx, name) => ctx.rows(SECRET).find((s) => s.name === name && kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx));
-const set = async (ctx) => {
+export async function PostAppsSecrets(ctx) {
     const params = ctx.params;
     const name = typeof params.name === 'string' ? params.name : '';
     if (!name)
@@ -22,21 +24,14 @@ const set = async (ctx) => {
     const expiresAt = params.expires_at !== undefined ? Math.trunc(Number(params.expires_at)) : null;
     const existing = named(ctx, name);
     if (existing)
-        return ctx.reply(await ctx.write(SECRET, String(existing.id), { payload: params.payload, expires_at: expiresAt, _updated: ctx.now() }, 'apps_secret.update'));
+        return ctx.reply(await ctx.write(SECRET, String(existing.id), { payload: params.payload, expires_at: expiresAt, _updated: nowUnix(ctx.occurredAt) }, 'apps_secret.update'));
     return ctx.reply(await created(ctx, SECRET, { name }, {
         livemode: false, deleted: false, expires_at: expiresAt, payload: params.payload,
         scope: scopeType === 'user' ? { type: 'user', user: scope.user } : { type: 'account' },
         _scope_key: scopeKeyOf(ctx),
     }));
-};
-const find = async (ctx) => {
-    const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
-    if (!name)
-        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
-    const s = named(ctx, name);
-    return s ? ctx.reply(s) : fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
-};
-const remove = async (ctx) => {
+}
+export async function PostAppsSecretsDelete(ctx) {
     const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
     if (!name)
         return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
@@ -44,11 +39,4 @@ const remove = async (ctx) => {
     if (!s)
         return fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
     return ctx.reply(await ctx.write(SECRET, String(s.id), { deleted: true }, 'apps_secret.delete'));
-};
-const listSecrets = async (ctx) => list(ctx, SECRET, newest(ctx, SECRET).filter((s) => kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx)));
-export const appsSecrets = {
-    PostAppsSecrets: set,
-    GetAppsSecretsFind: find,
-    PostAppsSecretsDelete: remove,
-    GetAppsSecrets: listSecrets,
-};
+}

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

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

package/dist/src/semantics/around.js

@@ -0,0 +1,16 @@
+import { actingAsOAuthKey, platformKeyRefused, publishableKeyRefused, refuseParameters, rendered, revokedAccountRefused, withMetadata } from "./shared.js";
+export async function around(ctx, next) {
+    const arrived = ctx.call.request;
+    const unkeyed = platformKeyRefused(ctx, arrived);
+    if (unkeyed)
+        return unkeyed;
+    const acting = await actingAsOAuthKey(ctx, arrived.clone());
+    if (acting instanceof Response)
+        return acting;
+    if (ctx.call.operation.id !== 'unmatched') {
+        const refused = publishableKeyRefused(ctx) ?? revokedAccountRefused(ctx) ?? refuseParameters(ctx);
+        if (refused)
+            return refused;
+    }
+    return rendered(arrived, await next(withMetadata(ctx, acting)));
+}

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

@@ -1,11 +1,2 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** The acting account's Balance object (docs.stripe.com/api/balance/balance_object). */
-export declare function balanceBody(ctx: SemanticsContext): Row;
-/** Time's arrivals, written: each of the acting account's payouts whose arrival date has come moves pending → paid
- *  (the clock's move, as asOf reads it), written as `payout.paid`, the event Stripe sends for it. Answers their ids. */
-export declare function payDuePayouts(ctx: SemanticsContext): Promise<string[]>;
-/** Time's payouts, caught up to the World's clock: each account on an automatic schedule is paid out, on each of its
- *  scheduled days that has come, what became available by then. */
-export declare function advancePayouts(ctx: SemanticsContext): Promise<void>;
-export declare const balances: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetBalance(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/balance.js

@@ -1,195 +1,4 @@
-import { validateMoney } from "../stripe-twin.js";
-import { accountSettings, PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
-import { actingAccount, balanceOf, refusePayout, settleAutomaticPayout, settlePayout, unpaidEntries } from "./ledger.js";
-import { at, at_, created, fail, inRange, list, newest, send, where, kept } from "./shared.js";
-const account = actingAccount;
-const DAY = 86_400;
-const payoutMissing = (ctx, id) => fail(ctx, `No such payout: '${id}'`, 404, 'resource_missing');
-/** The acting account's Balance object (docs.stripe.com/api/balance/balance_object). */
-export function balanceBody(ctx) {
-    const { available, pending, issuing } = balanceOf(ctx);
-    const toArr = (m) => {
-        const out = [...m.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } }));
-        return out.length ? out : [{ amount: 0, currency: 'usd', source_types: { card: 0 } }];
-    };
-    // a platform's balance holds its connected accounts' reserve, "Funds held due to negative balances on connected accounts
-    // where account.controller.requirement_collection is `application`" (docs.stripe.com/api/balance/balance_object, whose
-    // example answers `[{"amount": 0, "currency": "usd"}]`); the twin models no such reserve, so it is zero in each currency
-    const reserved = account(ctx) ? {} : { connect_reserved: toArr(available).map((b) => ({ amount: 0, currency: b.currency })) };
-    return {
-        object: 'balance', available: toArr(available), pending: toArr(pending), ...reserved, livemode: false,
-        ...(issuing.size ? { issuing: { available: [...issuing.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } })) } } : {}),
-    };
+import { balanceBody } from "./shared.js";
+export async function GetBalance(ctx) {
+    return ctx.reply(balanceBody(ctx));
 }
-const balance = async (ctx) => ctx.reply(balanceBody(ctx));
-/** Time's arrivals, written: each of the acting account's payouts whose arrival date has come moves pending → paid
- *  (the clock's move, as asOf reads it), written as `payout.paid`, the event Stripe sends for it. Answers their ids. */
-export async function payDuePayouts(ctx) {
-    const acct = account(ctx);
-    const now = Number(ctx.now());
-    const paid = [];
-    for (const p of newest(ctx, 'payout')) {
-        if ((acct ? kept(ctx, 'payout', p, '_account') !== acct : !!kept(ctx, 'payout', p, '_account')) || p.status !== 'pending' || Number(p.arrival_date) > now)
-            continue;
-        if (ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time'))
-            continue;
-        await ctx.write('payout', String(p.id), { status: 'paid' }, 'payout.paid');
-        paid.push(String(p.id));
-    }
-    return paid;
-}
-/** Where a connected account's payout goes: "ID of the bank account or card the payout is sent to" (served spec,
- *  payout.destination), its default external account for the currency, "When multiple accounts are available for a given
- *  currency, Stripe uses the one set as `default_for_currency`" (docs.stripe.com/connect/payouts-bank-accounts), the
- *  newest such. Where the documentation stops and the twin decides: the platform's own bank account is not modelled, so
- *  its payouts name none. */
-function payoutBank(ctx, account, currency) {
-    const banks = newest(ctx, 'external_account').filter((e) => e.account === account && String(e.currency ?? currency) === currency);
-    return String((banks.find((e) => e.default_for_currency === true) ?? banks[0])?.id ?? '') || null;
-}
-const payoutDefaults = (ctx) => ({
-    method: 'standard', type: 'bank_account', source_type: 'card', automatic: false,
-    reconciliation_status: 'not_applicable', arrival_date: Number(ctx.now()) + 2 * DAY, livemode: false, metadata: {},
-});
-/** A payout as the clock reads it: paid once its arrival date has come, the clock's move, asked of the
- *  machine as a write asks it. */
-function asOf(ctx, p) {
-    if (p.status !== 'pending' || Number(p.arrival_date) > Number(ctx.now()))
-        return p;
-    ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time');
-    return { ...p, status: 'paid' };
-}
-/** A connected account's payout in a currency none of its bank accounts takes. */
-function noExternalAccount(ctx, currency) {
-    return fail(ctx, `Sorry, you don't have any external accounts in that currency (${currency}).`, 400);
-}
-const createPayout = async (ctx) => {
-    const bad = validateMoney(ctx.params);
-    if (bad)
-        return send(ctx, bad);
-    const acct = account(ctx);
-    if (acct && !ctx.get('account', acct))
-        return fail(ctx, `No such account: '${acct}'`, 400, 'account_invalid');
-    const amount = Math.trunc(Number(ctx.params.amount) || 0);
-    const currency = String(ctx.params.currency ?? 'usd');
-    // a connected account is paid out to its own bank account
-    if (acct && !ctx.rows('external_account').some((e) => e.account === acct && (e.currency ?? currency) === currency))
-        return noExternalAccount(ctx, currency);
-    const refused = refusePayout(ctx, amount, currency);
-    if (refused)
-        return refused;
-    const id = ctx.mint('payout');
-    const bt = await settlePayout(ctx, id, -amount, currency);
-    return ctx.reply(await created(ctx, 'payout', { ...ctx.params, id }, { status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, destination: acct ? payoutBank(ctx, acct, currency) : null, ...(acct ? { _account: acct } : {}) }));
-};
-const listPayouts = async (ctx) => {
-    const acct = account(ctx);
-    const scoped = newest(ctx, 'payout').filter((p) => (acct ? kept(ctx, 'payout', p, '_account') === acct : !kept(ctx, 'payout', p, '_account'))).map((p) => asOf(ctx, p));
-    return list(ctx, 'payout', where(ctx, scoped, { status: (p, v) => p.status === v, created: (p, v) => inRange(p.created, v), arrival_date: (p, v) => inRange(p.arrival_date, v) }));
-};
-const DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
-/** The first scheduled payout time on or after `from`: midnight UTC of a day the schedule pays out on. */
-function payoutDay(from, schedule) {
-    const first = Math.ceil(from / DAY) * DAY;
-    const pays = (day) => {
-        const d = new Date(day * 1000);
-        if (schedule.interval === 'weekly')
-            return DAYS[d.getUTCDay()] === String(schedule.weekly_anchor ?? 'monday');
-        if (schedule.interval === 'monthly')
-            return d.getUTCDate() === Math.min(Number(schedule.monthly_anchor ?? 1), new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate());
-        return true;
-    };
-    return Array.from({ length: 62 }, (_, i) => first + i * DAY).find(pays) ?? first;
-}
-/** Time's payouts, caught up to the World's clock: each account on an automatic schedule is paid out, on each of its
- *  scheduled days that has come, what became available by then. */
-export async function advancePayouts(ctx) {
-    const now = Number(ctx.now());
-    const platform = ctx.get('account', PLATFORM_ACCOUNT_ID);
-    const accounts = [{ id: undefined, settings: platform?.settings }];
-    for (const a of ctx.rows('account')) {
-        if (a.id === PLATFORM_ACCOUNT_ID || a.payouts_enabled !== true)
-            continue;
-        if (!ctx.rows('external_account').some((e) => e.account === a.id))
-            continue;
-        accounts.push({ id: String(a.id), settings: a.settings });
-    }
-    for (const acct of accounts) {
-        const schedule = (accountSettings(acct.settings, acct.settings ?? undefined).payouts.schedule ?? {});
-        if (schedule.interval === 'manual')
-            continue;
-        const unpaid = unpaidEntries(ctx, acct.id);
-        const days = [...new Set(unpaid.map((t) => payoutDay(Number(t.available_on) || 0, schedule)))].filter((d) => d <= now).sort((x, y) => x - y);
-        const paid = new Set();
-        for (const day of days) {
-            const due = unpaid.filter((t) => !paid.has(t.id) && (Number(t.available_on) || 0) <= day);
-            const byCurrency = new Map();
-            for (const t of due)
-                byCurrency.set(String(t.currency ?? 'usd'), [...(byCurrency.get(String(t.currency ?? 'usd')) ?? []), t]);
-            for (const [currency, entries] of byCurrency) {
-                const amount = entries.reduce((n, t) => n + (Number(t.net) || 0), 0);
-                // nothing to pay yet: what came due is carried to the next payout
-                if (amount <= 0)
-                    continue;
-                // made on its day, as Stripe makes it, whenever the request that catches it up comes
-                const c = await at_(ctx)(day);
-                const id = c.mint('payout');
-                const bt = await settleAutomaticPayout(c, id, amount, currency, acct.id, day, entries);
-                await created(c, 'payout', { id, amount, currency }, {
-                    status: 'pending', ...payoutDefaults(c), arrival_date: day + 2 * DAY, automatic: true, balance_transaction: bt, destination: acct.id ? payoutBank(c, String(acct.id), currency) : null,
-                    description: 'STRIPE PAYOUT', ...(acct.id ? { _account: acct.id } : {}),
-                });
-                for (const t of entries)
-                    paid.add(t.id);
-            }
-        }
-    }
-}
-const retrievePayout = async (ctx) => {
-    const p = ctx.get('payout', at(ctx, 'payout'));
-    return p ? ctx.reply(asOf(ctx, p)) : payoutMissing(ctx, at(ctx, 'payout'));
-};
-const cancelPayout = async (ctx) => {
-    const id = at(ctx, 'payout');
-    const po = ctx.get('payout', id);
-    if (!po)
-        return payoutMissing(ctx, id);
-    const refused = ctx.legal('payout', 'status', 'PostPayoutsPayoutCancel', asOf(ctx, po).status, undefined, id);
-    if (refused)
-        return ctx.refuse(refused);
-    // the money comes back to the balance it left
-    const owner = kept(ctx, 'payout', po, '_account');
-    await settlePayout(ctx, id, Number(po.amount) || 0, String(po.currency ?? 'usd'), typeof owner === 'string' ? owner : null);
-    return ctx.reply(await ctx.write('payout', id, { status: 'canceled' }, 'payout.cancel'));
-};
-// a reversal is itself a payout in the other direction, back into the connected account's balance, as the reverse page's
-// example answers it: a negative amount, pending until it arrives, carrying the request's metadata
-// (docs.stripe.com/api/payouts/reverse); the original stays paid and names it
-const reversePayout = async (ctx) => {
-    const id = at(ctx, 'payout');
-    const po = ctx.get('payout', id);
-    if (!po)
-        return payoutMissing(ctx, id);
-    const owner = kept(ctx, 'payout', po, '_account');
-    if (typeof owner !== 'string')
-        return fail(ctx, "Payout reversals are only supported for payouts to connected accounts' bank accounts.", 400);
-    const status = String(asOf(ctx, po).status);
-    if (po.reversed_by || status !== 'paid')
-        return ctx.refuse({ status: 400, code: 'payout_reversal_not_allowed', message: po.reversed_by ? 'This payout has already been reversed.' : `This payout cannot be reversed because it has a status of ${status}. A pending payout can be canceled instead.` });
-    const reversalId = ctx.mint('payout');
-    const bt = await settlePayout(ctx, reversalId, Number(po.amount) || 0, String(po.currency ?? 'usd'), owner);
-    const metadata = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {};
-    const reversal = await created(ctx, 'payout', { id: reversalId, amount: -(Number(po.amount) || 0), currency: po.currency, ...metadata }, {
-        status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, original_payout: id, destination: po.destination ?? null, _account: owner,
-    });
-    await ctx.write('payout', id, { reversed_by: reversal.id }, 'payout.reversed');
-    return ctx.reply(reversal);
-};
-export const balances = {
-    GetBalance: balance,
-    PostPayouts: createPayout,
-    GetPayouts: listPayouts,
-    GetPayoutsPayout: retrievePayout,
-    PostPayoutsPayoutCancel: cancelPayout,
-    PostPayoutsPayoutReverse: reversePayout,
-};