better-supabase 0.12.0 → 0.14.0

package/dist/blocks/billable-time/index.js

@@ -0,0 +1,260 @@
+import { t as temporal } from "../../temporal-required-B8qQHYbI.js";
+import { A as requiredInstant, B as dbTransport, C as optionalText, D as recordOf, H as rpcTransport, I as textOf, U as sqlTransport, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall } from "../../block-helpers-CiKtrb6g.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks } from "../../block-hooks-BymdcD0V.js";
+import { n as entitySchema, r as moneyField } from "../../entity-schema-BXXC1NnT.js";
+import { t as defineSection } from "../../sections-DjxYmpu-.js";
+import { n as event, t as defineEvents } from "../../event-map-CtPFhcOp.js";
+import { n as defineBlock } from "../../define-block-Dze77QTw.js";
+import { t as requireTenant } from "../../block-tenant-C1sNV8_4.js";
+import { i as moneyOf, t as amountText } from "../../money-codec-jMP0PQLZ.js";
+//#region src/blocks/billable-time/billable-time.ts
+function optional(key, value) {
+	return value === void 0 ? {} : { [key]: value };
+}
+function subjectOf(row) {
+	const type = optionalText(row["subjectType"]);
+	const id = optionalText(row["subjectId"]);
+	return type === void 0 || id === void 0 ? void 0 : {
+		type,
+		id
+	};
+}
+function idsOf(value, field) {
+	if (!Array.isArray(value)) throw new TypeError(`${field} is not a list`);
+	return value.map((item) => textOf(item));
+}
+function rateOf(value, fn) {
+	const row = recordOf(value, fn);
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["organizationId"]),
+		rate: moneyOf(row["rate"], row["currency"], "time rate"),
+		effectiveFrom: temporal().PlainDate.from(textOf(row["effectiveFrom"])),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		...optional("userId", optionalText(row["userId"])),
+		...optional("subject", subjectOf(row)),
+		...optional("createdBy", optionalText(row["createdBy"]))
+	};
+}
+function lineOf(value) {
+	const row = recordOf(value, "unbilled_time");
+	return {
+		description: textOf(row["description"]),
+		quantity: String(row["quantity"]),
+		unitAmount: moneyOf(row["unitAmount"], row["currency"], "unitAmount"),
+		amount: moneyOf(row["amount"], row["currency"], "amount"),
+		entryIds: idsOf(row["entryIds"], "entryIds"),
+		...optional("subject", subjectOf(row)),
+		...optional("userId", optionalText(row["userId"]))
+	};
+}
+function invoicedOf(value) {
+	const row = recordOf(value, "list_invoiced_time");
+	const seconds = Number(row["seconds"]);
+	if (!Number.isInteger(seconds)) throw new TypeError("seconds is not an integer");
+	return {
+		entryId: textOf(row["entryId"]),
+		invoiceId: textOf(row["invoiceId"]),
+		userId: textOf(row["userId"]),
+		startedAt: requiredInstant(row["startedAt"], "startedAt"),
+		seconds,
+		rate: moneyOf(row["rate"], row["currency"], "rate"),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		...optional("subject", subjectOf(row))
+	};
+}
+/** A scope as the `jsonb` the SQL reads; absent fields stay absent. */
+function scopeArg(scope) {
+	return {
+		...optional("subject", scope.subject),
+		...optional("userId", scope.userId),
+		...optional("starts", instantArg(scope.starts) ?? void 0),
+		...optional("ends", instantArg(scope.ends) ?? void 0),
+		...optional("entryIds", scope.entryIds)
+	};
+}
+/** The `billable-time` SQL module as typed calls. */
+function createBillableTime(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const tenant = () => requireTenant(options.tenant);
+	return withBlockHooks({
+		setRate: (input) => tenant().andThen((organizationId) => call("set_time_rate", {
+			tenant: organizationId,
+			rate: amountText(input.rate),
+			currency: input.rate.currency,
+			user_id: input.userId ?? null,
+			subject_type: input.subject?.type ?? null,
+			subject_id: input.subject?.id ?? null,
+			effective_from: input.effectiveFrom?.toString() ?? null
+		}, (value) => rateOf(value, "set_time_rate"))),
+		deleteRate: (rateId) => call("delete_time_rate", { rate_id: rateId }, (value) => rateOf(value, "delete_time_rate")),
+		listRates: (list = {}) => tenant().andThen((organizationId) => call("list_time_rates", {
+			tenant: organizationId,
+			user_id: list.userId ?? null,
+			subject_type: list.subject?.type ?? null,
+			subject_id: list.subject?.id ?? null,
+			page_size: list.pageSize ?? null
+		}, (value) => recordsOf(value, "list_time_rates").map((row) => rateOf(row, "list_time_rates")))),
+		rateFor: (lookup = {}) => tenant().andThen((organizationId) => call("time_rate", {
+			tenant: organizationId,
+			user_id: lookup.userId ?? null,
+			subject_type: lookup.subject?.type ?? null,
+			subject_id: lookup.subject?.id ?? null,
+			on_day: lookup.on?.toString() ?? null
+		}, (value) => value === null ? null : rateOf(value, "time_rate"))),
+		unbilled: (query = {}) => tenant().andThen((organizationId) => call("unbilled_time", {
+			tenant: organizationId,
+			scope: scopeArg(query),
+			group_by: query.groupBy ?? "subject"
+		}, (value) => {
+			const row = recordOf(value, "unbilled_time");
+			return {
+				lines: recordsOf(row["lines"], "unbilled_time").map(lineOf),
+				totals: recordsOf(row["totals"], "unbilled_time").map((total) => moneyOf(total["amount"], total["currency"], "total")),
+				unrated: idsOf(row["unrated"], "unrated")
+			};
+		})),
+		invoice: (input = {}) => tenant().andThen((organizationId) => call("invoice_from_time", {
+			tenant: organizationId,
+			attrs: {
+				...optional("currency", input.currency),
+				...optional("title", input.title),
+				...optional("company", input.company),
+				...optional("contact", input.contact),
+				...optional("termsDays", input.termsDays),
+				...optional("note", input.note)
+			},
+			scope: scopeArg(input),
+			group_by: input.groupBy ?? "subject"
+		}, (value) => {
+			const row = recordOf(value, "invoice_from_time");
+			return {
+				invoiceId: textOf(row["invoiceId"]),
+				total: moneyOf(row["total"], row["currency"], "total"),
+				entryIds: idsOf(row["entryIds"], "entryIds")
+			};
+		})),
+		invoicedEntries: (invoiceId, list = {}) => call("list_invoiced_time", {
+			invoice: invoiceId,
+			page_size: list.pageSize ?? null
+		}, (value) => recordsOf(value, "list_invoiced_time").map(invoicedOf))
+	}, options.hooks, {
+		block: "billable-time",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/billable-time/events.ts
+/** The `billable-time` block's event types, for its manifest and `onBlockEvent`. */
+const billableTimeEvents = defineEvents({ "time.invoiced": event() });
+//#endregion
+//#region src/blocks/billable-time/schemas.ts
+/** What `setRate` takes, with the bounds the SQL checks. */
+const timeRateInputSchema = entitySchema({
+	title: "TimeRateInput",
+	fields: {
+		rate: moneyField,
+		userId: {
+			kind: "uuid",
+			optional: true
+		},
+		subject: {
+			kind: "json",
+			optional: true,
+			description: "The record the rate applies to: `{ type, id }`."
+		},
+		effectiveFrom: {
+			kind: "plainDate",
+			optional: true
+		}
+	}
+});
+const timeInvoiceSectionInputSchema = entitySchema({
+	title: "TimeInvoiceSectionInput",
+	fields: {
+		title: {
+			kind: "string",
+			optional: true,
+			minLength: 1,
+			maxLength: 200
+		},
+		currency: {
+			kind: "string",
+			optional: true,
+			minLength: 3,
+			maxLength: 3
+		},
+		groupBy: {
+			kind: "enum",
+			values: [
+				"subject",
+				"member",
+				"entry"
+			],
+			optional: true
+		},
+		note: {
+			kind: "string",
+			optional: true,
+			maxLength: 2e3
+		}
+	}
+});
+const timeRateSectionInputSchema = entitySchema({
+	title: "TimeRateSectionInput",
+	fields: {
+		rate: moneyField,
+		userId: {
+			kind: "uuid",
+			optional: true
+		},
+		effectiveFrom: {
+			kind: "plainDate",
+			optional: true
+		}
+	}
+});
+//#endregion
+//#region src/blocks/billable-time/section.ts
+/** A record's unbilled time, such as a project's, ready to invoice. */
+const billableTimeSection = defineSection({
+	permissions: {
+		read: "read",
+		write: "manage"
+	},
+	module: "billable-time",
+	load: (client, subject) => client.unbilled({ subject }),
+	events: ["time.*"],
+	writes: {
+		setRate: {
+			input: timeRateSectionInputSchema,
+			run: (client, subject, input) => client.setRate({
+				...input,
+				subject
+			})
+		},
+		invoice: {
+			input: timeInvoiceSectionInputSchema,
+			run: (client, subject, input) => client.invoice({
+				...input,
+				subject
+			})
+		}
+	}
+});
+//#endregion
+//#region src/blocks/billable-time/manifest.ts
+/** The `billable-time` block's manifest (ADR 0029). */
+const billableTimeBlock = defineBlock({
+	name: "billable-time",
+	sql: ["billable-time"],
+	options: {},
+	events: billableTimeEvents,
+	schemas: { time_rate: { input: timeRateInputSchema } },
+	create: createBillableTime,
+	sections: { billableTime: billableTimeSection },
+	category: "commerce"
+});
+//#endregion
+export { billableTimeBlock, billableTimeEvents, billableTimeSection, createBillableTime, dbTransport, extendBlock, rpcTransport, sqlTransport, timeInvoiceSectionInputSchema, timeRateInputSchema, timeRateSectionInputSchema, withBlockHooks, wrapTransport };

package/dist/blocks/billing/index.d.ts

@@ -1,20 +1,21 @@
 /// <reference lib="esnext.temporal" />
-import { T as ErrorMapper, t as AsyncResult } from "../../result-BREt7qOh.js";
-import { C as BillingEventData, O as BlockEventType, o as EventHub, wt as Events } from "../../events-P3raDX2E.js";
+import { T as ErrorMapper, t as AsyncResult } from "../../result-C6jDfedy.js";
+import { C as BillingEventData, Ct as Events, O as BlockEventType, o as EventHub } from "../../events-DbLjvxDX.js";
 import { n as Logger } from "../../logger-DWVYUmwi.js";
-import { n as SqlClient } from "../../executor-D1hECPGG.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DezJPPA0.js";
-import { i as CursorPageOptions, r as BlockTemporalOptions } from "../../block-helpers-CjcQM1yA.js";
-import { n as BlockHooks } from "../../block-hooks-DcPJHztl.js";
-import { n as StripeSource, r as StripeTaxId, t as StripeClient } from "../../stripe-NVcNOhHy.js";
-import { i as EventSink } from "../../cloud-event-DXkNoI6v.js";
-import { s as BlockOf } from "../../define-block-BHxLHLys.js";
-import { d as stripeInboxVerify, f as verifyStripeWebhook, u as signStripeWebhook } from "../../verify-DU4p9-Ve.js";
-import { a as PlanPickerController, c as createPlanPickerController, i as PlanPickerActions, n as PlanCatalog, o as PlanPickerControllerOptions, r as PlanOption, s as PlanPickerSnapshot, t as CheckoutStarted } from "../../client-D3gRTNSi.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "../../block-helpers-BaugZlJV.js";
+import { n as SqlClient } from "../../executor-CsTaO3AT.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-d53POsem.js";
+import { n as BlockHooks } from "../../block-hooks-CmjPKqQ_.js";
+import { n as StripeSource, r as StripeTaxId, t as StripeClient } from "../../stripe-X22LjuH-.js";
+import { i as EventSink } from "../../cloud-event-SPyXMdcd.js";
+import { c as BlockOf } from "../../define-block-COpcS6aT.js";
+import { d as stripeInboxVerify, f as verifyStripeWebhook, u as signStripeWebhook } from "../../verify-BmuCB4PW.js";
+import { a as PlanPickerController, c as createPlanPickerController, i as PlanPickerActions, n as PlanCatalog, o as PlanPickerControllerOptions, r as PlanOption, s as PlanPickerSnapshot, t as CheckoutStarted } from "../../client-BrtwaIBh.js";
 //#region src/blocks/billing/events.d.ts
 /** The events of the `billing` block: type to data. */
 type BillingEvents = {
   readonly "billing.customer_linked": BillingEventData;
+  readonly "billing.account_linked": BillingEventData;
   readonly "billing.checkout_completed": BillingEventData;
   readonly "billing.subscription_created": BillingEventData;
   readonly "billing.subscription_updated": BillingEventData;
@@ -31,40 +32,83 @@ interface BillingOptions extends BlockTemporalOptions {
   /** Receives the errors `after` hooks throw. Default: `console`. */
   readonly logger?: Logger;
   readonly stripe: StripeSource;
-  /** A service-role transport: linking customers and reading seats are granted to `service_role` only. */
+  /**
+   * A service-role transport: linking customers and reading seats are granted
+   * to `service_role` only.
+   */
   readonly transport: BlockTransport;
-  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`. Default `better_supabase`.
+   */
   readonly schema?: string;
   readonly mappers?: readonly ErrorMapper[];
   /** `betterSupabase.events`, for `billing.*` block events. */
   readonly events?: EventHub;
   /**
-   * Where subscription state lives, matching `blocks.billing.options.subscriptions`.
-   * `webhook` stores every `customer.subscription.*` event handled by
-   * `handleStripeEvent` in `billing_subscriptions`, newest event wins, and
-   * makes `checkout` refuse a tenant that is already subscribed. Default `sync-engine`.
+   * Where subscription state lives, matching
+   * `blocks.billing.options.subscriptions`. `webhook` stores every
+   * `customer.subscription.*` event handled by `handleStripeEvent` in
+   * `billing_subscriptions`, newest event wins, and makes `checkout` refuse a
+   * tenant that is already subscribed. Default `sync-engine`.
    */
   readonly subscriptions?: "sync-engine" | "webhook";
   /**
-   * Names the provider that already bills the tenant outside Stripe, such as
-   * a marketplace. `checkout` then fails with `BILLING_EXTERNAL` and the
-   * provider in the message. In webhook mode the SQL hook
+   * Names the provider that already bills the tenant outside Stripe, such as a
+   * marketplace. `checkout` then fails with `BILLING_EXTERNAL` and the provider
+   * in the message. In webhook mode the SQL hook
    * `public.billing_external_provider(tenant)` does the same.
    */
   readonly external?: (tenant: string) => string | undefined | Promise<string | undefined>;
-  /** The per-seat price `syncSeats` updates; default the subscription's first item. */
+  /**
+   * The per-seat price `syncSeats` updates; default the subscription's first
+   * item.
+   */
   readonly seatPrice?: string;
   /** Stripe `proration_behavior` for seat changes, default `create_prorations`. */
   readonly prorationBehavior?: "create_prorations" | "none" | "always_invoice";
   /**
-   * Invalidates the cached sessions of a customer's members after a plan
-   * change (`entitlementMembers`), so their next request reads the new
-   * entitlements. Needs the `entitlements` module.
+   * Invalidates the cached sessions of a customer's members after a plan change
+   * (`entitlementMembers`), so their next request reads the new entitlements.
+   * Needs the `entitlements` module.
    */
   readonly sessions?: {
     readonly sql: SqlClient;
     readonly invalidate: (userId: string) => void;
   };
+  /**
+   * Bills tenants as Stripe Accounts v2 accounts with the `customer`
+   * configuration instead of v1 customers. `checkout` creates or reuses the
+   * tenant's account and passes it as `customer_account` to Checkout, as does
+   * `portal`. Stripe creates the account's linked customer at the first
+   * checkout, and `handleStripeEvent` records it. A tenant that already has a
+   * v1 customer keeps it. Needs `v2.core.accounts` on the Stripe client.
+   * Default `false`.
+   */
+  readonly customerAccounts?: boolean | CustomerAccountOptions;
+  /**
+   * `ignore` skips Connect events (those with `event.account`, sent for a
+   * connected account) in `handleStripeEvent`, for an endpoint or event
+   * destination that receives both platform and connected account events while
+   * the block bills on the platform. Default `handle`.
+   */
+  readonly connectEvents?: "handle" | "ignore";
+}
+/** `customerAccounts` in `createBilling`. */
+interface CustomerAccountOptions {
+  /**
+   * The tenant's existing Accounts v2 account, such as the connected account it
+   * already sells through, or `undefined` to create one. The account needs the
+   * `customer` configuration before Stripe bills it.
+   */
+  readonly resolve?: (tenant: string) => string | undefined | Promise<string | undefined>;
+  /**
+   * More `v2.core.accounts.create` parameters, merged deeply over the block's
+   * (`contact_email`, `display_name`, `configuration.customer` and the tenant
+   * in `metadata.organization_id`), or a function of the tenant and the details
+   * that returns them.
+   */
+  readonly params?: Readonly<Record<string, unknown>> | ((tenant: string, details: CustomerDetails) => Readonly<Record<string, unknown>>);
 }
 interface CustomerDetails {
   readonly email?: string;
@@ -74,17 +118,17 @@ interface CheckoutOptions extends CustomerDetails {
   /** A Stripe price id. Pass this or `plan`. */
   readonly price?: string;
   /**
-   * A plan key from `blocks.billing.options.plans`, resolved to its
-   * Stripe price in the app's plan catalog (with `interval` when plans have
-   * monthly and yearly prices).
+   * A plan key from `blocks.billing.options.plans`, resolved to its Stripe
+   * price in the app's plan catalog (with `interval` when plans have monthly
+   * and yearly prices).
    */
   readonly plan?: string;
   readonly interval?: string;
   /** One of the plan's prices, from the catalog's `variant` column. */
   readonly variant?: string;
   /**
-   * More line items, such as add-on packages next to the plan: each a
-   * price, or a plan key with `interval` and `variant`. Quantity defaults to 1.
+   * More line items, such as add-on packages next to the plan: each a price, or
+   * a plan key with `interval` and `variant`. Quantity defaults to 1.
    */
   readonly items?: readonly CheckoutItem[];
   readonly successUrl: string;
@@ -119,6 +163,8 @@ interface SubscriptionItem {
 }
 interface BillingStatus {
   readonly customerId: string | undefined;
+  /** The tenant's Accounts v2 account, when it is billed as one. */
+  readonly accountId: string | undefined;
   readonly seats: number;
   readonly subscription: SubscriptionItem | undefined;
 }
@@ -132,6 +178,8 @@ interface SeatSync {
 interface StripeEvent {
   readonly id: string;
   readonly type: string;
+  /** The connected account a Connect event happened on. */
+  readonly account?: string | null;
   /** Unix seconds; orders subscription events in webhook mode. */
   readonly created?: number;
   readonly data: {
@@ -143,6 +191,8 @@ interface StripeEventOutcome {
   readonly event: BlockEventType<BillingEvents> | undefined;
   readonly organizationId: string | undefined;
   readonly customerId: string | undefined;
+  /** The event object's `customer_account`, for a tenant billed as an account. */
+  readonly accountId: string | undefined;
   /** Members whose sessions were invalidated. */
   readonly invalidated: readonly string[];
 }
@@ -164,7 +214,10 @@ interface PlanChange {
  * payment method (`id`, `type`, `card`).
  */
 type StripeRow = Readonly<Record<string, unknown>>;
-/** A Sync Engine row with the tenant and customer it belongs to, from a platform read. */
+/**
+ * A Sync Engine row with the tenant and customer it belongs to, from a platform
+ * read.
+ */
 interface TenantStripeRow {
   readonly organizationId: string;
   readonly customerId: string;
@@ -198,13 +251,34 @@ interface BillingCustomerUpdate {
 interface Billing {
   /** The tenant's Stripe customer, or `undefined` before the first checkout. */
   customer(organizationId: string): AsyncResult<string | undefined>;
-  /** The tenant's customer, created in Stripe (with the tenant in `metadata`) when there is none. */
+  /**
+   * The tenant's Stripe Accounts v2 account (`acct_`), or `undefined` when it
+   * is not billed as one.
+   */
+  account(organizationId: string): AsyncResult<string | undefined>;
+  /**
+   * The tenant's customer, created in Stripe (with the tenant in `metadata`)
+   * when there is none. With `customerAccounts`, a tenant without a customer
+   * gets its account instead, and this fails with `not_found`
+   * (`BILLING_CUSTOMER_PENDING`) until Stripe creates the account's customer at
+   * the first checkout.
+   */
   ensureCustomer(organizationId: string, details?: CustomerDetails): AsyncResult<string>;
+  /**
+   * The tenant's Accounts v2 account: the linked one, the one
+   * `customerAccounts.resolve` returns, or a new one with the `customer`
+   * configuration (and the tenant in `metadata`), which it links.
+   */
+  ensureAccount(organizationId: string, details?: CustomerDetails): AsyncResult<string>;
   checkout(organizationId: string, options: CheckoutOptions): AsyncResult<{
     readonly id: string;
     readonly url: string | undefined;
   }>;
-  /** A customer portal session; `not_found` before the tenant has a customer. */
+  /**
+   * A customer portal session, for the tenant's account with
+   * `customerAccounts`; `not_found` before the tenant has a customer or an
+   * account.
+   */
   portal(organizationId: string, options: {
     readonly returnUrl: string;
   }): AsyncResult<{
@@ -213,8 +287,8 @@ interface Billing {
   status(organizationId: string): AsyncResult<BillingStatus>;
   /**
    * The tenant's newest subscription as the Sync Engine stores it (every
-   * column, with `items`), preferring an active one; `undefined` without
-   * one. For `billing.read` in the tenant, or platform staff.
+   * column, with `items`), preferring an active one; `undefined` without one.
+   * For `billing.read` in the tenant, or platform staff.
    */
   subscription(organizationId: string): AsyncResult<StripeRow | undefined>;
   /**
@@ -229,9 +303,9 @@ interface Billing {
    */
   allCustomers(): AsyncResult<readonly BillingCustomer[]>;
   /**
-   * Cancels the tenant's active subscription in Stripe now; `undefined`
-   * when it has none. The `customer.subscription.deleted` webhook then
-   * emits `billing.subscription_deleted`.
+   * Cancels the tenant's active subscription in Stripe now; `undefined` when it
+   * has none. The `customer.subscription.deleted` webhook then emits
+   * `billing.subscription_deleted`.
    */
   cancelSubscription(organizationId: string): AsyncResult<string | undefined>;
   /** Sets the seat item's quantity to the tenant's seat count. */
@@ -240,7 +314,8 @@ interface Billing {
   }): AsyncResult<SeatSync>;
   /**
    * An outbox sink that syncs seats after `organization.member_*` and
-   * `organization.role_changed` events: `outbox.relay('billing-seats', billing.seatSink())`.
+   * `organization.role_changed` events: `outbox.relay('billing-seats',
+   * billing.seatSink())`.
    */
   seatSink(): EventSink;
   /**
@@ -249,14 +324,20 @@ interface Billing {
    * call it with a service transport after their own permission check.
    */
   changePlan(organizationId: string, change: PlanChange): AsyncResult<SubscriptionItem>;
-  /** Schedules (true) or clears (false) the cancellation at the end of the period. */
+  /**
+   * Schedules (true) or clears (false) the cancellation at the end of the
+   * period.
+   */
   cancelAtPeriodEnd(organizationId: string, cancel: boolean): AsyncResult<string>;
   /**
    * Every tenant's invoices, newest first, for platform staff (`billing.read`
    * in the platform scope) or a service transport.
    */
   allInvoices(options?: PlatformListOptions): AsyncResult<readonly TenantStripeRow[]>;
-  /** The tenant's invoices from the Sync Engine, newest first (`billing.read`, or platform staff). */
+  /**
+   * The tenant's invoices from the Sync Engine, newest first (`billing.read`,
+   * or platform staff).
+   */
   invoices(organizationId: string, options?: {
     readonly limit?: number;
   }): AsyncResult<readonly StripeRow[]>;
@@ -266,43 +347,53 @@ interface Billing {
   voidInvoice(organizationId: string, invoiceId: string): AsyncResult<string>;
   /** Marks an open invoice of the tenant's customer uncollectible. */
   markInvoiceUncollectible(organizationId: string, invoiceId: string): AsyncResult<string>;
-  /** The billing contact as Stripe holds it, from the Sync Engine's customers table. */
+  /**
+   * The billing contact as Stripe holds it, from the Sync Engine's customers
+   * table.
+   */
   customerDetails(organizationId: string): AsyncResult<StripeRow | undefined>;
   /**
-   * The tenant customer's tax ids, `[]` before the tenant has a customer.
-   * From Stripe by default, which needs `customers.listTaxIds` on the
-   * client; `{ from: "sync" }` reads the Sync Engine's `stripe.tax_ids`
-   * through `billing_tax_ids` instead (`billing.read`, or platform staff).
+   * The tenant customer's tax ids, `[]` before the tenant has a customer. From
+   * Stripe by default, which needs `customers.listTaxIds` on the client; `{
+   * from: "sync" }` reads the Sync Engine's `stripe.tax_ids` through
+   * `billing_tax_ids` instead (`billing.read`, or platform staff).
    */
   taxIds(organizationId: string, options?: {
     readonly from?: "stripe" | "sync";
   }): AsyncResult<readonly StripeTaxId[]>;
   /**
-   * Adds a tax id (`{ type: 'eu_vat', value: 'DE123456789' }`) to the
-   * tenant's customer, creating the customer first when there is none.
+   * Adds a tax id (`{ type: 'eu_vat', value: 'DE123456789' }`) to the tenant's
+   * customer, creating the customer first when there is none.
    */
   addTaxId(organizationId: string, taxId: {
     readonly type: string;
     readonly value: string;
   }): AsyncResult<StripeTaxId>;
-  /** Removes a tax id from the tenant's customer; `not_found` before the tenant has a customer. */
+  /**
+   * Removes a tax id from the tenant's customer; `not_found` before the tenant
+   * has a customer.
+   */
   removeTaxId(organizationId: string, taxId: string): AsyncResult<string>;
   /** Updates the billing contact on the Stripe customer, the record for it. */
   updateCustomer(organizationId: string, update: BillingCustomerUpdate): AsyncResult<string>;
   /**
-   * Handles `checkout.session.completed` and `customer.subscription.*`:
-   * links the customer, emits `billing.*` events and invalidates sessions.
-   * Other events are ignored. Call it from `inbox.process`.
+   * Handles `checkout.session.completed` and `customer.subscription.*`: links
+   * the customer, emits `billing.*` events and invalidates sessions. Any other
+   * event with a `customer_account` of a linked tenant records the account's
+   * customer; other events are ignored. Call it from `inbox.process`.
    */
   handleStripeEvent(event: unknown): AsyncResult<StripeEventOutcome>;
 }
 //#endregion
 //#region src/blocks/billing/billing.d.ts
-/** Stripe customers, checkout, the portal and seat sync over the `billing` module. */
+/**
+ * Stripe customers, checkout, the portal and seat sync over the `billing`
+ * module.
+ */
 export declare function createBilling(options: BillingOptions): Billing;
 //#endregion
 //#region src/blocks/billing/manifest.d.ts
 /** The `billing` block's manifest (ADR 0029). */
 export declare const billingBlock: BlockOf<"billing", typeof createBilling, BillingEvents>;
 //#endregion
-export { type Billing, type BillingCustomer, type BillingCustomerUpdate, type BillingEventData, type BillingEvents, type BillingOptions, type BillingStatus, type BlockTransport, type CheckoutItem, type CheckoutOptions, type CheckoutStarted, type CustomerDetails, type PlanCatalog, type PlanChange, type PlanOption, type PlanPickerActions, type PlanPickerController, type PlanPickerControllerOptions, type PlanPickerSnapshot, type PlatformListOptions, type SeatSync, type StripeClient, type StripeEvent, type StripeEventOutcome, type StripeRow, type StripeSource, type StripeTaxId, type SubscriptionItem, type TenantStripeRow, createPlanPickerController, dbTransport, rpcTransport, signStripeWebhook, sqlTransport, stripeInboxVerify, verifyStripeWebhook };
+export { type Billing, type BillingCustomer, type BillingCustomerUpdate, type BillingEventData, type BillingEvents, type BillingOptions, type BillingStatus, type BlockTransport, type CheckoutItem, type CheckoutOptions, type CheckoutStarted, type CustomerAccountOptions, type CustomerDetails, type PlanCatalog, type PlanChange, type PlanOption, type PlanPickerActions, type PlanPickerController, type PlanPickerControllerOptions, type PlanPickerSnapshot, type PlatformListOptions, type SeatSync, type StripeClient, type StripeEvent, type StripeEventOutcome, type StripeRow, type StripeSource, type StripeTaxId, type SubscriptionItem, type TenantStripeRow, createPlanPickerController, dbTransport, rpcTransport, signStripeWebhook, sqlTransport, stripeInboxVerify, verifyStripeWebhook };