@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/semantics/doors.js

@@ -0,0 +1,73 @@
+import { platformAccountDefault } from "../engine/connect.js";
+import { accountSettings, PLATFORM_ACCOUNT_ID } from "../engine/stripe.js";
+import { balanceBody, payDuePayouts, settleDueEntries } from "./shared.js";
+/** The platform's own account settings (its payout schedule, its public name) change on Stripe's Dashboard, which has no
+ *  API: this stands in for that page. The account is Stripe's default until the page first changes it (the same default
+ *  GET /v1/account answers); a hash is merged into what the account holds, as an update merges it. */
+export async function account(ctx) {
+    const ex = ctx.get('account', PLATFORM_ACCOUNT_ID);
+    const given = ctx.params;
+    const { type: _t, settings: rawSettings, business_profile: rawProfile, ...rest } = given;
+    const { id: _id, ...base } = platformAccountDefault();
+    const fields = {
+        ...(ex ? {} : base),
+        ...rest,
+        settings: accountSettings(rawSettings, ex?.settings),
+        ...(rawProfile && typeof rawProfile === 'object' ? { business_profile: { ...(ex?.business_profile ?? {}), ...rawProfile } } : {}),
+    };
+    return ctx.reply(await ctx.write('account', PLATFORM_ACCOUNT_ID, fields, 'account.update'));
+}
+/** Time's events, sent when a caller drives them (a runner's drainer): what time settled on each account is written —
+ *  payouts whose arrival date came (pending → paid, sent as payout.paid) and funds that came due (pending → available),
+ *  for which the account is sent one balance.available ("Occurs whenever your Stripe balance has been updated (e.g., when
+ *  a charge is available to be paid out)", docs.stripe.com/api/events/types) carrying its Balance, when an entry that
+ *  settled adds to it ("This event is not fired for negative transactions", the same page); a connected account's
+ *  events go to Connect endpoints. A read already sees these moves; the drain is what makes Stripe's events about them
+ *  arrive. Answers what it sent. */
+export async function drain(ctx) {
+    const accounts = [undefined, ...ctx.rows('account').map((a) => String(a.id)).filter((id) => id !== PLATFORM_ACCOUNT_ID)];
+    const delivered = [];
+    for (const account of accounts) {
+        for (const id of await payDuePayouts(ctx, account))
+            delivered.push({ type: 'payout.paid', id, ...(account ? { account } : {}) });
+        if ((await settleDueEntries(ctx, account)).some((t) => Number(t.net) > 0)) {
+            // the notice the event is sent for: the account's Balance, which has no id of its own (./events.ts renders it)
+            await ctx.write('_balance_notice', `${account ?? PLATFORM_ACCOUNT_ID}:${ctx.occurredAt}`, { account: account ?? null, balance: balanceBody(ctx, account) }, 'balance.available');
+            delivered.push({ type: 'balance.available', ...(account ? { account } : {}) });
+        }
+    }
+    return Response.json({ delivered });
+}
+/** POST /_twin/app-credentials: the platform's API keys as the dashboard's API keys page shows them, a secret key and a
+ *  publishable key (`sk_test_…`, `pk_test_…`), held by their SHA-256, and the signing secrets its webhook endpoints
+ *  are made with. The runtime issues them to a World's applications at every boot (the descriptor's credentialDoor), so
+ *  the answer is the same each time: the account's one pair of keys, made the first time. Where the documentation
+ *  stops: the keys' length and alphabet after the prefix. */
+// source: https://docs.stripe.com/keys "Publishable keys"
+export async function appCredentials(ctx) {
+    const secretKey = `sk_test_51${(await ctx.secret('stripe-platform-key:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 96)}`;
+    const publishableKey = `pk_test_51${(await ctx.secret('stripe-publishable-key:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 96)}`;
+    if (!ctx.rowsRaw('_platform_key').some((k) => k.id === 'secret:app' && k._sha256 === ctx.crypto.sha256(secretKey))) {
+        await ctx.record('_platform_key', { kind: 'secret', _sha256: ctx.crypto.sha256(secretKey), created: ctx.occurredAt, deleted: false }, 'secret:app');
+        await ctx.record('_platform_key', { kind: 'publishable', _sha256: ctx.crypto.sha256(publishableKey), created: ctx.occurredAt, deleted: false }, 'publishable:app');
+    }
+    // the signing secrets the application verifies its webhooks with, its account's and its Connect endpoint's: an
+    // endpoint made for it (the webhookEndpoints door) is signed with the one of its kind, so the two agree
+    return Response.json({ secret_key: secretKey, publishable_key: publishableKey, webhook_secret: await appEndpointSecret(ctx, false), connect_webhook_secret: await appEndpointSecret(ctx, true) }, { status: 201 });
+}
+/** The signing secret the World's application is issued for its account's endpoints, or for its Connect endpoint. */
+const appEndpointSecret = async (ctx, connect) => `whsec_${(await ctx.secret(connect ? 'stripe-webhook-secret:connect' : 'stripe-webhook-secret:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 32)}`;
+/** POST /_twin/webhook-endpoints {url, events, connect?}: an endpoint added on the Dashboard's Webhooks page, the events
+ *  it takes, signed with the secret the World's application is issued (./doors.ts `appCredentials`): the twin's
+ *  decision, since Stripe mints an endpoint's secret and lets no one choose one. */
+// source: https://docs.stripe.com/webhooks "register a webhook endpoint, Stripe pushes real-time data to it when"
+export async function webhookEndpoints(ctx) {
+    const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {});
+    if (typeof b.url !== 'string' || !/^https?:\/\//.test(b.url) || !Array.isArray(b.events) || !b.events.length)
+        return Response.json({ error: 'a url and its events are required' }, { status: 400 });
+    const connect = b.connect === true;
+    const id = ctx.mint('webhook_endpoint');
+    const secret = await appEndpointSecret(ctx, connect);
+    await ctx.write('webhook_endpoint', id, { id, object: 'webhook_endpoint', url: b.url, enabled_events: b.events.map(String), status: 'enabled', connect, livemode: false, metadata: {}, api_version: null, application: null, description: null, secret, created: Math.floor(Date.parse(ctx.occurredAt) / 1000) }, 'webhook_endpoint.create');
+    return Response.json({ id, secret }, { status: 201 });
+}

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

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

