@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/engine/refunds.js

@@ -0,0 +1,28 @@
+// Refund semantics. A refund always names what it took money out of and lands there: a refund
+// naming nothing, an id nobody minted, or more than the charge has left is refused as Stripe
+// refuses it. The machine in ../manifest.ts says only a refund waiting on the customer
+// (requires_action) may be canceled. List and update are the derived core's.
+//
+// Refunding a destination charge can take back the connected account's share (reverse_transfer: a reversal of the
+// charge's transfer, in proportion to the refund) and the platform's (refund_application_fee: a refund of the
+// application fee, in proportion) (docs.stripe.com/api/refunds/create#create_refund-reverse_transfer,
+// docs.stripe.com/connect/destination-charges#issue-refunds). Where the documentation stops and the twin decides: the
+// twin's destination charge transfers the amount less the fee (the fee is kept back rather than collected from the
+// connected account), so a fee refund moves no money of its own; the reversal and the refund settle both shares.
+//
+// A payment made by bank transfer (from the customer's cash balance) is refunded to the customer's bank account: Stripe
+// emails the customer (instructions_email, else the customer's email) for their bank details and the refund waits in
+// requires_action, moving no money, until they answer; only then can it still be canceled. With origin=customer_balance
+// it goes back to the cash balance at once (docs.stripe.com/payments/customer-balance/refunding,
+// docs.stripe.com/api/refunds/cancel). Where the documentation stops and the twin decides: the customer never answers
+// the email in the World, and its link expires 30 days on.
+//
+// An uncaptured charge holds an authorization, not money. A PaymentIntent's is not refunded: "the charge attached to the
+// PaymentIntent remains uncaptured and can't be refunded directly. You must cancel the PaymentIntent"
+// (docs.stripe.com/refunds), which releases it (charges.ts cancelAuthorization). A charge made with capture=false is
+// released by its refund, as its authorization would be "automatically refunded if uncaptured" (spec/openapi.json.gz,
+// `capture_before`): refunded in full, no balance moved, and its capture refused afterwards. Where the documentation
+// stops and the twin decides: the refusal's code (payment_intent_unexpected_state) and wording, and that a refund of a
+// capture=false charge releases the whole authorization, so an `amount` short of it is refused.
+// the reasons a caller may give; `expired_uncaptured_charge` is Stripe's own
+export const REFUND_REASONS = new Set(['duplicate', 'fraudulent', 'requested_by_customer']);

package/dist/src/engine/renewals.d.ts

@@ -0,0 +1,36 @@
+import type { Row } from './common.js';
+export declare const SUB = "subscription";
+export declare const INV = "invoice";
+export declare const HOUR = 3600;
+/** The statuses a subscription renews in. */
+export declare const RENEWING: string[];
+export declare const itemsOf: (sub: Row) => Row[];
+/** An item's quantity as it bills: 1 when none is set, and 0 when 0 is (a quantity of 0 bills nothing). */
+export declare function itemQuantity(it: Row): number;
+/** The subscription's discounts with a `once` coupon's spent: "When a subscription uses a coupon with `duration=once`, the
+ *  coupon is considered used after the invoice finalizes and is removed from the subscription's `discounts` array"
+ *  (docs.stripe.com/billing/subscriptions/coupons#coupon-duration). */
+export declare function unspentDiscounts(discounts: unknown): Row[];
+/** The coupon ids an invoice's discounts name. */
+export declare const couponsOf: (discounts: unknown) => Set<string>;
+/** A subscription's discounts after `invoice` finalizes: less the `once` coupons it took. */
+export declare function keptAfter(discounts: Row[], invoice: Row): Row[];
+/** A Checkout session's one-time line items as lines of its subscription's first invoice, numbered after its `after` lines. */
+export declare function oneTimeLines(invoiceId: string, sub: Row, items: Row[], after: number, at: number, currency: string): {
+    id: string;
+    object: string;
+    type: string;
+    amount: number;
+    currency: string;
+    quantity: number;
+    proration: boolean;
+    price: Row | null;
+    subscription: unknown;
+    subscription_item: null;
+    invoice_item: null;
+    period: {
+        start: number;
+        end: number;
+    };
+    description: string | null;
+}[];

package/dist/src/engine/renewals.js

