@volter/twin-stripe 2.0.38 → 3.0.0

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

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

package/dist/src/semantics/balance_transactions.js

@@ -0,0 +1,15 @@
+import { inRange } from "../engine/common.js";
+import { BT } from "../engine/ledger.js";
+import { commonAsOf, kept, list, mine, newest, where } from "./shared.js";
+export async function GetBalanceTransactions(ctx) {
+    const own = mine(ctx);
+    return list(ctx, BT, where(ctx, newest(ctx, BT).filter((t) => own.has(t.id)).map((t) => commonAsOf(ctx, t)), {
+        type: (t, v) => t.type === v,
+        currency: (t, v) => t.currency === v,
+        source: (t, v) => t.source === v,
+        // an automatic payout lists the entries it paid out, its own debit among them
+        payout: (t, v) => t.source === v || kept(ctx, BT, t, '_payout') === v,
+        // a range of creation times (docs.stripe.com/api/balance_transactions/list#balance_transaction_list-created)
+        created: (t, v) => inRange(t.created, v),
+    }));
+}

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

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

package/dist/src/semantics/billing_portal.js

@@ -0,0 +1,42 @@
+import { filled, PBC, PORTAL_FEATURES } from "../engine/files.js";
+import { asBool, nowUnix } from "../engine/stripe.js";
+import { actingAccount, at, created, fail, list, mergeUpdate, newest, where } from "./shared.js";
+export async function GetBillingPortalConfigurations(ctx) {
+    return list(ctx, PBC, where(ctx, newest(ctx, PBC), {
+        active: (c, v) => asBool(c.active) === asBool(v),
+        is_default: (c, v) => asBool(c.is_default) === asBool(v),
+    }));
+}
+export async function PostBillingPortalConfigurations(ctx) {
+    return ctx.reply(await created(ctx, PBC, { ...ctx.params, business_profile: filled({ headline: null, privacy_policy_url: null, terms_of_service_url: null }, ctx.params.business_profile), features: filled(PORTAL_FEATURES, ctx.params.features) }, {
+        active: true, is_default: false, livemode: false,
+        login_page: { enabled: false, url: null },
+        metadata: {}, default_return_url: ctx.params.default_return_url ?? null,
+        updated: nowUnix(ctx.occurredAt),
+    }));
+}
+export async function PostBillingPortalConfigurationsConfiguration(ctx) {
+    const id = at(ctx, 'configuration');
+    if (!ctx.get(PBC, id))
+        return ctx.notFound(PBC, id);
+    return ctx.reply(await ctx.write(PBC, id, mergeUpdate(ctx, PBC, id, { ...ctx.params, updated: nowUnix(ctx.occurredAt) }), 'billing_portal.configuration.update'));
+}
+// ── the customer portal ──
+// the configuration defaults to the account's default one
+export async function PostBillingPortalSessions(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');
+    const configuration = typeof ctx.params.configuration === 'string' && ctx.params.configuration
+        ? ctx.params.configuration
+        : (ctx.rowsRaw('billing_portal.configuration', { withDeleted: true }).find((c) => c.is_default)?.id ?? 'bpc_twin_default');
+    const id = ctx.mint('billing_portal.session');
+    return ctx.reply(await created(ctx, 'billing_portal.session', {
+        id, customer, configuration, return_url: ctx.params.return_url ?? null, url: `https://billing.stripe.com/p/session/${id}`,
+        locale: ctx.params.locale ?? null, on_behalf_of: ctx.params.on_behalf_of ?? null, livemode: false,
+        // the account the session was made on (Stripe-Account), whose name the portal shows (screens/billing-portal.tsx)
+        ...(actingAccount(ctx) ? { _brand_account: actingAccount(ctx) } : {}),
+    }, {}));
+}

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