package/dist/src/semantics/entitlements.js

@@ -1,95 +1,4 @@
-import { asBool, subscriptionItemPairs } from "../stripe-twin.js";
-import { at, created, fail, list, newest, path, where, kept } from "./shared.js";
-const FEAT = 'entitlements.feature';
-/** A feature whose lookup_key an unarchived feature already has: "A unique key you provide as your own system identifier"
- *  (docs.stripe.com/api/entitlements/feature/create). */
-function lookupKeyTaken(ctx, lookupKey) {
-    return fail(ctx, `A feature with lookup_key '${lookupKey}' already exists.`, 400, 'resource_already_exists');
-}
-const create = async (ctx) => {
-    const params = ctx.params;
-    if (typeof params.name !== 'string' || !params.name)
-        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
-    const lookupKey = typeof params.lookup_key === 'string' ? params.lookup_key : '';
-    if (!lookupKey)
-        return fail(ctx, 'Missing required param: lookup_key.', 400, 'parameter_missing');
-    if (ctx.rowsRaw(FEAT, { withDeleted: true }).some((f) => f.lookup_key === lookupKey && !f._archived))
-        return lookupKeyTaken(ctx, lookupKey);
-    return ctx.reply(await created(ctx, FEAT, {}, {
-        name: params.name, lookup_key: lookupKey, active: true, livemode: false,
-        metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
-    }));
-};
-const listFeatures = async (ctx) => list(ctx, FEAT, where(ctx, newest(ctx, FEAT), {
-    lookup_key: (f, v) => f.lookup_key === v,
-    archived: (f, v) => asBool(kept(ctx, FEAT, f, '_archived')) === asBool(v),
-}));
-// name, active and metadata change
-const update = async (ctx) => {
-    const id = at(ctx, 'id');
-    if (!ctx.get(FEAT, id))
-        return ctx.notFound(FEAT, id);
-    const patch = {};
-    if (ctx.params.name !== undefined)
-        patch.name = ctx.params.name;
-    if (ctx.params.active !== undefined) {
-        patch.active = asBool(ctx.params.active);
-        patch._archived = undefined;
-    }
-    if (ctx.params.metadata !== undefined)
-        patch.metadata = ctx.params.metadata;
-    return ctx.reply(await ctx.write(FEAT, id, patch, 'entitlements_feature.update'));
-};
-// a customer is entitled to every feature granted to a product its live subscriptions bill, as the product stood when
-// the subscription's current period began: "When a customer purchases or subscribes to a product with an attached
-// feature, Stripe creates and manages an Active Entitlement for that customer and feature"; "Existing subscriptions will
-// create active entitlements for any product feature changes at the start of the next billing period"
-// (docs.stripe.com/billing/entitlements). Where the documentation stops and the twin decides: a feature removed from a
-// product is kept, the same way, until the next period begins.
-const activeEntitlements = async (ctx) => {
-    const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (!ctx.row('customer', customer, { withDeleted: true }))
-        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-    // each product a live subscription bills, with the start of the period it is billed for
-    const productIds = new Map();
-    for (const sub of newest(ctx, 'subscription')) {
-        // a subscription entitles while it runs: not before its first payment (incomplete), nor once it has ended
-        // (docs.stripe.com/billing/entitlements; past_due keeps access during retries — that edge is the twin's reading)
-        if (sub.customer !== customer || !['active', 'trialing', 'past_due'].includes(String(sub.status)))
-            continue;
-        const periodStart = Number(sub.current_period_start ?? sub.start_date ?? sub.created ?? 0);
-        for (const it of subscriptionItemPairs(sub)) {
-            const price = ctx.get('price', it.price);
-            if (price && typeof price.product === 'string')
-                productIds.set(price.product, Math.max(productIds.get(price.product) ?? -Infinity, periodStart));
-        }
-    }
-    const seen = new Set();
-    const data = [];
-    for (const pf of ctx.rowsRaw('product_feature', { withDeleted: true })) {
-        const periodStart = productIds.get(String(pf._product));
-        if (periodStart === undefined)
-            continue;
-        // attached by the period's start, and not removed before it
-        if (Number(pf._created ?? 0) > periodStart)
-            continue;
-        if (pf.deleted && !(Number(pf._removed_at) > periodStart))
-            continue;
-        const featId = String(pf._feature ?? pf.entitlement_feature?.id ?? pf.entitlement_feature);
-        if (seen.has(featId))
-            continue;
-        seen.add(featId);
-        const feat = ctx.get(FEAT, featId);
-        if (feat)
-            data.push({ id: `ent_twin_${customer}_${featId}`, object: 'entitlements.active_entitlement', feature: featId, lookup_key: feat.lookup_key, livemode: false });
-    }
-    return ctx.reply({ object: 'list', url: path(ctx), has_more: false, data });
-};
-export const entitlements = {
-    PostEntitlementsFeatures: create,
-    GetEntitlementsFeatures: listFeatures,
-    PostEntitlementsFeaturesId: update,
-    GetEntitlementsActiveEntitlements: activeEntitlements,
-};
+"use strict";
+// Stripe's entitlements operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+// source: spec:PostEntitlementsFeatures "Creates a feature"

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

