@volter/twin-stripe 3.0.0 → 3.0.1

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

@@ -1,7 +1,6 @@
 import type { HandlerContext } from '@volter/world-core';
 export declare function DeleteSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response>;
 export declare function GetSubscriptions(ctx: HandlerContext): Promise<Response>;
-export declare function GetSubscriptionsSearch(ctx: HandlerContext): Promise<Response>;
 export declare function GetSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response>;
-export declare function PostSubscriptions(ctx: HandlerContext): Promise<Response>;
 export declare function PostSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response>;
+export declare function DeleteSubscriptionsSubscriptionExposedIdDiscount(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/subscriptions.js

@@ -1,12 +1,14 @@
-import { itemQuantity, keptAfter } from "../engine/renewals.js";
-import { addBillingInterval, applyCouponDiscount, asBool, buildDiscount, buildSubscriptionItemsList, declineFor, mintClientSecret, nowUnix, priceAmount, resolveSubscriptionBillingInterval, resolveTrial, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries } from "../engine/stripe.js";
+import { keptAfter } from "../engine/renewals.js";
+import { asBool, nowUnix, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries } from "../engine/stripe.js";
 import { pauseCollection, SUB } from "../engine/subscriptions.js";
-import { advanceBilling, applyItemChanges, applyTrialEnd, at, clockNow, collectSubscriptionInvoice, created, draftSubscriptionInvoice, expanded, fail, finalizedFields, finder, firstPaymentRefused, itemChangesRefused, list, mintCharge, newest, redeemCoupon, replacedDiscounts, search, spendOnceCoupon, storeItems, subMissing, trialEndBlocked, trialEndRefused, where } from "./shared.js";
+import { resourceView, advanceBilling, applyItemChanges, applyTrialEnd, at, clockNow, collectSubscriptionInvoice, expanded, itemChangesRefused, list, newest, redeemCoupon, replacedDiscounts, subMissing, trialEndBlocked, trialEndRefused, where } from "./shared.js";
+import { deletedDiscount } from "../engine/common.js";
+import { fail } from "./shared.js";
 // canceling keeps the subscription, now canceled, stamped with when it was canceled and ended
 // (https://docs.stripe.com/api/subscriptions/object#subscription_object-canceled_at, #subscription_object-ended_at)
 export async function DeleteSubscriptionsSubscriptionExposedId(ctx) {
     const id = at(ctx, 'subscription_exposed_id');
-    const sub = ctx.get(SUB, id);
+    const sub = resourceView(ctx, SUB, id);
     if (!sub)
         return subMissing(ctx, id);
     const refused = ctx.legal(SUB, 'status', 'DeleteSubscriptionsSubscriptionExposedId', sub.status, undefined, id);
@@ -18,7 +20,7 @@ export async function DeleteSubscriptionsSubscriptionExposedId(ctx) {
     // `"reason": "cancellation_requested"` (docs.stripe.com/api/subscriptions/cancel)
     const given = ctx.params.cancellation_details && typeof ctx.params.cancellation_details === 'object' ? ctx.params.cancellation_details : {};
     const cancellation_details = { comment: given.comment ?? null, feedback: given.feedback ?? null, reason: 'cancellation_requested' };
-    return ctx.reply(await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel'));
+    return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel')));
 }
 export async function GetSubscriptions(ctx) {
     await advanceBilling(ctx);
@@ -28,154 +30,17 @@ export async function GetSubscriptions(ctx) {
         price: (s, v) => subscriptionHasPrice(s, String(v)),
     }));
 }
-export async function GetSubscriptionsSearch(ctx) {
-    await advanceBilling(ctx);
-    return search(ctx, SUB);
-}
 export async function GetSubscriptionsSubscriptionExposedId(ctx) {
     const id = at(ctx, 'subscription_exposed_id');
     await advanceBilling(ctx, (sub) => sub.id === id);
-    const sub = ctx.get(SUB, id);
+    const sub = resourceView(ctx, SUB, id);
     return sub ? ctx.reply(expanded(ctx, SUB, sub)) : subMissing(ctx, id);
 }
-export async function PostSubscriptions(ctx) {
-    const params = ctx.params;
-    const customer = typeof params.customer === 'string' ? params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (!ctx.get('customer', customer))
-        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-    const now = clockNow(ctx, customer);
-    const badTrial = trialEndRefused(ctx, params.trial_end, now);
-    if (badTrial)
-        return badTrial;
-    // a coupon (or discounts[0][coupon]) must exist; it becomes the subscription's discount
-    const couponId = subscriptionCouponParam(params);
-    let discounts = [];
-    if (couponId) {
-        const coupon = ctx.get('coupon', couponId);
-        if (!coupon)
-            return fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
-        discounts = [buildDiscount(coupon, customer, now)];
-    }
-    // a trial is the current period; otherwise one billing interval of the first item's price. The
-    // period sits top-level: this twin's default API version predates basil moving it onto items.
-    const trial = resolveTrial(params, now);
-    const itemEntries = subscriptionItemEntries(params.items);
-    const { interval, interval_count } = resolveSubscriptionBillingInterval(itemEntries, finder(ctx));
-    const periodStart = trial ? trial.start : now;
-    const periodEnd = trial ? trial.end : addBillingInterval(now, interval, interval_count);
-    const subId = typeof params.id === 'string' && params.id ? params.id : ctx.mint(SUB);
-    const itemsList = buildSubscriptionItemsList(itemEntries, subId, now, finder(ctx));
-    const itemsData = itemsList.data;
-    const currency = typeof params.currency === 'string' && params.currency ? params.currency : 'usd';
-    // Stripe opens a subscription's first invoice at once (a trialing one has nothing due yet) and, by
-    // payment_behavior (docs.stripe.com/api/subscriptions/create#create_subscription-payment_behavior):
-    // allow_incomplete (the default) charges the default payment method now, and without one, or on a decline,
-    // leaves the subscription incomplete with the invoice open; error_if_incomplete refuses the create instead;
-    // default_incomplete never charges, leaving a PaymentIntent the frontend confirms.
-    const behavior = typeof params.payment_behavior === 'string' ? params.payment_behavior : 'allow_incomplete';
-    const needsFirstInvoice = !trial;
-    const holder = ctx.get('customer', customer) ?? {};
-    const payWith = behavior === 'default_incomplete' ? undefined
-        : (typeof params.default_payment_method === 'string' ? params.default_payment_method : undefined) ?? holder.invoice_settings?.default_payment_method ?? undefined;
-    const declined = payWith ? declineFor(finder(ctx), { payment_method: payWith }) : undefined;
-    let subtotal = 0;
-    for (const it of itemsData) {
-        const price = it.price && typeof it.price === 'object' ? it.price : undefined;
-        subtotal += priceAmount(price, itemQuantity(it));
-    }
-    const coupon = discounts[0]?.coupon;
-    const discountAmount = applyCouponDiscount(subtotal, coupon);
-    const invoiceTotal = Math.max(0, subtotal - discountAmount);
-    // a $0 first invoice is paid at once and needs no PaymentIntent
-    const isFree = invoiceTotal <= 0;
-    const pays = needsFirstInvoice && !isFree && !!payWith && !declined;
-    if (needsFirstInvoice && !isFree && !pays && behavior === 'error_if_incomplete')
-        return firstPaymentRefused(ctx, declined);
-    // minted first so the subscription names its latest_invoice in its own create (a trial's $0 invoice too)
-    const invoiceId = needsFirstInvoice ? ctx.mint('invoice') : null;
-    const trialInvoiceId = needsFirstInvoice ? null : ctx.mint('invoice');
-    const piId = needsFirstInvoice && !isFree ? ctx.mint('payment_intent') : null;
-    const { coupon: _c, discounts: _ds, trial_period_days: _tpd, trial_end: _te, items: _items, id: _id, ...rest } = params;
-    const sub = await created(ctx, SUB, { ...rest, id: subId }, {
-        status: trial ? 'trialing' : needsFirstInvoice && !isFree && !pays ? 'incomplete' : 'active',
-        livemode: false, currency, collection_method: 'charge_automatically',
-        // a trial's end is the billing anchor: "The `billing_cycle_anchor` will be updated to the `trial_end` value"
-        // (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
-        cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trial ? trial.end : now, metadata: {},
-        discounts: discounts.map((d) => ({ ...d, subscription: subId })), billing_schedules: [],
-        ...(trial ? { trial_start: trial.start, trial_end: trial.end } : { trial_start: null, trial_end: null }),
-        current_period_start: periodStart, current_period_end: periodEnd,
-        items: itemsList,
-        latest_invoice: invoiceId ?? trialInvoiceId,
-        automatic_tax: { enabled: false, liability: null },
-        billing_mode: { type: 'classic' },
-        invoice_settings: { issuer: { type: 'self' } },
-    });
-    await storeItems(ctx, subId, itemsData);
-    if (discounts.length)
-        await redeemCoupon(ctx, couponId);
-    // a customer billed for the first time takes the subscription's currency
-    if (!holder.currency)
-        await ctx.write('customer', customer, { currency }, 'customer.update');
-    if (!invoiceId) {
-        // a trial's subscription still opens an invoice at once: "An immediate invoice is still created, but the amount is 0"
-        // (docs.stripe.com/billing/subscriptions/trials/free-trials); finalizing it spends a once coupon (renewals.ts)
-        const trialInvoice = await draftSubscriptionInvoice(ctx, ctx.get(SUB, subId) ?? sub, { start: periodStart, end: periodEnd, reason: 'subscription_create', trial: true, ...(trialInvoiceId ? { id: trialInvoiceId } : {}) });
-        await collectSubscriptionInvoice(ctx, trialInvoice, now, 'api');
-        return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-    }
-    // the default payment method pays the first invoice now: its charge (with its ledger entry) comes first
-    const chargeId = pays && piId ? await mintCharge(ctx, piId, { currency, customer, payment_method: payWith, invoice: invoiceId }, invoiceTotal) : null;
-    const invoiceLines = itemsData.map((it, i) => {
-        const price = it.price && typeof it.price === 'object' ? it.price : undefined;
-        const quantity = itemQuantity(it);
-        return {
-            id: `il_twin_${invoiceId}_${i + 1}`, object: 'line_item', type: 'subscription',
-            amount: priceAmount(price, quantity), currency, quantity, proration: false,
-            price: it.price ?? null, subscription: subId, invoice_item: null, subscription_item: it.id ?? null,
-            period: { start: periodStart, end: periodEnd }, description: null,
-        };
-    });
-    await created(ctx, 'invoice', {
-        id: invoiceId,
-        ...finalizedFields(ctx, { id: invoiceId, customer }, now),
-        status: isFree || pays ? 'paid' : 'open', livemode: false, currency, collection_method: 'charge_automatically',
-        auto_advance: !(isFree || pays), attempt_count: payWith && !isFree ? 1 : 0, attempted: !isFree && behavior !== 'default_incomplete',
-        customer, subscription: subId, billing_reason: 'subscription_create', charge: chargeId,
-        amount_due: invoiceTotal, amount_paid: isFree || pays ? invoiceTotal : 0, amount_remaining: isFree || pays ? 0 : invoiceTotal,
-        amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
-        subtotal, total: invoiceTotal, starting_balance: 0,
-        post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
-        period_start: periodStart, period_end: periodEnd,
-        default_tax_rates: [], discounts: discounts[0] ? [discounts[0]] : [],
-        lines: { object: 'list', data: invoiceLines, has_more: false, total_count: invoiceLines.length, url: `/v1/invoices/${invoiceId}/lines` },
-        automatic_tax: { enabled: false, liability: null, status: null },
-        status_transitions: { finalized_at: now, marked_uncollectible_at: null, paid_at: isFree || pays ? now : null, voided_at: null },
-        issuer: { type: 'self' },
-        payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
-        payment_intent: piId,
-    }, {});
-    if (piId) {
-        // paid by the default payment method, or waiting on one (declined, absent, or collected client-side)
-        await created(ctx, 'payment_intent', { id: piId, amount: invoiceTotal, currency, customer, invoice: invoiceId, ...(payWith ? { payment_method: pays ? payWith : null } : {}) }, {
-            status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId, await ctx.secret(`client-secret:${piId}`)), livemode: false,
-            capture_method: 'automatic', amount_capturable: 0, amount_received: pays ? invoiceTotal : 0, next_action: null,
-            latest_charge: chargeId,
-            last_payment_error: declined ? { type: 'card_error', code: declined.code, decline_code: declined.decline_code ?? null, message: declined.message, payment_method: { id: payWith } } : null,
-            automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
-        });
-    }
-    // the first invoice is finalized: the `once` coupon it took is spent (renewals.ts spendOnceCoupon)
-    await spendOnceCoupon(ctx, ctx.get('invoice', invoiceId) ?? {});
-    return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-}
 export async function PostSubscriptionsSubscriptionExposedId(ctx) {
     const id = at(ctx, 'subscription_exposed_id');
     // a period that has already ended renews (or a trial that has, ends) before the update applies (renewals.ts)
     await advanceBilling(ctx, (s) => s.id === id);
-    const sub = ctx.get(SUB, id);
+    const sub = resourceView(ctx, SUB, id);
     if (!sub)
         return subMissing(ctx, id);
     const params = ctx.params;
@@ -230,5 +95,18 @@ export async function PostSubscriptionsSubscriptionExposedId(ctx) {
         if (fields.discounts !== undefined)
             fields.discounts = keptAfter(fields.discounts, ctx.get('invoice', trial.invoice) ?? {});
     }
-    return ctx.reply(await ctx.write(SUB, id, fields, op));
+    return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, fields, op)));
+}
+export async function DeleteSubscriptionsSubscriptionExposedIdDiscount(ctx) {
+    const id = at(ctx, 'subscription_exposed_id');
+    const sub = resourceView(ctx, SUB, id);
+    if (!sub)
+        return subMissing(ctx, id);
+    // source: spec:DeleteSubscriptionsSubscriptionExposedIdDiscount "Removes the currently applied discount on a subscription."
+    const current = (sub.discounts ?? [])[0] ?? sub.discount;
+    // Where the documentation stops and the twin decides: a subscription with no discount answers its absence as a missing resource.
+    if (!current)
+        return fail(ctx, `No active discount for subscription: '${id}'`, 404, 'resource_missing');
+    await ctx.write(SUB, id, { discounts: [] }, 'subscription.update');
+    return ctx.reply(deletedDiscount(typeof current === 'string' ? { id: current } : { ...current, subscription: id }, nowUnix(ctx.occurredAt)));
 }

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

