@volter/twin-stripe 0.1.1 → 2.0.0

package/dist/src/semantics/disputes.js

@@ -0,0 +1,51 @@
+import { asBool } from "../stripe-twin.js";
+import { settleDisputeWon } from "./ledger.js";
+import { at, fail } from "./shared.js";
+const disputeMissing = (ctx, id) => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
+const retrieve = async (ctx) => {
+    const d = ctx.get('dispute', at(ctx, 'dispute'));
+    return d ? ctx.reply(d) : disputeMissing(ctx, at(ctx, 'dispute'));
+};
+const close = async (ctx) => {
+    const id = at(ctx, 'dispute');
+    const d = ctx.get('dispute', id);
+    if (!d)
+        return disputeMissing(ctx, id);
+    const refused = ctx.legal('dispute', 'status', 'PostDisputesDisputeClose', d.status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    return ctx.reply(await ctx.write('dispute', id, { status: 'lost' }, 'dispute.close'));
+};
+/** Evidence staged without submitting it (submit=false), or on a dispute already under review or decided. */
+async function keepEvidence(ctx, id, fields) {
+    return ctx.reply(await ctx.write('dispute', id, fields, 'dispute.update'));
+}
+const update = async (ctx) => {
+    const id = at(ctx, 'dispute');
+    const d = ctx.get('dispute', id);
+    if (!d)
+        return disputeMissing(ctx, id);
+    const params = ctx.params;
+    const given = params.evidence && typeof params.evidence === 'object' ? params.evidence : {};
+    const evidence = { ...(d.evidence ?? {}), ...given };
+    const fields = { evidence, ...(params.metadata && typeof params.metadata === 'object' ? { metadata: { ...(d.metadata ?? {}), ...params.metadata } } : {}) };
+    const submit = params.submit === undefined ? true : asBool(params.submit);
+    const review = d.status === 'warning_needs_response' ? 'warning_under_review' : 'under_review';
+    if (!submit || ctx.legal('dispute', 'status', 'PostDisputesDispute', d.status, review, id))
+        return keepEvidence(ctx, id, fields);
+    const details = d.evidence_details ?? {};
+    let body = await ctx.write('dispute', id, { ...fields, status: review, evidence_details: { ...details, has_evidence: true, submission_count: (Number(details.submission_count) || 0) + 1 } }, 'charge.dispute.updated');
+    const text = String(evidence.uncategorized_text ?? '');
+    const decided = review === 'under_review' ? (text.includes('winning_evidence') ? 'won' : text.includes('losing_evidence') ? 'lost' : undefined) : undefined;
+    if (decided && !ctx.legal('dispute', 'status', 'PostDisputesDispute', review, decided, id, 'vendor')) {
+        const bt = decided === 'won' ? await settleDisputeWon(ctx, id, Number(d.amount) || 0, String(d.currency ?? 'usd')) : undefined;
+        const kept = (ctx.get('dispute', id)?.balance_transactions ?? []);
+        body = await ctx.write('dispute', id, { status: decided, ...(bt ? { balance_transactions: [...kept, ctx.get('balance_transaction', bt) ?? bt] } : {}) }, 'charge.dispute.closed');
+    }
+    return ctx.reply(body);
+};
+export const disputes = {
+    GetDisputesDispute: retrieve,
+    PostDisputesDispute: update,
+    PostDisputesDisputeClose: close,
+};

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

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

package/dist/src/semantics/entitlements.js

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

package/dist/src/semantics/ephemeral-keys.d.ts

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

package/dist/src/semantics/ephemeral-keys.js

@@ -0,0 +1,34 @@
+import { at, fail } from "./shared.js";
+const create = async (ctx) => {
+    const version = ctx.call.request.headers.get('stripe-version');
+    if (!version)
+        return fail(ctx, 'You must pass the `Stripe-Version` header (e.g. via the apiVersion option) when creating an ephemeral key.', 400, 'parameter_missing');
+    const params = ctx.params;
+    const scopes = [];
+    if (typeof params.customer === 'string' && params.customer)
+        scopes.push(['customer', params.customer]);
+    if (typeof params.issuing_card === 'string' && params.issuing_card)
+        scopes.push(['issuing.card', params.issuing_card]);
+    if (typeof params.verification_session === 'string' && params.verification_session)
+        scopes.push(['identity.verification_session', params.verification_session]);
+    if (scopes.length !== 1)
+        return fail(ctx, 'You must pass exactly one of `customer`, `issuing_card`, or `verification_session`.', 400, 'parameter_missing');
+    const [scope, scopedId] = scopes[0];
+    if (scope === 'customer' && !ctx.get('customer', scopedId))
+        return fail(ctx, `No such customer: '${scopedId}'`, 400, 'resource_missing');
+    const id = ctx.mint('ephemeral_key');
+    const now = Number(ctx.now());
+    const associated_objects = [{ type: scope, id: scopedId }];
+    await ctx.write('ephemeral_key', id, { object: 'ephemeral_key', created: now, expires: now + 3600, livemode: false, associated_objects }, 'ephemeral_key.create');
+    return ctx.reply({ id, object: 'ephemeral_key', created: now, expires: now + 3600, livemode: false, secret: `ek_test_twin_${id}`, associated_objects });
+};
+const expire = async (ctx) => {
+    const id = at(ctx, 'key');
+    if (!ctx.get('ephemeral_key', id))
+        return fail(ctx, `No such ephemeral key: '${id}'`, 404, 'resource_missing');
+    return ctx.reply(await ctx.write('ephemeral_key', id, { expires: ctx.now() }, 'ephemeral_key.delete'));
+};
+export const ephemeralKeys = {
+    PostEphemeralKeys: create,
+    DeleteEphemeralKeysKey: expire,
+};

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

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

package/dist/src/semantics/files.js

@@ -0,0 +1,125 @@
+import { asBool } from "../stripe-twin.js";
+import { actingAccount } from "./ledger.js";
+import { at, created, fail, filePurposeRefused, list, mergeUpdate, newest, where } from "./shared.js";
+/** The type Stripe answers for an uploaded file: "The returned file type (for example, csv, pdf, jpg, or png)"
+ *  (docs.stripe.com/api/files/object). Where the documentation stops and the twin decides: read from the name's
+ *  extension (jpeg as jpg), and null for a name without one. */
+function fileType(name) {
+    const ext = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
+    return ext ? (ext === 'jpeg' ? 'jpg' : ext) : null;
+}
+// multipart on Stripe; the file is described by the part uploaded: its name, its size in bytes and its type
+const createFile = async (ctx) => {
+    const purpose = typeof ctx.params.purpose === 'string' ? ctx.params.purpose : '';
+    if (!purpose)
+        return fail(ctx, 'Missing required param: purpose.', 400, 'parameter_missing');
+    const part = ctx.params.file && typeof ctx.params.file === 'object' ? ctx.params.file : undefined;
+    const filename = typeof ctx.params.file === 'string' ? ctx.params.file : typeof part?.name === 'string' ? part.name : 'twin_upload';
+    const made = await created(ctx, 'file', { purpose }, {
+        filename, size: typeof part?.size === 'number' ? part.size : 0,
+        type: fileType(filename), title: null, expires_at: null, url: null,
+        links: { object: 'list', data: [], has_more: false, total_count: 0, url: '' },
+    });
+    await syncLinks(ctx, String(made.id));
+    return ctx.reply(ctx.get('file', String(made.id)));
+};
+/** A file's links, kept in step with the links made to it, at the address Stripe lists them
+ *  (/v1/file_links?file=…, the File object's example). */
+async function syncLinks(ctx, fileId) {
+    const data = newest(ctx, 'file_link').filter((l) => l.file === fileId);
+    await ctx.write('file', fileId, { links: { object: 'list', data, has_more: false, url: `/v1/file_links?file=${fileId}` } }, 'file.links_synced');
+}
+/** The purposes a file link may be made to: "The file's `purpose` must be one of the following: …" (the served
+ *  spec, POST /v1/file_links `file`). */
+const LINKABLE = ['business_icon', 'business_logo', 'customer_signature', 'dispute_evidence', 'finance_report_run', 'financial_account_statement', 'identity_document_downloadable', 'issuing_regulatory_reporting', 'pci_document', 'selfie', 'sigma_scheduled_query', 'tax_document_user_upload', 'terminal_android_apk', 'terminal_reader_splashscreen'];
+// `file` is required; a link is kept, has its own public url, and is listed on its file
+const createFileLink = async (ctx) => {
+    if (ctx.params.file === undefined || ctx.params.file === '')
+        return fail(ctx, 'Missing required param: file.', 400, 'parameter_missing');
+    const fileId = String(ctx.params.file);
+    const refused = filePurposeRefused(ctx, 'file', LINKABLE);
+    if (refused)
+        return refused;
+    const id = ctx.mint('file_link');
+    const link = await created(ctx, 'file_link', { ...ctx.params, id, file: fileId }, {
+        url: `https://files.twin.local/links/${id}`, expired: false, livemode: false, metadata: {},
+        expires_at: ctx.params.expires_at !== undefined ? Number(ctx.params.expires_at) : null,
+    });
+    await syncLinks(ctx, fileId);
+    return ctx.reply(link);
+};
+// the person verifies at the session's url, Stripe Identity's hosted page (../screens/identity.tsx)
+const createVerificationSession = async (ctx) => {
+    const id = ctx.mint('identity.verification_session');
+    return ctx.reply(await created(ctx, 'identity.verification_session', { ...ctx.params, id }, {
+        status: 'requires_input', livemode: false, client_secret: `${id}_secret_twin`, url: `https://verify.stripe.com/start/${id}`,
+        last_error: null, last_verification_report: null, verified_outputs: null, return_url: ctx.params.return_url ?? null,
+    }));
+};
+// ── the customer portal ──
+// the configuration defaults to the account's default one
+const createPortalSession = async (ctx) => {
+    const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
+    if (!customer)
+        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+    if (!ctx.row('customer', customer, { withDeleted: true }))
+        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
+    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/portal.tsx)
+        ...(actingAccount(ctx) ? { _brand_account: actingAccount(ctx) } : {}),
+    }, {}));
+};
+const PBC = 'billing_portal.configuration';
+/** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served
+ *  spec requires all five), as the create page's example answers a request that sets only customer_update and
+ *  invoice_history: payment_method_update disabled, subscription_cancel disabled at_period_end with proration_behavior
+ *  none and its five default reasons, subscription_update disabled with no allowed updates and proration_behavior none
+ *  (docs.stripe.com/api/customer_portal/configurations/create); trial_update_behavior "Defaults to a value of
+ *  `end_trial` if you don't set it during creation" (the served spec). Where the documentation stops and the twin
+ *  decides: a feature the request leaves out is disabled, and schedule_at_period_end has no conditions. */
+const PORTAL_FEATURES = {
+    customer_update: { allowed_updates: [], enabled: false },
+    invoice_history: { enabled: false },
+    payment_method_update: { enabled: false, payment_method_configuration: null },
+    subscription_cancel: { cancellation_reason: { enabled: false, options: ['too_expensive', 'missing_features', 'switched_service', 'unused', 'other'] }, enabled: false, mode: 'at_period_end', proration_behavior: 'none' },
+    subscription_update: { default_allowed_updates: [], enabled: false, proration_behavior: 'none', schedule_at_period_end: { conditions: [] }, trial_update_behavior: 'end_trial' },
+};
+const filled = (base, given) => {
+    if (!given || typeof given !== 'object' || Array.isArray(given) || !base || typeof base !== 'object' || Array.isArray(base))
+        return given === undefined ? base : given;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(given))
+        out[k] = filled(base[k], v);
+    return out;
+};
+const createPortalConfiguration = async (ctx) => 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: ctx.now(),
+}));
+const listPortalConfigurations = async (ctx) => 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),
+}));
+const updatePortalConfiguration = async (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: ctx.now() }), 'billing_portal.configuration.update'));
+};
+export const files = {
+    PostFiles: createFile,
+    PostFileLinks: createFileLink,
+    PostIdentityVerificationSessions: createVerificationSession,
+    PostBillingPortalSessions: createPortalSession,
+    PostBillingPortalConfigurations: createPortalConfiguration,
+    GetBillingPortalConfigurations: listPortalConfigurations,
+    PostBillingPortalConfigurationsConfiguration: updatePortalConfiguration,
+};

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

@@ -0,0 +1,18 @@
+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>;