@@ -0,0 +1,11 @@
+import type { EventWrite, WriteHookContext } from '@volter/world-core';
+/** An event's `data`: the object the write concerns, as Stripe sends it in the event's API version. An Issuing
+ *  authorization carries its full card; the balance notice the drain writes carries the account's Balance. */
+export declare function data(ctx: WriteHookContext, write: EventWrite): Record<string, unknown>;
+/** An event's further envelope values: the connected account it is about ("Each event for a connected account contains
+ *  a top-level `account` property that identifies the connected account", docs.stripe.com/connect/webhooks) — the
+ *  account a request acts as (Stripe-Account), a connected account's own account.updated, or the account whose books the
+ *  written row is kept on (its `_account`) — and the API version it is rendered in. A connected account whose OAuth
+ *  connection was revoked "can't be accessed by your platform" (docs.stripe.com/connect/oauth-reference): its events are
+ *  kept but no longer sent (`$send: false`), except the account.application.deauthorized that says so. */
+export declare function values(ctx: WriteHookContext, write: EventWrite, type: string): Record<string, unknown>;

package/dist/src/semantics/events.js

@@ -0,0 +1,31 @@
+import { isValidApiVersion, PLATFORM_ACCOUNT_ID, TWIN_API_VERSION } from "../engine/stripe.js";
+import { render } from "../engine/version.js";
+// ── the events Stripe's writes send (the manifest's `events`: ./shared.ts STRIPE_EVENTS) ──
+/** An event's `data`: the object the write concerns, as Stripe sends it in the event's API version. An Issuing
+ *  authorization carries its full card; the balance notice the drain writes carries the account's Balance. */
+export function data(ctx, write) {
+    const object = write.storedType === '_balance_notice' ? write.body.balance
+        : write.storedType === 'issuing_authorization' ? ctx.expand('issuing.authorization', write.body)
+            : write.storedType === 'issuing_card' ? ctx.expand('issuing.card', write.body) : ctx.expand(String(write.body.object ?? write.storedType), write.body);
+    return { object: render(object, eventVersion(write)) };
+}
+/** An event's further envelope values: the connected account it is about ("Each event for a connected account contains
+ *  a top-level `account` property that identifies the connected account", docs.stripe.com/connect/webhooks) — the
+ *  account a request acts as (Stripe-Account), a connected account's own account.updated, or the account whose books the
+ *  written row is kept on (its `_account`) — and the API version it is rendered in. A connected account whose OAuth
+ *  connection was revoked "can't be accessed by your platform" (docs.stripe.com/connect/oauth-reference): its events are
+ *  kept but no longer sent (`$send: false`), except the account.application.deauthorized that says so. */
+export function values(ctx, write, type) {
+    const id = write.body.id;
+    const kept = typeof id === 'string' ? ctx.rowsRaw(write.storedType, { withDeleted: true }).find((r) => r.id === id)?._account : undefined;
+    const account = write.request?.headers.get('stripe-account')
+        ?? (write.storedType === 'account' && typeof id === 'string' && id !== PLATFORM_ACCOUNT_ID ? id : undefined)
+        ?? (write.storedType === '_balance_notice' && typeof write.body.account === 'string' ? write.body.account : undefined)
+        ?? (typeof kept === 'string' ? kept : undefined);
+    return { $account: account, $version: eventVersion(write) };
+}
+/** The API version an event is rendered in: the one the writing request pinned, when it is one, else the served one. */
+const eventVersion = (write) => {
+    const pinned = write.request?.headers.get('stripe-version');
+    return pinned && isValidApiVersion(pinned) ? pinned : TWIN_API_VERSION;
+};

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

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