@@ -1,28 +1,3 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** Every egress of a charge carries its refunds, derived from the refund rows in list order. */
-export declare function chargeBody(ctx: SemanticsContext, c: Row): Row;
-/** A capture=false charge refunded while uncaptured: its authorization is released by the refund, as it would be
- *  "automatically refunded if uncaptured" (spec/openapi.json.gz, `capture_before`). The charge stays uncaptured and
- *  becomes refunded in full, a Refund records the release, and no money moves: none was ever received. Written as
- *  charge.refunded. Where the documentation stops and the twin decides: Stripe's basil change ("Partially capturing or
- *  canceling payments no longer creates a Refund", docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
- *  capture-and-payment-cancellation-flow) names partial capture and cancellation, not a refund asked for, so a refund
- *  still makes one; its reason is null and it has no balance transaction. Answers the Refund. */
-export declare function releaseAuthorization(ctx: SemanticsContext, ch: Row, operationId: string, given?: Row): Promise<Row>;
-/** A PaymentIntent's authorization released by its cancel: "For PaymentIntents with a `status` of `requires_capture`, the
- *  remaining `amount_capturable` is automatically refunded" (docs.stripe.com/api/payment_intents/cancel), and since basil
- *  a cancellation makes no Refund: "`amount_captured` will be 0 instead of `nil` in payment cancellation flows",
- *  "`amount_refunded` will no longer be updated by these actions", "`refunded` will no longer be `true` for payment
- *  cancellation flows", and no charge.refunded is sent (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-
- *  partial-capture-and-payment-cancellation-flow). The charge stays uncaptured; nothing is written as an event. */
-export declare function cancelAuthorization(ctx: SemanticsContext, ch: Row): Promise<Row>;
-/** An authorized charge captured, by the charge's capture or its PaymentIntent's: what is captured credits the balance.
- *  Written as charge.captured, "Occurs whenever a previously uncaptured charge is captured" (docs.stripe.com/api/events/types).
- *  A partial capture releases the rest with no Refund and leaves amount_refunded and refunded as they were: "The following
- *  flows no longer result in a `Refund` object created and linked to the payment: Partial capture", "`amount_refunded`
- *  will no longer be updated by these actions", and "There will only be a single balance transaction for partial captures"
- *  (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-capture-and-payment-cancellation-flow).
- *  The caller has asked the machine whether it may capture. */
-export declare function captureAuthorization(ctx: SemanticsContext, ch: Row, toCapture: number, _operationId: string): Promise<Row>;
-export declare const charges: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetCharges(ctx: HandlerContext): Promise<Response>;
+export declare function GetChargesCharge(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/charges.js

@@ -1,209 +1,12 @@
-import { asBool, cardError, chargeDefaults, declineFor, searchOver, validateMoney } from "../stripe-twin.js";
-import { afterCharge } from "./after-payment.js";
-import { settleCharge } from "./ledger.js";
-import { paymentMethodDetails } from "./payment-methods.js";
-import { refundCharge } from "./refunds.js";
-import { at, created, expanded, fail, finder, list, newest, path, refundDestination, send, where } from "./shared.js";
-const chargeMissing = (ctx, id) => fail(ctx, `No such charge: '${id}'`, 404, 'resource_missing');
-/** Every egress of a charge carries its refunds, derived from the refund rows in list order. */
-export function chargeBody(ctx, c) {
-    const data = newest(ctx, 'refund').filter((r) => r.charge === c.id);
-    return { ...c, refunds: { object: 'list', data, has_more: false, total_count: data.length, url: `/v1/charges/${String(c.id)}/refunds` } };
-}
-// A charge is written as the event Stripe sends for it (docs.stripe.com/api/events/types; Stripe has no
-// `charge.created`): charge.succeeded, "Occurs whenever a charge is successful", for one made or authorized
-// (capture=false: its status is succeeded, captured false), and charge.failed, "Occurs whenever a failed charge attempt
-// occurs", for a declined attempt. The twin makes no pending charge (charge.pending, "Occurs whenever a pending charge is
-// created"): its charges settle when made.
-/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
- *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
- *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
- *  CVC back on every read of the charge. */
-function withoutCard(params) {
-    const { card: _card, ...rest } = params;
-    return rest;
-}
-/** A Charges-API charge a declining test card refuses: a 402 card_error naming the failed charge Stripe records for the
- *  attempt (docs.stripe.com/declines). */
-async function declinedCharge(ctx, decline) {
-    const params = ctx.params;
-    const failedId = ctx.mint('charge');
-    const amount = Number(params.amount) || 0;
-    await created(ctx, 'charge', { ...withoutCard(params), id: failedId }, {
-        ...chargeDefaults(failedId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
-        failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
-        outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
-        payment_method_details: paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card) ?? null,
-    }, { operation: 'charge.failed' });
-    return send(ctx, cardError(decline, { charge: failedId }));
-}
-/** A charge's fraud report: "user_report … Assessments reported by you. If set, possible values of are `safe` and
- *  `fraudulent`" (docs.stripe.com/api/charges/object, fraud_details). */
-function fraudReport(ctx, existing, fd) {
-    const report = String(fd.user_report);
-    if (report !== 'safe' && report !== 'fraudulent')
-        return fail(ctx, "Invalid fraud_details[user_report]: must be 'safe' or 'fraudulent'.", 400, 'parameter_invalid_string_enum');
-    const prior = existing.fraud_details && typeof existing.fraud_details === 'object' ? existing.fraud_details : {};
-    return { user_report: report, stripe_report: prior.stripe_report ?? null };
-}
-const create = async (ctx) => {
-    const params = ctx.params;
-    const bad = validateMoney(params);
-    if (bad)
-        return send(ctx, bad);
-    // a declining test card answers a 402 card_error naming the failed charge Stripe records for the attempt
-    const decline = declineFor(finder(ctx), params);
-    if (decline)
-        return declinedCharge(ctx, decline);
-    // capture=false authorizes only: succeeded and paid, but not captured, with a capture deadline
-    const captured = !(params.capture !== undefined && !asBool(params.capture));
-    // the id comes first so the charge's own `refunds` list can carry its URL
-    const id = typeof params.id === 'string' && params.id ? params.id : ctx.mint('charge');
-    const amount = Number(params.amount) || 0;
-    // a captured charge credits the balance; an authorization does when it is captured
-    const card = String(params.source ?? params.payment_method ?? params.card?.number ?? '');
-    const bt = captured ? await settleCharge(ctx, id, amount, String(params.currency ?? 'usd'), card) : null;
-    const details = paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card);
-    await created(ctx, 'charge', { ...withoutCard(params), id }, { ...chargeDefaults(id, amount, captured, ctx.occurredAt), balance_transaction: bt, payment_method_details: details ?? null }, { operation: 'charge.succeeded' });
-    await afterCharge(ctx, id, { amount, currency: String(params.currency ?? 'usd'), application_fee_amount: params.application_fee_amount, destination: params.transfer_data?.destination }, params.payment_method ?? params.source ?? params.card);
-    return ctx.reply(chargeBody(ctx, ctx.get('charge', id)));
-};
-// capture takes `amount` (the whole authorization by default; docs.stripe.com/api/charges/capture); the rest of a
-// partial capture is released with no Refund (captureAuthorization). `amount_to_capture` is the
-// PaymentIntent capture's parameter, which a charge's capture does not know.
-const capture = async (ctx) => {
-    const id = at(ctx, 'charge');
-    const ch = ctx.get('charge', id);
-    if (!ch)
-        return chargeMissing(ctx, id);
-    const refused = ctx.legal('charge', 'captured', 'PostChargesChargeCapture', ch.captured === true ? 'true' : 'false', undefined, id);
-    if (refused)
-        return ctx.refuse(refused);
-    // "Capturing a charge will always succeed, unless the charge is already refunded, expired, captured, or an invalid
-    // capture amount is specified" (docs.stripe.com/api/charges/capture): a released authorization is refunded
-    if (ch.refunded === true)
-        return fail(ctx, `Charge ${id} has already been refunded.`, 400, 'charge_already_refunded');
-    // a canceled PaymentIntent's authorization is released: "After it's canceled, no additional charges are made by the
-    // PaymentIntent and any operations on the PaymentIntent fail with an error" (docs.stripe.com/api/payment_intents/cancel).
-    // Where the documentation stops and the twin decides: its charge's capture answers payment_intent_unexpected_state
-    // ("The PaymentIntent's state was incompatible with the operation", docs.stripe.com/error-codes), in the twin's words.
-    const intent = typeof ch.payment_intent === 'string' ? ctx.get('payment_intent', ch.payment_intent) : undefined;
-    if (intent?.status === 'canceled')
-        return fail(ctx, `Charge ${id} belongs to PaymentIntent ${String(intent.id)}, which is canceled; its authorization was released.`, 400, 'payment_intent_unexpected_state');
-    const full = Number(ch.amount) || 0;
-    const toCapture = ctx.params.amount !== undefined ? Math.min(full, Math.max(0, Math.trunc(Number(ctx.params.amount) || 0))) : full;
-    return ctx.reply(chargeBody(ctx, await captureAuthorization(ctx, ch, toCapture, 'PostChargesChargeCapture')));
-};
-/** A capture=false charge refunded while uncaptured: its authorization is released by the refund, as it would be
- *  "automatically refunded if uncaptured" (spec/openapi.json.gz, `capture_before`). The charge stays uncaptured and
- *  becomes refunded in full, a Refund records the release, and no money moves: none was ever received. Written as
- *  charge.refunded. Where the documentation stops and the twin decides: Stripe's basil change ("Partially capturing or
- *  canceling payments no longer creates a Refund", docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
- *  capture-and-payment-cancellation-flow) names partial capture and cancellation, not a refund asked for, so a refund
- *  still makes one; its reason is null and it has no balance transaction. Answers the Refund. */
-export async function releaseAuthorization(ctx, ch, operationId, given = {}) {
-    const id = String(ch.id);
-    const full = Number(ch.amount) || 0;
-    if (ch.refunded !== true)
-        ctx.legal('charge', 'refunded', operationId, 'false', 'true', id);
-    const refund = await created(ctx, 'refund', { ...given, charge: id, amount: full - (Number(ch.amount_refunded) || 0), currency: String(ch.currency ?? 'usd') }, {
-        status: 'succeeded', metadata: {}, reason: null, receipt_number: null,
-        balance_transaction: null, source_transfer_reversal: null, transfer_reversal: null, ...refundDestination(ch, 'reversal'),
-        ...(typeof ch.payment_intent === 'string' ? { payment_intent: ch.payment_intent } : {}),
-    });
-    await ctx.write('charge', id, { amount_refunded: full, refunded: true }, 'charge.refunded');
-    return refund;
-}
-/** A PaymentIntent's authorization released by its cancel: "For PaymentIntents with a `status` of `requires_capture`, the
- *  remaining `amount_capturable` is automatically refunded" (docs.stripe.com/api/payment_intents/cancel), and since basil
- *  a cancellation makes no Refund: "`amount_captured` will be 0 instead of `nil` in payment cancellation flows",
- *  "`amount_refunded` will no longer be updated by these actions", "`refunded` will no longer be `true` for payment
- *  cancellation flows", and no charge.refunded is sent (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-
- *  partial-capture-and-payment-cancellation-flow). The charge stays uncaptured; nothing is written as an event. */
-export async function cancelAuthorization(ctx, ch) {
-    return ctx.write('charge', String(ch.id), { amount_captured: 0 }, 'charge.authorization_released');
-}
-/** An authorized charge captured, by the charge's capture or its PaymentIntent's: what is captured credits the balance.
- *  Written as charge.captured, "Occurs whenever a previously uncaptured charge is captured" (docs.stripe.com/api/events/types).
- *  A partial capture releases the rest with no Refund and leaves amount_refunded and refunded as they were: "The following
- *  flows no longer result in a `Refund` object created and linked to the payment: Partial capture", "`amount_refunded`
- *  will no longer be updated by these actions", and "There will only be a single balance transaction for partial captures"
- *  (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-capture-and-payment-cancellation-flow).
- *  The caller has asked the machine whether it may capture. */
-export async function captureAuthorization(ctx, ch, toCapture, _operationId) {
-    const id = String(ch.id);
-    const bt = toCapture > 0 ? await settleCharge(ctx, id, toCapture, String(ch.currency ?? 'usd'), String(ch.source ?? ch.payment_method ?? '')) : null;
-    return ctx.write('charge', id, { captured: true, amount_captured: toCapture, balance_transaction: bt }, 'charge.captured');
-}
-const listCharges = async (ctx) => {
+import { at, chargeBody, chargeMissing, expanded, list, newest, where } from "./shared.js";
+export async function GetCharges(ctx) {
     const items = where(ctx, newest(ctx, 'charge'), {
         customer: (c, v) => c.customer === v,
         payment_intent: (c, v) => c.payment_intent === v,
     });
     return list(ctx, 'charge', items.map((c) => chargeBody(ctx, c)));
-};
-const searchCharges = async (ctx) => {
-    const found = searchOver(newest(ctx, 'charge'), ctx.params, path(ctx));
-    const body = found.body;
-    if (found.status === 200 && Array.isArray(body.data))
-        body.data = body.data.map((c) => chargeBody(ctx, c));
-    return send(ctx, found);
-};
-const retrieve = async (ctx) => {
+}
+export async function GetChargesCharge(ctx) {
     const c = ctx.get('charge', at(ctx, 'charge'));
     return c ? ctx.reply(expanded(ctx, 'charge', chargeBody(ctx, c))) : chargeMissing(ctx, at(ctx, 'charge'));
-};
-// fraud_details[user_report] marks a charge safe or fraudulent; Stripe keeps its own stripe_report
-const update = async (ctx) => {
-    const id = at(ctx, 'charge');
-    const existing = ctx.get('charge', id);
-    if (!existing)
-        return chargeMissing(ctx, id);
-    const fields = { ...ctx.params };
-    const fd = ctx.params.fraud_details;
-    const fraud = fd && typeof fd === 'object' && 'user_report' in fd ? fraudReport(ctx, existing, fd) : undefined;
-    if (fraud instanceof Response)
-        return fraud;
-    if (fraud)
-        fields.fraud_details = fraud;
-    return ctx.reply(chargeBody(ctx, await ctx.write('charge', id, fields, 'charge.update')));
-};
-// ── the charge's own refunds: listed, created and read through it; another charge's refund is not found ──
-const refunds = async (ctx) => {
-    const id = at(ctx, 'charge');
-    if (!ctx.get('charge', id))
-        return chargeMissing(ctx, id);
-    return list(ctx, 'refund', newest(ctx, 'refund').filter((r) => r.charge === id));
-};
-const createRefund = async (ctx) => {
-    const ch = ctx.get('charge', at(ctx, 'charge'));
-    if (!ch)
-        return chargeMissing(ctx, at(ctx, 'charge'));
-    return refundCharge(ctx, ch, ctx.params);
-};
-const chargeRefund = (ctx) => {
-    if (!ctx.get('charge', at(ctx, 'charge')))
-        return chargeMissing(ctx, at(ctx, 'charge'));
-    const r = ctx.get('refund', at(ctx, 'refund'));
-    return r && r.charge === at(ctx, 'charge') ? r : fail(ctx, `No such refund: '${at(ctx, 'refund')}'`, 404, 'resource_missing');
-};
-const refund = async (ctx) => {
-    const r = chargeRefund(ctx);
-    return r instanceof Response ? r : ctx.reply(r);
-};
-const updateRefund = async (ctx) => {
-    const r = chargeRefund(ctx);
-    return r instanceof Response ? r : ctx.reply(await ctx.write('refund', at(ctx, 'refund'), ctx.params, 'refund.update'));
-};
-export const charges = {
-    PostCharges: create,
-    PostChargesChargeCapture: capture,
-    GetCharges: listCharges,
-    GetChargesSearch: searchCharges,
-    GetChargesCharge: retrieve,
-    PostChargesCharge: update,
-    GetChargesChargeRefunds: refunds,
-    PostChargesChargeRefunds: createRefund,
-    GetChargesChargeRefundsRefund: refund,
-    PostChargesChargeRefundsRefund: updateRefund,
-};
+}

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

@@ -1,20 +1,3 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
- *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
- *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
- *  empty is not set, and metadata posted empty is {} (stripe-server.ts createMetadata, the top-level case). */
-export declare function nestedMetadata(given: unknown): Row | undefined;
-/** The card the customer entered on the page. */
-export type EnteredCard = {
-    number: string;
-    exp_month: number;
-    exp_year: number;
-};
-/** A line item of a one-time Price: a stored Price, or an inline `price_data`, without `recurring` ("Line items with
- *  one-time Prices will be on the initial invoice only", docs.stripe.com/api/checkout/sessions/create). */
-export declare function isOneTime(item: Row, priceData?: Row | null): boolean;
-/** The customer paying on the hosted page (src/screens/checkout.tsx): the external actor's move on the
- *  session's machine, then what the payment made, linked, and the session stored complete. */
-export declare function completeSession(ctx: SemanticsContext, id: string, existing: Row, details?: Row, card?: EnteredCard): Promise<Row | Response>;
-export declare const checkout: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function PostCheckoutSessions(ctx: HandlerContext): Promise<Response>;
+export declare function PostCheckoutSessionsSessionExpire(ctx: HandlerContext): Promise<Response>;