@@ -1,6 +1,3 @@
 import type { HandlerContext } from '@volter/world-core';
-/** A test clock deleted with what lives on it: "Deleting the simulation also deletes the test customers associated
- *  with the clock and cancels their subscriptions" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). */
-export declare function DeleteTestHelpersTestClocksTestClock(ctx: HandlerContext): Promise<Response>;
-export declare function PostTestHelpersTestClocks(ctx: HandlerContext): Promise<Response>;
-export declare function PostTestHelpersTestClocksTestClockAdvance(ctx: HandlerContext): Promise<Response>;
+export declare function PostTestHelpersIssuingAuthorizations(ctx: HandlerContext): Promise<Response>;
+export declare function PostTestHelpersIssuingAuthorizationsAuthorizationCapture(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/test_helpers.js

@@ -1,47 +1,125 @@
-import { nowUnix } from "../engine/stripe.js";
-import { CLOCK } from "../engine/test-clocks.js";
-import { at, created, fail } from "./shared.js";
-/** A test clock deleted with what lives on it: "Deleting the simulation also deletes the test customers associated
- *  with the clock and cancels their subscriptions" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). */
-export async function DeleteTestHelpersTestClocksTestClock(ctx) {
-    const id = at(ctx, 'test_clock');
-    if (!ctx.get(CLOCK, id))
-        return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
-    const now = Number(nowUnix(ctx.occurredAt));
-    for (const c of ctx.rows('customer').filter((c) => c.test_clock === id)) {
-        for (const sub of ctx.rows('subscription').filter((s) => s.customer === c.id && s.status !== 'canceled')) {
-            ctx.legal('subscription', 'status', 'DeleteTestHelpersTestClocksTestClock', String(sub.status), 'canceled', String(sub.id));
-            await ctx.write('subscription', String(sub.id), { status: 'canceled', canceled_at: now, ended_at: now }, 'subscription.cancel');
-        }
-        await ctx.write('customer', String(c.id), { deleted: true }, 'customer.deleted');
-    }
-    await ctx.write(CLOCK, id, { deleted: true }, 'test_clock.deleted');
-    return ctx.reply({ id, object: 'test_helpers.test_clock', deleted: true });
+import { AUTH, CARD, cardId, CH, historyEntry, holderId, merchantData, TXN } from "../engine/issuing.js";
+import { isValidApiVersion, nowUnix, spendingControlsViolation, TWIN_API_VERSION } from "../engine/stripe.js";
+import { stripeEventMatches } from "../engine/webhooks.js";
+import { answeredByEndpoint, approvedAtOnce, askForAuthorization, at, authMissing, balanceOf, capture, created, fail, issuingRefusal, withCard } from "./shared.js";
+export async function PostTestHelpersIssuingAuthorizations(ctx) {
+    const params = ctx.params;
+    const card = typeof params.card === 'string' ? params.card : '';
+    if (!card)
+        return fail(ctx, 'Missing required param: card.', 400, 'parameter_missing');
+    const c = ctx.get(CARD, card);
+    if (!c)
+        return fail(ctx, `No such card: '${card}'`, 400, 'resource_missing');
+    if (params.amount === undefined)
+        return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+    const amount = Math.trunc(Number(params.amount) || 0);
+    const currency = String(params.currency ?? c.currency ?? 'usd');
+    const createdSec = Number(nowUnix(ctx.occurredAt));
+    const cardholderId = holderId(c);
+    const merchant = merchantData(params.merchant_data);
+    const isAmountControllable = params.is_amount_controllable === true;
+    const authMethod = typeof params.authorization_method === 'string' ? params.authorization_method : 'online';
+    if (!['chip', 'contactless', 'keyed_in', 'online', 'swipe'].includes(authMethod))
+        return issuingRefusal(ctx, 'authorization_method');
+    const merchantAmount = params.merchant_amount !== undefined ? Math.trunc(Number(params.merchant_amount) || 0) : amount;
+    const merchantCurrency = typeof params.merchant_currency === 'string' ? params.merchant_currency : currency;
+    const authId = ctx.mint(AUTH);
+    const baseFields = {
+        amount, amount_details: null, authorization_method: authMethod,
+        balance_transactions: [], transactions: [],
+        currency, fleet: null, fuel: null, livemode: false,
+        merchant_amount: merchantAmount, merchant_currency: merchantCurrency, merchant_data: merchant,
+        metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
+        network_data: null,
+        verification_data: {
+            address_line1_check: 'not_provided', address_postal_code_check: 'not_provided',
+            authentication_exemption: null, cvc_check: 'match', expiry_check: 'match',
+            postal_code: null, three_d_secure: null,
+        },
+        wallet: null,
+    };
+    const subject = { id: authId, card, cardholder: cardholderId };
+    const entry = (o) => historyEntry({ ...o, currency, createdSec, merchantAmount, merchantCurrency });
+    const decline = async (reason, reasonMessage) => ctx.reply(withCard(ctx, await created(ctx, AUTH, subject, { ...baseFields, status: 'closed', approved: false, pending_request: null, request_history: [entry({ amount, approved: false, reason, reasonMessage })] })));
+    if (c.status === 'canceled')
+        return decline('card_canceled', 'The card has been canceled.');
+    // source: https://docs.stripe.com/api/issuing/cards/create "Defaults to inactive"
+    // source: spec:/components/schemas/issuing_authorization_request/properties/reason/enum "card_inactive"
+    if (c.status !== 'active')
+        return decline('card_inactive', 'The card is inactive.');
+    // what earlier approved authorizations on the card (or cardholder) already spent, for the limits
+    const prior = (key, value) => ctx.rows(AUTH).filter((a) => a[key] === value && a.approved === true)
+        .map((a) => ({ amount: Number(a.amount) || 0, created: Number(a.created) || 0, category: String(a.merchant_data?.category ?? '') }));
+    const controlsOpts = { amount, category: String(merchant.category ?? ''), country: merchant.country == null ? null : String(merchant.country), nowSec: createdSec };
+    const cardholderRow = cardholderId ? ctx.get(CH, cardholderId) : undefined;
+    const violation = spendingControlsViolation(c.spending_controls, { ...controlsOpts, priorApproved: prior('card', card) }) ??
+        spendingControlsViolation(cardholderRow?.spending_controls, { ...controlsOpts, priorApproved: prior('cardholder', cardholderId) });
+    if (violation)
+        return decline('spending_controls', violation);
+    // an authorization is paid from the Issuing balance, and declined when it cannot cover it
+    // (docs.stripe.com/issuing/funding/balance)
+    if ((balanceOf(ctx).issuing.get(currency) ?? 0) < amount)
+        return decline('insufficient_funds', 'Your Issuing balance does not have enough funds for this authorization.');
+    const pendingRequest = {
+        amount, amount_details: null, currency, is_amount_controllable: isAmountControllable,
+        merchant_amount: merchantAmount, merchant_currency: merchantCurrency, network_risk_score: null,
+    };
+    const endpoint = ctx.rows('webhook_endpoint').find((w) => w.status === 'enabled' && stripeEventMatches(w.enabled_events, 'issuing_authorization.request'));
+    // no real-time enrollment: "If you don't have a real-time authorization webhook, we approve the authorization without
+    // sending the issuing_authorization.request" (docs.stripe.com/issuing/purchases/authorizations), its outcome
+    // card_active, "approved according to your default Issuing settings"
+    if (!endpoint)
+        return approvedAtOnce(ctx, subject, baseFields, amount, entry({ amount, approved: true, reason: 'card_active', reasonMessage: null }));
+    // the request event's authorization carries pending_request, non-null only during the request
+    const requestObject = withCard(ctx, { object: 'issuing.authorization', id: authId, created: createdSec, ...baseFields, card, cardholder: cardholderId, status: 'pending', approved: false, pending_request: pendingRequest, request_history: [] });
+    // the request asked of the endpoint and the stored event are one event under one id
+    const pinned = ctx.call.request.headers.get('stripe-version');
+    const requestEvent = {
+        id: ctx.mint('event'), object: 'event', api_version: pinned && isValidApiVersion(pinned) ? pinned : TWIN_API_VERSION, created: createdSec,
+        data: { object: requestObject }, livemode: false, pending_webhooks: 1, request: { id: null, idempotency_key: null }, type: 'issuing_authorization.request',
+    };
+    await ctx.write('event', requestEvent.id, requestEvent, 'event.record');
+    const outcome = await askForAuthorization(ctx, String(endpoint.url), requestEvent, String(endpoint.secret ?? ''));
+    // a request no one answered (the World refused the delivery, it failed, or it timed out) is not a decision: the
+    // authorization stays pending with its request, for the deprecated approve or decline "within the timeout window of
+    // the real-time authorization flow" (the served spec), until lapseRealtimeRequests decides it when the window ends
+    if (outcome.kind === 'timeout')
+        return ctx.reply(withCard(ctx, await created(ctx, AUTH, subject, { ...baseFields, status: 'pending', approved: false, request_history: [], pending_request: pendingRequest })));
+    return answeredByEndpoint(ctx, outcome, { subject, fields: baseFields, amount, controllable: isAmountControllable, entry, decline });
 }
-export async function PostTestHelpersTestClocks(ctx) {
-    if (ctx.params.frozen_time === undefined)
-        return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
-    const frozen = Math.trunc(Number(ctx.params.frozen_time) || 0);
-    // "Simulations are automatically deleted 30 days after you create them" (docs.stripe.com/billing/testing/test-clocks/
-    // api-advanced-usage): from its creation on the account's clock, not its frozen time
-    return ctx.reply(await created(ctx, CLOCK, { name: ctx.params.name ?? null }, { frozen_time: frozen, status: 'ready', status_details: {}, livemode: false, deletes_after: Number(nowUnix(ctx.occurredAt)) + 30 * 24 * 3600 }));
-}
-export async function PostTestHelpersTestClocksTestClockAdvance(ctx) {
-    const id = at(ctx, 'test_clock');
-    const clock = ctx.get(CLOCK, id);
-    if (!clock)
-        return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
-    if (ctx.params.frozen_time === undefined)
-        return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
-    const to = Math.trunc(Number(ctx.params.frozen_time) || 0);
-    if (to <= Number(clock.frozen_time))
-        return fail(ctx, 'frozen_time must be after the current clock time.', 400, 'parameter_invalid');
-    const refused = ctx.legal(CLOCK, 'status', 'PostTestHelpersTestClocksTestClockAdvance', clock.status, 'advancing', id);
+export async function PostTestHelpersIssuingAuthorizationsAuthorizationCapture(ctx) {
+    const id = at(ctx, 'authorization');
+    const auth = ctx.get(AUTH, id);
+    if (!auth)
+        return authMissing(ctx, id);
+    if (auth.approved !== true || auth.status !== 'pending')
+        return issuingRefusal(ctx, 'not_capturable', auth);
+    const closeAuthorization = ctx.params.close_authorization !== false;
+    const refused = ctx.legal(AUTH, 'status', 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', auth.status, closeAuthorization ? 'closed' : 'pending');
     if (refused)
         return ctx.refuse(refused);
-    // "After a successful API request or Dashboard operation, it takes a few seconds to advance to the specified time"
-    // (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage): the advance answers advancing toward its target,
-    // and finishClockAdvances completes it ADVANCE_SECONDS of World time later; an advance asked meanwhile is refused
-    // test_clock_not_ready (the machine's refusal).
-    return ctx.reply(await ctx.write(CLOCK, id, { status: 'advancing', status_details: { advancing: { target_frozen_time: to } } }, 'test_clock.advancing'));
+    const txns = Array.isArray(auth.transactions) ? auth.transactions : [];
+    const capturedSoFar = txns.map((t) => ctx.get(TXN, String(t))).reduce((s, t) => s + Math.abs(Number(t?.amount) || 0), 0);
+    const remaining = (Number(auth.amount) || 0) - capturedSoFar;
+    const captureAmount = ctx.params.capture_amount !== undefined ? Math.trunc(Number(ctx.params.capture_amount) || 0) : remaining;
+    if (captureAmount <= 0 || captureAmount > remaining)
+        return fail(ctx, 'Invalid capture_amount: must be a positive integer no greater than the uncaptured authorized amount.', 400, 'parameter_invalid_integer');
+    // the capture releases what the approval held and debits the transaction; a capture that closes the authorization
+    // releases ALL it still holds, the uncaptured rest included: the amount is held "until the authorization is either
+    // captured, voided, or expired without capture" (docs.stripe.com/issuing/purchases/authorizations), and a closed
+    // authorization can be captured no further (close_authorization "Defaults to true. Set to false to enable
+    // multi-capture flows", the served spec). A capture that keeps it open releases only what it captured.
+    const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+    const released = closeAuthorization ? remaining : captureAmount;
+    const release = await created(ctx, 'balance_transaction', {}, {
+        amount: released, currency, fee: 0, net: released, type: 'issuing_authorization_release',
+        status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_release',
+        available_on: nowUnix(ctx.occurredAt), fee_details: [], source: id,
+    });
+    const captured = await capture(ctx, id, { ...auth, card: cardId(auth) }, captureAmount);
+    return ctx.reply(withCard(ctx, await ctx.write(AUTH, id, {
+        status: closeAuthorization ? 'closed' : 'pending',
+        transactions: [...txns, captured.txnId],
+        balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), release.id, captured.btId],
+    }, 'issuing_authorization.updated')));
 }

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

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

package/dist/src/semantics/webhook_endpoints.js

@@ -0,0 +1,26 @@
+import { asBool } from "../engine/stripe.js";
+import { WE } from "../engine/webhook-endpoints.js";
+import { created, fail } from "./shared.js";
+// an endpoint is enabled at once and signs each event with a secret of its own, answered by this create alone (the
+// around answers no other read of it)
+export async function PostWebhookEndpoints(ctx) {
+    const params = ctx.params;
+    // source: spec:PostWebhookEndpoints "The URL of the webhook endpoint."
+    if (typeof params.url !== 'string' || params.url === '')
+        return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
+    // source: spec:PostWebhookEndpoints "The list of events to enable for this endpoint."
+    if (params.enabled_events === undefined || params.enabled_events === '' || (Array.isArray(params.enabled_events) && !params.enabled_events.length))
+        return fail(ctx, 'Missing required param: enabled_events.', 400, 'parameter_missing');
+    const id = ctx.mint(WE);
+    // source: spec:/components/schemas/webhook_endpoint/properties/secret/description "The endpoint's secret, used to generate"
+    const secret = `whsec_${(await ctx.secret(`webhook-endpoint-secret:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 32)}`;
+    return ctx.reply(await created(ctx, WE, { ...params, id }, {
+        url: params.url, enabled_events: Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : [String(params.enabled_events)],
+        // source: spec:/components/schemas/webhook_endpoint/properties/status/description "The status of the webhook."
+        status: 'enabled', livemode: false, metadata: {}, application: null,
+        api_version: typeof params.api_version === 'string' ? params.api_version : null,
+        description: typeof params.description === 'string' ? params.description : null,
+        // source: spec:PostWebhookEndpoints "Whether this endpoint should receive events from connected accounts"
+        connect: asBool(params.connect), secret,
+    }));
+}

package/generated/pack-facts.json

@@ -28,11 +28,11 @@
         },
         {
           "host": "connect.stripe.com",
-          "pathPattern": "^/setup/|^/oauth/(authorize|token|deauthorize)/?$"
+          "pathPattern": "^/setup/"
         },
         {
           "host": "dashboard.stripe.com",
-          "pathPattern": "^/settings/public/?$|^/(test/)?settings/connect(/onboarding-options/oauth)?/?$"
+          "pathPattern": "^/radar/lists(?:/[^/]+)?/?$|^/test/issuing/balance/?$|^/settings/public/?$"
         },
         {
           "host": "verify.stripe.com",
@@ -40,7 +40,7 @@
         },
         {
           "host": "js.stripe.com",
-          "pathPattern": "^/v3/financial-connections/|^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$"
+          "pathPattern": "^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$"
         }
       ],
       "archetype": "crud",