package/dist/src/semantics/index.js

@@ -0,0 +1,85 @@
+import * as account from "./account.js";
+import * as account_links from "./account_links.js";
+import * as accounts from "./accounts.js";
+import * as apps from "./apps.js";
+import * as balance from "./balance.js";
+import * as balance_transactions from "./balance_transactions.js";
+import * as billing_portal from "./billing_portal.js";
+import * as charges from "./charges.js";
+import * as checkout from "./checkout.js";
+import * as coupons from "./coupons.js";
+import * as customers from "./customers.js";
+import * as invoice_payments from "./invoice_payments.js";
+import * as invoices from "./invoices.js";
+import * as issuing from "./issuing.js";
+import * as payment_intents from "./payment_intents.js";
+import * as payment_methods from "./payment_methods.js";
+import * as payouts from "./payouts.js";
+import * as prices from "./prices.js";
+import * as products from "./products.js";
+import * as promotion_codes from "./promotion_codes.js";
+import * as radar from "./radar.js";
+import * as refunds from "./refunds.js";
+import * as subscriptions from "./subscriptions.js";
+import * as test_helpers from "./test_helpers.js";
+import * as transfers from "./transfers.js";
+import * as webhook_endpoints from "./webhook_endpoints.js";
+export const stripeSemantics = {
+    DeleteSubscriptionsSubscriptionExposedId: subscriptions.DeleteSubscriptionsSubscriptionExposedId,
+    DeleteSubscriptionsSubscriptionExposedIdDiscount: subscriptions.DeleteSubscriptionsSubscriptionExposedIdDiscount,
+    GetAccount: account.GetAccount,
+    GetAccountsAccountExternalAccounts: accounts.GetAccountsAccountExternalAccounts,
+    GetAppsSecretsFind: apps.GetAppsSecretsFind,
+    GetBalance: balance.GetBalance,
+    GetBalanceTransactions: balance_transactions.GetBalanceTransactions,
+    GetBillingPortalConfigurations: billing_portal.GetBillingPortalConfigurations,
+    GetCharges: charges.GetCharges,
+    GetChargesCharge: charges.GetChargesCharge,
+    GetCheckoutSessionsSessionLineItems: checkout.GetCheckoutSessionsSessionLineItems,
+    GetCustomersCustomer: customers.GetCustomersCustomer,
+    GetCustomersSearch: customers.GetCustomersSearch,
+    GetInvoicePayments: invoice_payments.GetInvoicePayments,
+    GetInvoicesInvoice: invoices.GetInvoicesInvoice,
+    GetIssuingCardsCard: issuing.GetIssuingCardsCard,
+    GetPaymentMethodsPaymentMethod: payment_methods.GetPaymentMethodsPaymentMethod,
+    GetPayouts: payouts.GetPayouts,
+    GetPrices: prices.GetPrices,
+    GetPricesPrice: prices.GetPricesPrice,
+    GetProducts: products.GetProducts,
+    GetPromotionCodes: promotion_codes.GetPromotionCodes,
+    GetSubscriptions: subscriptions.GetSubscriptions,
+    GetSubscriptionsSubscriptionExposedId: subscriptions.GetSubscriptionsSubscriptionExposedId,
+    PostAccountLinks: account_links.PostAccountLinks,
+    PostAccounts: accounts.PostAccounts,
+    PostAccountsAccountLoginLinks: accounts.PostAccountsAccountLoginLinks,
+    PostAppsSecrets: apps.PostAppsSecrets,
+    PostAppsSecretsDelete: apps.PostAppsSecretsDelete,
+    PostBillingPortalConfigurations: billing_portal.PostBillingPortalConfigurations,
+    PostBillingPortalSessions: billing_portal.PostBillingPortalSessions,
+    PostCheckoutSessions: checkout.PostCheckoutSessions,
+    PostCoupons: coupons.PostCoupons,
+    PostCustomers: customers.PostCustomers,
+    PostCustomersCustomer: customers.PostCustomersCustomer,
+    PostInvoices: invoices.PostInvoices,
+    PostInvoicesCreatePreview: invoices.PostInvoicesCreatePreview,
+    PostInvoicesInvoicePay: invoices.PostInvoicesInvoicePay,
+    PostInvoicesInvoiceVoid: invoices.PostInvoicesInvoiceVoid,
+    PostIssuingAuthorizationsAuthorizationApprove: issuing.PostIssuingAuthorizationsAuthorizationApprove,
+    PostIssuingAuthorizationsAuthorizationDecline: issuing.PostIssuingAuthorizationsAuthorizationDecline,
+    PostIssuingCards: issuing.PostIssuingCards,
+    PostIssuingCardsCard: issuing.PostIssuingCardsCard,
+    PostPaymentIntents: payment_intents.PostPaymentIntents,
+    PostPaymentIntentsIntentCancel: payment_intents.PostPaymentIntentsIntentCancel,
+    PostPaymentMethodsPaymentMethodDetach: payment_methods.PostPaymentMethodsPaymentMethodDetach,
+    PostPayouts: payouts.PostPayouts,
+    PostPrices: prices.PostPrices,
+    PostProducts: products.PostProducts,
+    PostPromotionCodes: promotion_codes.PostPromotionCodes,
+    PostRadarValueListItems: radar.PostRadarValueListItems,
+    PostRefunds: refunds.PostRefunds,
+    PostSubscriptionsSubscriptionExposedId: subscriptions.PostSubscriptionsSubscriptionExposedId,
+    PostTestHelpersIssuingAuthorizations: test_helpers.PostTestHelpersIssuingAuthorizations,
+    PostTestHelpersIssuingAuthorizationsAuthorizationCapture: test_helpers.PostTestHelpersIssuingAuthorizationsAuthorizationCapture,
+    PostTransfers: transfers.PostTransfers,
+    PostWebhookEndpoints: webhook_endpoints.PostWebhookEndpoints,
+};

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

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