@@ -0,0 +1,65 @@
+// A subscription's invoices over time: the first one Checkout pays, and each renewal. Time's moves are made
+// as the twin's trial end already made them: caught up to the customer's clock (the World's, or its test
+// clock) whenever the twin is asked anything (./front.ts), each checked against the machines in
+// ../manifest.ts.
+//
+// - Checkout's subscription session pays the first invoice with the card the customer entered, which becomes the
+//   subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works); nothing is due
+//   on a trial's.
+// - At each period's end Stripe drafts a `subscription_cycle` invoice for the next period and advances the
+//   period; a trial's end is the first such renewal, and the subscription is active from then
+//   (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions,
+//   docs.stripe.com/billing/subscriptions/trials).
+// - About an hour after, Stripe finalizes the draft and charges the subscription's default payment method,
+//   else the customer's (docs.stripe.com/invoicing/integration/workflow-transitions#finalized,
+//   docs.stripe.com/api/subscriptions/object#subscription_object-default_payment_method).
+// - A declined renewal leaves the invoice open with its attempt counted and the subscription past_due
+//   (docs.stripe.com/billing/subscriptions/overview#payment-status); paying the invoice later, through the API
+//   (docs.stripe.com/api/invoices/pay) or on the customer portal (docs.stripe.com/customer-management), makes it
+//   active again.
+//
+// Where the documentation stops and the twin decides: Stripe retries a failed renewal on its Smart Retries
+// schedule and may then cancel or mark the subscription unpaid; the twin makes no retry (next_payment_attempt
+// is null) and leaves it past_due until the invoice is paid. A paused subscription (pause_collection) is not renewed.
+// - One set to cancel at its period's end is canceled when the period ends, with no renewal
+//   (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle).
+import { priceAmount } from "./stripe.js";
+export const SUB = 'subscription';
+export const INV = 'invoice';
+export const HOUR = 3600;
+/** The statuses a subscription renews in. */
+export const RENEWING = ['trialing', 'active', 'past_due'];
+export const itemsOf = (sub) => (sub.items?.data) ?? [];
+/** An item's quantity as it bills: 1 when none is set, and 0 when 0 is (a quantity of 0 bills nothing). */
+export function itemQuantity(it) {
+    return it.quantity === undefined || it.quantity === null ? 1 : Math.max(0, Math.trunc(Number(it.quantity) || 0));
+}
+/** The subscription's discounts with a `once` coupon's spent: "When a subscription uses a coupon with `duration=once`, the
+ *  coupon is considered used after the invoice finalizes and is removed from the subscription's `discounts` array"
+ *  (docs.stripe.com/billing/subscriptions/coupons#coupon-duration). */
+export function unspentDiscounts(discounts) {
+    return (discounts ?? []).filter((d) => !(d && typeof d === 'object' && d.coupon?.duration === 'once'));
+}
+/** The coupon ids an invoice's discounts name. */
+export const couponsOf = (discounts) => new Set((discounts ?? []).map((d) => {
+    const c = d && typeof d === 'object' ? d.coupon : undefined;
+    return typeof c === 'string' ? c : c && typeof c === 'object' ? String(c.id ?? '') : '';
+}).filter(Boolean));
+/** A subscription's discounts after `invoice` finalizes: less the `once` coupons it took. */
+export function keptAfter(discounts, invoice) {
+    const taken = couponsOf(invoice.discounts);
+    return discounts.filter((d) => !(unspentDiscounts([d]).length === 0 && [...couponsOf([d])].some((c) => taken.has(c))));
+}
+/** A Checkout session's one-time line items as lines of its subscription's first invoice, numbered after its `after` lines. */
+export function oneTimeLines(invoiceId, sub, items, after, at, currency) {
+    return items.map((it, i) => {
+        const price = it.price && typeof it.price === 'object' ? it.price : null;
+        const quantity = itemQuantity(it);
+        return {
+            id: `il_twin_${invoiceId}_${after + i + 1}`, object: 'line_item', type: 'subscription',
+            amount: priceAmount(price ?? undefined, quantity), currency, quantity, proration: false,
+            price, subscription: sub.id, subscription_item: null, invoice_item: null,
+            period: { start: at, end: at }, description: typeof it.description === 'string' ? it.description : null,
+        };
+    });
+}

package/dist/src/engine/setup-intents.d.ts

@@ -0,0 +1 @@
+export declare const SI = "setup_intent";

package/dist/src/engine/setup-intents.js

@@ -0,0 +1,4 @@
+// SetupIntent semantics. The machine in ../manifest.ts says which moves of `status` are legal and
+// what Stripe answers otherwise; these handlers compute what each move does. List, retrieve and
+// update are the derived core's.
+export const SI = 'setup_intent';

package/dist/src/{stripe-twin.d.ts → engine/stripe.d.ts}

@@ -1,18 +1,10 @@
-export type StripeRequest = {
-    method: string;
-    path: string;
-    body?: string;
-    occurredAt?: string;
-    root?: string;
-    readOnly?: boolean;
-    idempotencyKey?: string;
-    apiVersion?: string;
-    stripeAccount?: string;
-};
+import { type TwinResource } from '@volter/world-core';
 export type StripeResponse = {
     status: number;
     body: unknown;
 };
+/** Stripe's error body: an invalid_request_error with the message, and the code when there is one. */
+export declare function err(message: string, status?: number, code?: string): StripeResponse;
 export declare const TWIN_API_VERSION: string;
 export declare function isValidApiVersion(v: string): boolean;
 export declare function validateMoney(params: Record<string, unknown>): StripeResponse | null;
