@volter/twin-stripe 2.0.38 → 3.0.0

package/dist/src/semantics/entitlements.js

@@ -1,52 +1,13 @@
-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'));
-};
+import { FEAT } from "../engine/entitlements.js";
+import { subscriptionItemPairs } from "../engine/stripe.js";
+import { fail, newest, path } from "./shared.js";
 // 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) => {
+export async function GetEntitlementsActiveEntitlements(ctx) {
     const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
     if (!customer)
         return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
@@ -86,10 +47,4 @@ const activeEntitlements = async (ctx) => {
             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,
-};
+}

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

@@ -0,0 +1,12 @@
+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. A plan is stored as
+ *  the recurring price it is, and its own events carry the plan object; 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,36 @@
+import { planOf } from "../engine/plans.js";
+import { embedIssuingAuthorizationCard, isValidApiVersion, PLATFORM_ACCOUNT_ID, TWIN_API_VERSION } from "../engine/stripe.js";
+import { render } from "../engine/version.js";
+import { connectionRevoked, finder } from "./shared.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. A plan is stored as
+ *  the recurring price it is, and its own events carry the plan object; 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 === 'price' && write.operation.startsWith('plan.') ? planOf(write.body)
+            : write.storedType === 'issuing_authorization' ? embedIssuingAuthorizationCard({ ...write.body }, finder(ctx))
+                : 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);
+    const withheld = account !== undefined && type !== 'account.application.deauthorized' && connectionRevoked(ctx, account);
+    return { $account: account, $version: eventVersion(write), ...(withheld ? { $send: false } : {}) };
+}
+/** 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,107 @@
+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 disputes from "./disputes.js";
+import * as entitlements from "./entitlements.js";
+import * as invoice_payments from "./invoice_payments.js";
+import * as invoiceitems from "./invoiceitems.js";
+import * as invoices from "./invoices.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 setup_intents from "./setup_intents.js";
+import * as subscription_items from "./subscription_items.js";
+import * as subscription_schedules from "./subscription_schedules.js";
+import * as subscriptions from "./subscriptions.js";
+import * as test_helpers from "./test_helpers.js";
+import * as transfers from "./transfers.js";
+export const stripeSemantics = {
+    DeleteInvoiceitemsInvoiceitem: invoiceitems.DeleteInvoiceitemsInvoiceitem,
+    DeleteInvoicesInvoice: invoices.DeleteInvoicesInvoice,
+    DeleteProductsId: products.DeleteProductsId,
+    DeleteSubscriptionItemsItem: subscription_items.DeleteSubscriptionItemsItem,
+    DeleteSubscriptionsSubscriptionExposedId: subscriptions.DeleteSubscriptionsSubscriptionExposedId,
+    DeleteTestHelpersTestClocksTestClock: test_helpers.DeleteTestHelpersTestClocksTestClock,
+    GetAccountsAccountExternalAccounts: accounts.GetAccountsAccountExternalAccounts,
+    GetAppsSecretsFind: apps.GetAppsSecretsFind,
+    GetBalance: balance.GetBalance,
+    GetBalanceTransactions: balance_transactions.GetBalanceTransactions,
+    GetBillingPortalConfigurations: billing_portal.GetBillingPortalConfigurations,
+    GetCharges: charges.GetCharges,
+    GetChargesCharge: charges.GetChargesCharge,
+    GetCustomersCustomer: customers.GetCustomersCustomer,
+    GetCustomersCustomerPaymentMethods: customers.GetCustomersCustomerPaymentMethods,
+    GetCustomersSearch: customers.GetCustomersSearch,
+    GetDisputesDispute: disputes.GetDisputesDispute,
+    GetEntitlementsActiveEntitlements: entitlements.GetEntitlementsActiveEntitlements,
+    GetInvoicePayments: invoice_payments.GetInvoicePayments,
+    GetInvoicesInvoice: invoices.GetInvoicesInvoice,
+    GetInvoicesInvoiceLines: invoices.GetInvoicesInvoiceLines,
+    GetPaymentMethodsPaymentMethod: payment_methods.GetPaymentMethodsPaymentMethod,
+    GetPrices: prices.GetPrices,
+    GetPricesPrice: prices.GetPricesPrice,
+    GetProducts: products.GetProducts,
+    GetProductsSearch: products.GetProductsSearch,
+    GetPromotionCodes: promotion_codes.GetPromotionCodes,
+    GetRefundsRefund: refunds.GetRefundsRefund,
+    GetSubscriptionItemsItem: subscription_items.GetSubscriptionItemsItem,
+    GetSubscriptionSchedulesSchedule: subscription_schedules.GetSubscriptionSchedulesSchedule,
+    GetSubscriptions: subscriptions.GetSubscriptions,
+    GetSubscriptionsSearch: subscriptions.GetSubscriptionsSearch,
+    GetSubscriptionsSubscriptionExposedId: subscriptions.GetSubscriptionsSubscriptionExposedId,
+    PostAccountLinks: account_links.PostAccountLinks,
+    PostAccounts: accounts.PostAccounts,
+    PostAccountsAccountLoginLinks: accounts.PostAccountsAccountLoginLinks,
+    PostAppsSecrets: apps.PostAppsSecrets,
+    PostAppsSecretsDelete: apps.PostAppsSecretsDelete,
+    PostBillingPortalConfigurations: billing_portal.PostBillingPortalConfigurations,
+    PostBillingPortalConfigurationsConfiguration: billing_portal.PostBillingPortalConfigurationsConfiguration,
+    PostBillingPortalSessions: billing_portal.PostBillingPortalSessions,
+    PostCheckoutSessions: checkout.PostCheckoutSessions,
+    PostCheckoutSessionsSessionExpire: checkout.PostCheckoutSessionsSessionExpire,
+    PostCoupons: coupons.PostCoupons,
+    PostCustomers: customers.PostCustomers,
+    PostCustomersCustomerBalanceTransactions: customers.PostCustomersCustomerBalanceTransactions,
+    PostInvoiceitems: invoiceitems.PostInvoiceitems,
+    PostInvoices: invoices.PostInvoices,
+    PostInvoicesCreatePreview: invoices.PostInvoicesCreatePreview,
+    PostInvoicesInvoiceFinalize: invoices.PostInvoicesInvoiceFinalize,
+    PostInvoicesInvoicePay: invoices.PostInvoicesInvoicePay,
+    PostInvoicesInvoiceSend: invoices.PostInvoicesInvoiceSend,
+    PostInvoicesInvoiceVoid: invoices.PostInvoicesInvoiceVoid,
+    PostPaymentIntents: payment_intents.PostPaymentIntents,
+    PostPaymentIntentsIntentCancel: payment_intents.PostPaymentIntentsIntentCancel,
+    PostPaymentIntentsIntentConfirm: payment_intents.PostPaymentIntentsIntentConfirm,
+    PostPaymentMethods: payment_methods.PostPaymentMethods,
+    PostPaymentMethodsPaymentMethodAttach: payment_methods.PostPaymentMethodsPaymentMethodAttach,
+    PostPaymentMethodsPaymentMethodDetach: payment_methods.PostPaymentMethodsPaymentMethodDetach,
+    PostPayouts: payouts.PostPayouts,
+    PostPrices: prices.PostPrices,
+    PostProducts: products.PostProducts,
+    PostPromotionCodes: promotion_codes.PostPromotionCodes,
+    PostRadarValueListItems: radar.PostRadarValueListItems,
+    PostRefunds: refunds.PostRefunds,
+    PostSetupIntents: setup_intents.PostSetupIntents,
+    PostSetupIntentsIntentConfirm: setup_intents.PostSetupIntentsIntentConfirm,
+    PostSubscriptionItems: subscription_items.PostSubscriptionItems,
+    PostSubscriptionItemsItem: subscription_items.PostSubscriptionItemsItem,
+    PostSubscriptionSchedules: subscription_schedules.PostSubscriptionSchedules,
+    PostSubscriptionSchedulesScheduleRelease: subscription_schedules.PostSubscriptionSchedulesScheduleRelease,
+    PostSubscriptions: subscriptions.PostSubscriptions,
+    PostSubscriptionsSubscriptionExposedId: subscriptions.PostSubscriptionsSubscriptionExposedId,
+    PostTestHelpersTestClocks: test_helpers.PostTestHelpersTestClocks,
+    PostTestHelpersTestClocksTestClockAdvance: test_helpers.PostTestHelpersTestClocksTestClockAdvance,
+    PostTransfers: transfers.PostTransfers,
+};

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/invoiceitems.d.ts

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

package/dist/src/semantics/invoiceitems.js

@@ -0,0 +1,59 @@
+import { INV, linesOf } from "../engine/invoices.js";
+import { nowUnix } from "../engine/stripe.js";
+import { at, created, fail, invoiceMissing, itemMissing, pricedItem, resyncDraftLines, writeLines } from "./shared.js";
+// an item is deleted only while its invoice is still editable
+export async function DeleteInvoiceitemsInvoiceitem(ctx) {
+    const id = at(ctx, 'invoiceitem');
+    const it = ctx.get('invoiceitem', id);
+    if (!it)
+        return itemMissing(ctx, id);
+    const onInvoice = typeof it.invoice === 'string' ? ctx.get(INV, it.invoice) : undefined;
+    if (onInvoice && onInvoice.status !== 'draft')
+        return fail(ctx, 'You cannot delete an invoice item that is attached to an invoice that is no longer editable.', 400, 'invoice_not_editable');
+    await ctx.write('invoiceitem', id, { deleted: true }, 'invoiceitem.delete');
+    if (typeof it.invoice === 'string')
+        await resyncDraftLines(ctx, it.invoice);
+    return ctx.reply({ id, object: 'invoiceitem', deleted: true });
+}
+export async function PostInvoiceitems(ctx) {
+    const params = ctx.params;
+    const now = Number(nowUnix(ctx.occurredAt));
+    const qty = Number(params.quantity) || 1;
+    // the served version names the price in `pricing[price]` ("The pricing information for the invoice item", the served
+    // spec); an older version sends `price`. It is kept as the item's price, which the answer renders as `pricing`
+    // (../engine/version.ts)
+    const { pricing: pricingParam, ...stored } = params;
+    const given = pricingParam?.price;
+    const priceRef = typeof given === 'string' && given ? given : typeof params.price === 'string' ? params.price : '';
+    const priced = priceRef ? pricedItem(ctx, priceRef, qty) : undefined;
+    if (priced instanceof Response)
+        return priced;
+    const resolvedAmount = priced?.amount;
+    let resolvedCurrency = priced?.currency;
+    // only a draft invoice takes new items
+    const invoiceRef = typeof params.invoice === 'string' ? params.invoice : '';
+    let target;
+    if (invoiceRef) {
+        target = ctx.get(INV, invoiceRef);
+        if (!target)
+            return invoiceMissing(ctx, invoiceRef);
+        if (target.status !== 'draft')
+            return fail(ctx, `This invoice cannot have invoice items added because it has status ${String(target.status)}.`, 400, 'invoice_not_editable');
+        if (resolvedCurrency === undefined && typeof target.currency === 'string')
+            resolvedCurrency = target.currency;
+    }
+    // an invoice item is dated by `date`, not `created`; its currency is the price's, else the invoice's
+    const item = await created(ctx, 'invoiceitem', { ...stored, ...(priceRef ? { price: priceRef } : {}) }, {
+        livemode: false, discountable: true, proration: false, quantity: qty, quantity_decimal: String(qty),
+        period: { start: now, end: now }, currency: resolvedCurrency ?? 'usd',
+        ...(resolvedAmount !== undefined ? { amount: resolvedAmount } : {}),
+    }, { timeField: 'date' });
+    if (target) {
+        await writeLines(ctx, invoiceRef, [...linesOf(target), {
+                id: `il_${String(item.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(item.amount) || 0, currency: String(target.currency ?? item.currency ?? 'usd'),
+                quantity: qty, proration: false, invoice_item: item.id, price: item.price ?? null,
+                period: item.period ?? { start: now, end: now }, description: item.description ?? null,
+            }]);
+    }
+    return ctx.reply(item);
+}

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

@@ -1,18 +1,16 @@
-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 DeleteInvoicesInvoice(ctx: HandlerContext): Promise<Response>;
+export declare function GetInvoicesInvoice(ctx: HandlerContext): Promise<Response>;
+export declare function GetInvoicesInvoiceLines(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 with `subscription_details.proration_date` a credit for the unused period against a
+ * charge for the new one (split evenly: there is no clock here to measure the remaining fraction).
+ */
+export declare function PostInvoicesCreatePreview(ctx: HandlerContext): Promise<Response>;
+export declare function PostInvoicesInvoiceFinalize(ctx: HandlerContext): Promise<Response>;
+export declare function PostInvoicesInvoicePay(ctx: HandlerContext): Promise<Response>;
+export declare function PostInvoicesInvoiceSend(ctx: HandlerContext): Promise<Response>;
+export declare function PostInvoicesInvoiceVoid(ctx: HandlerContext): Promise<Response>;