package/dist/src/semantics/invoice_payments.js

@@ -0,0 +1,12 @@
+import { INV, invoicePayment } from "../engine/invoices.js";
+import { list, newest } from "./shared.js";
+export async function GetInvoicePayments(ctx) {
+    const p = ctx.params;
+    const wanted = p.payment?.payment_intent;
+    const items = newest(ctx, INV)
+        .filter((inv) => typeof p.invoice !== 'string' || inv.id === p.invoice)
+        .map(invoicePayment).filter((x) => !!x)
+        .filter((x) => typeof wanted !== 'string' || x.payment.payment_intent === wanted)
+        .filter((x) => typeof p.status !== 'string' || x.status === p.status);
+    return list(ctx, 'invoice_payment', items);
+}

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

@@ -1,18 +1,11 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** A draft invoice another object makes (an accepted quote): its customer's, with an invoice item per line the
- *  object gives, and the object named as its parent. Answers the invoice's id. */
-export declare function draftInvoiceFor(ctx: SemanticsContext, customer: string, currency: string, parent: Row, lines: Array<{
-    price: unknown;
-    quantity: number;
-    amount: number;
-    description: unknown;
-}>): Promise<string>;
-/** What finalizing assigns: the invoice's `number`, the customer's invoice_prefix and a sequence
- *  (https://docs.stripe.com/api/invoices/object#invoice_object-number), and for send_invoice a
- *  `due_date` days_until_due after finalization (#invoice_object-due_date). */
-/** A customer's invoice_prefix, "The prefix for the customer used to generate unique invoice numbers"
- *  (docs.stripe.com/api/customers/object): the twin's, from the customer's id. */
-export declare const invoicePrefix: (customerId: string) => string;
-export declare function finalizedFields(ctx: SemanticsContext, inv: Row, now: number): Row;
-export declare const invoices: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetInvoicesInvoice(ctx: HandlerContext): Promise<Response>;
+export declare function PostInvoicesInvoicePay(ctx: HandlerContext): Promise<Response>;
+export declare function PostInvoicesInvoiceVoid(ctx: HandlerContext): Promise<Response>;
+export declare function PostInvoices(ctx: HandlerContext): Promise<Response>;
+/**
+ * A preview of the next invoice for a customer or subscription (create_preview), computed and never
+ * stored: the subscription's items at their prices, the customer's pending items, the subscription's
+ * discount, and an update's unused-time credit and remaining-time charge at the old and new prices.
+ */
+export declare function PostInvoicesCreatePreview(ctx: HandlerContext): Promise<Response>;