@@ -23,7 +15,7 @@ type DeclineOutcome = {
 };
 export declare const TEST_TOKEN_DECLINES: Record<string, DeclineOutcome | null>;
 /** A stored subject by stored type and id, in the pack's view (tombstones included): how the
- *  semantics hand these helpers the tree they read (semantics/shared.ts `finder`). */
+ *  semantics hand these helpers the tree they read (./common.ts `finder`). */
 export type FindStored = (storedType: string, id: string) => Record<string, unknown> | undefined;
 export declare function declineFor(find: FindStored, ...paramSets: Array<Record<string, unknown>>): DeclineOutcome | null | undefined;
 export declare function requiresAuthentication(...paramSets: Array<Record<string, unknown>>): boolean;
@@ -38,21 +30,17 @@ export declare function cardError(outcome: DeclineOutcome, attach?: {
     payment_intent?: Record<string, unknown>;
 }): StripeResponse;
 export declare function nowUnix(occurredAt?: string): number;
-export declare function mintClientSecret(id: string): string;
+/** An intent's client secret: its id, `_secret_`, and a secret the World holds for it (ctx.secret, passed in), so no one
+ *  derives it from the intent's id; Stripe.js confirms an intent with it and the publishable key. */
+export declare function mintClientSecret(id: string, secret: string): string;
 export declare const OBJECT_NAME: Record<string, string>;
-export declare function view(type: string, r: Record<string, unknown>): Record<string, unknown>;
+/** A stored row as Stripe answers it: its `object`, its own fields (the vendor's `type` among them, which the tree's
+ *  shadows: world-core ownFields) without the twin's `_` bookkeeping, and its id. */
+export declare function view(type: string, r: TwinResource): Record<string, unknown>;
 export declare function paginate(items: Array<Record<string, unknown>>, params: Record<string, unknown>): {
     page: Array<Record<string, unknown>>;
     hasMore: boolean;
 };
-/** What follows every stored Stripe write: the webhook for the state change and the stored Event
- *  the Events API lists. The derived pack's write hook (manifest.ts) is this same function. */
-export declare function afterStripeWrite(type: string, op: string, out: Record<string, unknown>, root?: string, occurredAt?: string, apiVersion?: string, stripeAccount?: string): Promise<void>;
-/** The id the World's next event takes: its place in the World's events, so it is deterministic and never repeats
- *  within a World (a Balance has no id of its own, so nothing about the object can tell two events apart). The number
- *  is taken synchronously — the count of stored events, or the last number taken, whichever is higher. */
-export declare function nextStripeEventId(root?: string): string;
-export declare function persistStripeEvent(eventType: string, resource: Record<string, unknown>, root?: string, occurredAt?: string, apiVersion?: string, account?: string, id?: string): Promise<void>;
 export declare function asBool(v: unknown): boolean;
 export declare function searchOver(items: Array<Record<string, unknown>>, params: Record<string, unknown>, path: string): StripeResponse;
 export declare function subscriptionHasPrice(sub: Record<string, unknown>, priceId: string): boolean;
@@ -93,8 +81,7 @@ export declare function resolveTrial(params: Record<string, unknown>, at: number
     start: number;
     end: number;
 } | undefined;
-export declare function stashVendorType(_type: string, fields: Record<string, unknown>): Record<string, unknown>;
-export declare function embedIssuingAuthorizationCard(body: Record<string, unknown>, root?: string): Record<string, unknown>;
+export declare function embedIssuingAuthorizationCard(body: Record<string, unknown>, find: FindStored): Record<string, unknown>;
 export declare function emptySpendingControls(): Record<string, unknown>;
 export declare function normalizeSpendingControls(raw: unknown, currency: string | null): {
     controls?: Record<string, unknown>;
@@ -137,19 +124,4 @@ export declare function resolveLineItem(entry: Record<string, unknown>, index: n
 };
 export declare function lineItemEntries(params: Record<string, unknown>): Array<Record<string, unknown>>;
 export declare function chargeDefaults(chargeId: string, amount: number, captured: boolean, occurredAt?: string): Record<string, unknown>;
-/**
- * Public entry: honors the Idempotency-Key (replay → stored response, no re-write)
- * then delegates to the router. Only POSTs are idempotent (matches Stripe; GET/DELETE
- * pass straight through). A read-only twin never stores (it cannot write).
- */
-/** Stripe's API as one call: the request goes through the pack's own dispatch (the derived dispatch over
- *  its semantics, its derived core and the hand-written routes below), so a caller that holds no
- *  HTTP server reaches exactly what an SDK does. `occurredAt` pins the World instant. */
-export declare function handleStripeTwinRequest(req: StripeRequest): Promise<StripeResponse>;
-/**
- * The twin's doors: what stands in for an act Stripe's API does not have, each under `/_twin/`. The
- * platform's own account settings (its payout schedule) change on Stripe's Dashboard, which has no API:
- * POST /_twin/account stands in for that page. Answers nothing for any other path.
- */
-export declare function handleStripeDoor(req: StripeRequest, params: Record<string, unknown>): Promise<StripeResponse | undefined>;
 export {};