@greatwait/contracts 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/billing.js

@@ -0,0 +1,833 @@
+import { z } from "./zod.js";
+import { attemptIdSchema, projectIdSchema } from "./identifiers.js";
+import { pageRequestSchema, pageSchema, requiredIdempotencyRequestHeaderSchema, } from "./protocol.js";
+import { timestampSchema } from "./time.js";
+export const BILLING_AMOUNT_SCALE = 6;
+export const BILLING_CURRENCY = "USD";
+/**
+ * Exact integer money on the wire.
+ *
+ * PostgreSQL uses `bigint`; JSON uses a canonical decimal string because a
+ * JavaScript number cannot represent every ledger amount without rounding.
+ */
+export const microdollarAmountSchema = z
+    .string()
+    .regex(/^-?(?:0|[1-9]\d*)$/u, "must be a canonical integer decimal string");
+export const nonnegativeMicrodollarAmountSchema = z
+    .string()
+    .regex(/^(?:0|[1-9]\d*)$/u, "must be a canonical nonnegative integer decimal string");
+export const BILLING_ACTIVATION_MODES = [
+    "disabled",
+    "shadow",
+    "enforced",
+];
+export const BILLING_BLOCK_REASONS = [
+    "billing-state-missing",
+    "billing-account-closed",
+    "project-ineligible",
+    "insufficient-credit",
+    "execution-cap-reached",
+];
+export const BILLING_ENTRY_KINDS = [
+    "credit_granted",
+    "credit_reversed",
+    "attempt_debited",
+    "attempt_released",
+    "shadow_attempt_debited",
+    "shadow_attempt_released",
+    "late_evidence_waived",
+    "policy_installed",
+    "budget_policy_updated",
+    "budget_threshold_reached",
+    "budget_exhausted",
+    "budget_recovered",
+    "automatic_charge_ceiling_updated",
+    "payment_reserved",
+    "payment_submitted",
+    "payment_pending",
+    "payment_paid",
+    "payment_failed",
+    "payment_canceled",
+    "payment_authentication_required",
+    "payment_action_required",
+    "payment_refunded",
+    "payment_disputed",
+    "payment_reversed",
+    "payment_dispute_restored",
+    "refund_requested",
+    "payment_refund_canceled",
+    "automatic_top_up_cap_reached",
+    "automatic_charge_threshold_reached",
+    "automatic_charge_threshold_recovered",
+    "low_credit_reached",
+    "low_credit_recovered",
+    "notification_settings_updated",
+    "service_blocked",
+    "service_restored",
+];
+/**
+ * Why a ledger entry that looks like money moved none.
+ *
+ * `provider-details-attached`: the payment provider reported details of a
+ * payment the ledger already recorded — its charge, receipt, hosted page or
+ * tax. The entry repeats the payment's kind and shows a zero amount, so one
+ * purchase never reads as two.
+ */
+export const BILLING_LEDGER_ENTRY_NOTES = [
+    "provider-details-attached",
+];
+export const BILLING_PAYMENT_KINDS = ["manual", "automatic"];
+export const BILLING_PAYMENT_STATES = [
+    "pending",
+    "paid",
+    "failed",
+    "authentication-required",
+    "action-required",
+    "canceled",
+    "refunded",
+    "reversed",
+    "disputed",
+];
+const signedExactMoneySchema = z.object({
+    currency: z.literal(BILLING_CURRENCY),
+    microdollars: microdollarAmountSchema,
+    scale: z.literal(BILLING_AMOUNT_SCALE),
+});
+const nonnegativeExactMoneySchema = z.object({
+    currency: z.literal(BILLING_CURRENCY),
+    microdollars: nonnegativeMicrodollarAmountSchema,
+    scale: z.literal(BILLING_AMOUNT_SCALE),
+});
+/**
+ * The generated request contract for a whole-cent PostgreSQL `bigint`.
+ *
+ * Zod refinements deliberately remain the runtime authority below, while this
+ * JSON Schema metadata gives OpenAPI and MCP validators the same boundary. The
+ * long final branch is the inclusive 15-digit cent maximum
+ * `922337203685477`, followed by the four zero microdollar places.
+ */
+const exactCentMicrodollarAmountSchema = nonnegativeMicrodollarAmountSchema.meta({
+    description: "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.",
+    maxLength: 19,
+    pattern: "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$",
+});
+export const exactCentMoneySchema = z
+    .object({
+    currency: z.literal(BILLING_CURRENCY),
+    microdollars: exactCentMicrodollarAmountSchema,
+    scale: z.literal(BILLING_AMOUNT_SCALE),
+})
+    .superRefine((amount, context) => {
+    const microdollars = BigInt(amount.microdollars);
+    if (microdollars % 10000n !== 0n) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "must be a whole number of cents (10,000 microdollars)",
+            path: ["microdollars"],
+        });
+    }
+    if (microdollars > 9223372036854770000n) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "must fit the exact PostgreSQL billing range",
+            path: ["microdollars"],
+        });
+    }
+});
+export const manualFundingCreditSchema = exactCentMoneySchema.refine((amount) => BigInt(amount.microdollars) >= 10000000n, "manual execution-credit purchases must be at least USD 10");
+const positiveExactCentMoneySchema = exactCentMoneySchema.refine((amount) => BigInt(amount.microdollars) > 0n, "must be greater than zero");
+export const billingAutoTopUpConfigurationSchema = z
+    .object({
+    ceiling: positiveExactCentMoneySchema,
+    credit: positiveExactCentMoneySchema,
+    triggerBelow: positiveExactCentMoneySchema,
+})
+    .strict()
+    .superRefine((configuration, context) => {
+    if (BigInt(configuration.credit.microdollars) >
+        BigInt(configuration.ceiling.microdollars)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "fixed credit cannot exceed its gross payment ceiling",
+            path: ["credit"],
+        });
+    }
+});
+export const billingAutoTopUpPreviewRequestSchema = z
+    .object({
+    action: z.enum(["enable", "edit", "disable", "resume"]),
+    ceiling: positiveExactCentMoneySchema.optional(),
+    credit: positiveExactCentMoneySchema.optional(),
+    expectedRevision: z.number().int().nonnegative(),
+    triggerBelow: positiveExactCentMoneySchema.optional(),
+})
+    .strict()
+    .superRefine((request, context) => {
+    const replacement = request.action === "enable" || request.action === "edit";
+    for (const field of ["ceiling", "credit", "triggerBelow"]) {
+        if (replacement === (request[field] === undefined)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: replacement
+                    ? `${field} is required for a complete ${request.action} preview`
+                    : `${field} is not accepted for a ${request.action} preview`,
+                path: [field],
+            });
+        }
+    }
+});
+export const billingAutoTopUpApplyRequestSchema = z
+    .object({
+    confirmed: z.literal(true),
+    expectedRevision: z.number().int().nonnegative(),
+    preview: z.string().min(1).max(128),
+})
+    .strict();
+export const billingFundingQuoteRequestSchema = z
+    .object({ credit: manualFundingCreditSchema })
+    .strict();
+export const billingFundingQuoteSchema = z
+    .object({
+    credit: manualFundingCreditSchema,
+    expectedRevision: z.number().int().nonnegative(),
+    expiresAt: timestampSchema,
+    gross: z.literal(null),
+    quote: z.string().min(1).max(128),
+    tax: z.literal(null),
+    taxStatus: z.literal("calculated-at-checkout"),
+})
+    .strict();
+export const billingPurchaseRequestSchema = z
+    .object({
+    automaticTopUp: z
+        .boolean()
+        .meta({
+        description: "true: the customer also asks to top up automatically when credit runs low. The hosted payment then saves the payment method for later off-session charges (it offers every method the account enables except Klarna, which cannot be charged that way), and once the provider confirms this payment paid, automatic top-up is enabled with the default rule (add USD 10.00 when available credit falls below USD 2.00, at most USD 50.00 of automatic charges a month) using that payment method. A rule that is already ready is left unchanged; an enabled rule waiting for a payment method keeps its own amounts and gains this one. Omitted or false: the purchase does exactly what it always did. An unpaid, expired or cancelled payment enables nothing.",
+    })
+        .optional(),
+    confirmed: z.literal(true),
+    expectedRevision: z.number().int().nonnegative(),
+    quote: z.string().min(1).max(128),
+})
+    .strict();
+export const billingCeilingUpdateRequestSchema = z
+    .object({
+    automaticExecutionTopUpCeiling: exactCentMoneySchema.nullable(),
+    expectedRevision: z.number().int().nonnegative(),
+})
+    .strict();
+const safeBillingUrlSchema = z
+    .string()
+    .url()
+    .max(4096)
+    .refine((value) => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" &&
+            [
+                "billing.stripe.com",
+                "checkout.stripe.com",
+                "invoice.stripe.com",
+                "pay.stripe.com",
+            ].includes(url.hostname) &&
+            url.username === "" &&
+            url.password === "" &&
+            url.port === "");
+    }
+    catch {
+        return false;
+    }
+}, "must be a supported provider-hosted HTTPS billing URL");
+const billingPaymentReasonSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9-]{0,127}$/u, "must be a bounded reason code");
+export const billingAutoTopUpRuleSchema = z
+    .object({
+    cooldownUntil: timestampSchema.nullable(),
+    desired: billingAutoTopUpConfigurationSchema.nullable(),
+    effective: billingAutoTopUpConfigurationSchema.nullable(),
+    setupUrl: safeBillingUrlSchema.optional(),
+    state: z.enum(["disabled", "payment-method-required", "ready"]),
+    suspension: z
+        .object({
+        at: timestampSchema,
+        reason: z.enum(["authentication-required", "payment-failed"]),
+    })
+        .strict()
+        .nullable(),
+})
+    .strict()
+    .superRefine((rule, context) => {
+    if (rule.state === "disabled" && rule.effective !== null) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "a disabled rule cannot remain effective",
+            path: ["effective"],
+        });
+    }
+    if (rule.state === "ready" && rule.effective === null) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "a ready rule requires effective authority",
+            path: ["effective"],
+        });
+    }
+    if (rule.state !== "payment-method-required" &&
+        rule.setupUrl !== undefined) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "a setup URL is only available while payment authority is required",
+            path: ["setupUrl"],
+        });
+    }
+});
+export const billingAutoTopUpPreviewSchema = z
+    .object({
+    action: z.enum(["enable", "edit", "disable", "resume"]),
+    after: billingAutoTopUpConfigurationSchema.nullable(),
+    before: billingAutoTopUpConfigurationSchema.nullable(),
+    currentPeriod: z
+        .object({
+        end: timestampSchema,
+        pending: nonnegativeExactMoneySchema,
+        remaining: nonnegativeExactMoneySchema.nullable(),
+        settled: nonnegativeExactMoneySchema,
+        start: timestampSchema,
+    })
+        .strict(),
+    expectedRevision: z.number().int().nonnegative(),
+    expandsAuthority: z.boolean(),
+    expiresAt: timestampSchema,
+    preview: z.string().min(1).max(128),
+    subscribedProjectFees: nonnegativeExactMoneySchema,
+})
+    .strict();
+export const billingPaymentOperationSchema = z
+    .object({
+    createdAt: timestampSchema,
+    credit: exactCentMoneySchema,
+    gross: nonnegativeExactMoneySchema.nullable(),
+    id: z.string().min(1).max(255),
+    kind: z.enum(BILLING_PAYMENT_KINDS),
+    paymentUrl: safeBillingUrlSchema.optional(),
+    reason: billingPaymentReasonSchema.optional(),
+    receiptUrl: safeBillingUrlSchema.optional(),
+    state: z.enum(BILLING_PAYMENT_STATES),
+    tax: nonnegativeExactMoneySchema.nullable(),
+    taxStatus: z.enum(["calculated-at-checkout", "confirmed"]),
+    updatedAt: timestampSchema,
+})
+    .strict()
+    .superRefine((operation, context) => {
+    if (operation.taxStatus === "calculated-at-checkout") {
+        if (operation.tax !== null || operation.gross !== null) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "tax and gross stay unknown until provider confirmation",
+                path: ["taxStatus"],
+            });
+        }
+        return;
+    }
+    if (operation.tax === null || operation.gross === null) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "confirmed tax status requires exact tax and gross amounts",
+            path: ["taxStatus"],
+        });
+        return;
+    }
+    if (BigInt(operation.gross.microdollars) !==
+        BigInt(operation.credit.microdollars) + BigInt(operation.tax.microdollars)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "gross must equal execution credit plus confirmed tax",
+            path: ["gross"],
+        });
+    }
+});
+export const billingFundingViewSchema = z
+    .object({
+    automaticExecutionTopUp: z.object({
+        ceiling: exactCentMoneySchema.nullable(),
+        currentPeriod: z.object({
+            end: timestampSchema,
+            pending: nonnegativeExactMoneySchema,
+            remaining: nonnegativeExactMoneySchema.nullable(),
+            settled: nonnegativeExactMoneySchema,
+            start: timestampSchema,
+        }),
+        rule: billingAutoTopUpRuleSchema,
+        revision: z.number().int().nonnegative(),
+    }),
+    credit: z.object({
+        amountOwed: nonnegativeExactMoneySchema,
+        available: nonnegativeExactMoneySchema,
+        reserved: nonnegativeExactMoneySchema,
+    }),
+    freshness: z.object({ kind: z.literal("authoritative") }),
+    paymentOperations: z.array(billingPaymentOperationSchema).max(25),
+    subscribedProjectFees: nonnegativeExactMoneySchema,
+})
+    .strict()
+    .superRefine((view, context) => {
+    const ceiling = view.automaticExecutionTopUp.ceiling;
+    const period = view.automaticExecutionTopUp.currentPeriod;
+    if (ceiling === null) {
+        if (period.remaining !== null) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "remaining must be null when automatic funding is off",
+                path: ["automaticExecutionTopUp", "currentPeriod", "remaining"],
+            });
+        }
+        return;
+    }
+    const committed = BigInt(period.pending.microdollars) + BigInt(period.settled.microdollars);
+    const cap = BigInt(ceiling.microdollars);
+    const expected = cap > committed ? cap - committed : 0n;
+    if (period.remaining?.microdollars !== expected.toString()) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "remaining must reflect settled plus pending gross charges",
+            path: ["automaticExecutionTopUp", "currentPeriod", "remaining"],
+        });
+    }
+});
+export const BILLING_NOTICE_KINDS = [
+    "budget-warning",
+    "budget-exhausted",
+    "low-credit",
+    "automatic-top-up-cap-reached",
+    "funding-blocked",
+    "payment-pending",
+    "payment-succeeded",
+    "payment-failed",
+    "payment-authentication-required",
+    "payment-outcome-unresolved",
+    "service-restored",
+];
+export const billingNoticeRecoveryPathSchema = z.enum([
+    "#billing",
+    "#billing-funding",
+    "#billing-notification-settings",
+]);
+export const billingNoticeSchema = z
+    .object({
+    amounts: z
+        .object({
+        available: nonnegativeExactMoneySchema.optional(),
+        gross: nonnegativeExactMoneySchema.optional(),
+        limit: nonnegativeExactMoneySchema.optional(),
+        threshold: nonnegativeExactMoneySchema.optional(),
+    })
+        .strict(),
+    detail: z.string().min(1).max(512),
+    email: z
+        .object({
+        attempts: z.number().int().nonnegative().max(100),
+        failureCode: billingPaymentReasonSchema.optional(),
+        lastAttemptAt: timestampSchema.nullable(),
+        state: z.enum(["pending", "delivered", "failed", "suppressed"]),
+    })
+        .strict(),
+    id: z.string().min(1).max(128),
+    kind: z.enum(BILLING_NOTICE_KINDS),
+    occurredAt: timestampSchema,
+    payment: z
+        .object({
+        operation: z.string().min(1).max(255),
+        state: z.enum(BILLING_PAYMENT_STATES),
+    })
+        .strict()
+        .nullable(),
+    recoveryPath: billingNoticeRecoveryPathSchema,
+    resolvedAt: timestampSchema.nullable(),
+    scope: z.discriminatedUnion("kind", [
+        z.object({ kind: z.literal("organization") }).strict(),
+        z
+            .object({ kind: z.literal("project"), project: projectIdSchema })
+            .strict(),
+    ]),
+    severity: z.enum(["warning", "critical", "recovery"]),
+    state: z.enum(["active", "resolved"]),
+    title: z.string().min(1).max(160),
+    updatedAt: timestampSchema,
+})
+    .strict()
+    .superRefine((notice, context) => {
+    if ((notice.state === "resolved") !== (notice.resolvedAt !== null)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "resolved notices require resolvedAt and active notices forbid it",
+            path: ["resolvedAt"],
+        });
+    }
+    if (notice.email.state === "failed" &&
+        notice.email.failureCode === undefined) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "failed email delivery requires a bounded failure code",
+            path: ["email", "failureCode"],
+        });
+    }
+});
+export const billingNoticePageSchema = pageSchema(billingNoticeSchema).extend({
+    freshness: z.object({ kind: z.literal("authoritative") }),
+});
+export const billingNotificationSettingsSchema = z
+    .object({
+    criticalEmail: z.literal(true),
+    freshness: z.object({ kind: z.literal("authoritative") }),
+    lowCreditThreshold: exactCentMoneySchema,
+    noncriticalEmail: z.boolean(),
+    recipients: z
+        .object({
+        billingContacts: z.literal("active-billing-role-members"),
+        owners: z.literal(true),
+    })
+        .strict(),
+    revision: z.number().int().nonnegative(),
+})
+    .strict();
+export const billingNotificationSettingsUpdateRequestSchema = z
+    .object({
+    expectedRevision: z.number().int().nonnegative(),
+    lowCreditThreshold: positiveExactCentMoneySchema.nullable().optional(),
+    noncriticalEmail: z.boolean(),
+})
+    .strict();
+export const billingRefundRequestCreateSchema = z
+    .object({
+    amount: positiveExactCentMoneySchema,
+    confirmed: z.literal(true),
+    paymentOperation: z.string().min(1).max(255),
+    reason: z.string().trim().min(1).max(128),
+})
+    .strict();
+export const billingRefundResolutionRequestSchema = z
+    .object({
+    confirmed: z.literal(true),
+    decision: z.enum(["completed", "declined"]),
+    gross: positiveExactCentMoneySchema.optional(),
+    providerRefund: z
+        .string()
+        .regex(/^re_[A-Za-z0-9_]+$/u, "must be a Stripe refund identifier")
+        .max(255)
+        .optional(),
+    tax: exactCentMoneySchema.optional(),
+})
+    .strict()
+    .superRefine((request, context) => {
+    const completed = request.decision === "completed";
+    for (const field of ["gross", "providerRefund", "tax"]) {
+        if (completed === (request[field] === undefined)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: completed
+                    ? `${field} is required for a completed refund`
+                    : `${field} is not accepted for a declined refund`,
+                path: [field],
+            });
+        }
+    }
+});
+export const billingRefundRequestViewSchema = z
+    .object({
+    amount: positiveExactCentMoneySchema,
+    id: z.string().min(1).max(255),
+    paymentOperation: z.string().min(1).max(255),
+    requestedAt: timestampSchema,
+    state: z.literal("operator-review-pending"),
+})
+    .strict();
+export const billingBudgetUpdateRequestSchema = z.object({
+    advisoryBudget: exactCentMoneySchema.nullable(),
+    expectedRevision: z.number().int().nonnegative(),
+    hardCap: exactCentMoneySchema.nullable(),
+});
+const billingBudgetSettingsSchema = z.object({
+    advisoryBudget: nonnegativeExactMoneySchema.nullable(),
+    hardCap: nonnegativeExactMoneySchema.nullable(),
+});
+export const billingBudgetPolicySchema = z
+    .object({
+    desired: billingBudgetSettingsSchema,
+    desiredRevision: z.number().int().nonnegative(),
+    effectiveRevision: z.number().int().nonnegative(),
+    pending: z.boolean(),
+})
+    .superRefine((policy, context) => {
+    if (!policy.pending &&
+        policy.desiredRevision !== policy.effectiveRevision) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "different desired and effective budget revisions must remain pending",
+        });
+    }
+});
+export const billingPeriodSummarySchema = z.object({
+    advisoryBudget: nonnegativeExactMoneySchema.optional(),
+    hardCap: nonnegativeExactMoneySchema.optional(),
+    remainingToHardCap: nonnegativeExactMoneySchema.optional(),
+    advisoryBudgetProgress: z
+        .object({
+        committed: nonnegativeExactMoneySchema,
+        remaining: nonnegativeExactMoneySchema,
+    })
+        .optional(),
+    automaticExecutionTopUp: z.object({
+        cap: nonnegativeExactMoneySchema.optional(),
+        pending: nonnegativeExactMoneySchema,
+        remainingToCap: nonnegativeExactMoneySchema.optional(),
+        settled: nonnegativeExactMoneySchema,
+    }),
+    subscribedProjectFees: nonnegativeExactMoneySchema,
+    reservedUsage: nonnegativeExactMoneySchema,
+    settledUsage: nonnegativeExactMoneySchema,
+    start: timestampSchema,
+    end: timestampSchema,
+});
+export const billingSummarySchema = z
+    .object({
+    activation: z.object({
+        boundary: timestampSchema,
+        mode: z.enum(BILLING_ACTIVATION_MODES),
+    }),
+    blockingReasons: z.array(z.enum(BILLING_BLOCK_REASONS)),
+    budgetPolicy: billingBudgetPolicySchema,
+    closedAt: timestampSchema.optional(),
+    credit: z.object({
+        available: signedExactMoneySchema,
+        consumed: nonnegativeExactMoneySchema,
+        reserved: nonnegativeExactMoneySchema,
+    }),
+    desiredRevision: z.number().int().positive(),
+    effectiveRevision: z.number().int().positive(),
+    freshness: z.object({ kind: z.literal("authoritative") }),
+    includedProject: projectIdSchema.optional(),
+    period: billingPeriodSummarySchema.optional(),
+    pending: z.boolean(),
+    priceVersion: z.string().min(1).max(64),
+    trialExpiresAt: timestampSchema.optional(),
+})
+    .superRefine((summary, context) => {
+    if (!summary.pending &&
+        summary.desiredRevision !== summary.effectiveRevision) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "different desired and effective revisions must remain pending",
+        });
+    }
+});
+export const billingBudgetUpdateResponseSchema = z.object({
+    budgetPolicy: billingBudgetPolicySchema,
+    freshness: z.object({ kind: z.literal("authoritative") }),
+});
+export const billingBudgetUpdateRequestHeadersSchema = requiredIdempotencyRequestHeaderSchema;
+export const billingLedgerEntrySchema = z.object({
+    amount: z.object({
+        currency: z.literal(BILLING_CURRENCY),
+        microdollars: microdollarAmountSchema,
+        scale: z.literal(BILLING_AMOUNT_SCALE),
+    }),
+    kind: z.enum(BILLING_ENTRY_KINDS),
+    note: z
+        .enum(BILLING_LEDGER_ENTRY_NOTES)
+        .meta({
+        description: "Present when an entry moved no money despite its kind. provider-details-attached: the provider reported details of a payment already recorded; the amount is zero.",
+    })
+        .optional(),
+    period: timestampSchema.optional(),
+    recordedAt: timestampSchema,
+    reference: z.object({
+        attempt: attemptIdSchema.optional(),
+        creditLot: z.string().min(1).max(128).optional(),
+        event: z.string().min(1).max(255),
+        paymentOperation: z.string().min(1).max(255).optional(),
+    }),
+    sequence: nonnegativeMicrodollarAmountSchema.refine((value) => value !== "0", "must be positive"),
+});
+export const billingLedgerRequestSchema = pageRequestSchema;
+export const billingLedgerPageSchema = pageSchema(billingLedgerEntrySchema).extend({
+    freshness: z.object({ kind: z.literal("authoritative") }),
+});
+export const PROJECT_BILLING_ACTIONS = [
+    "add",
+    "cancel",
+    "transfer-included",
+];
+export const projectBillingQuoteRequestSchema = z
+    .object({
+    action: z.enum(PROJECT_BILLING_ACTIONS),
+    project: projectIdSchema,
+    fromProject: projectIdSchema.optional(),
+})
+    .strict();
+export const projectBillingQuoteSchema = projectBillingQuoteRequestSchema.extend({
+    quote: z.string().min(1).max(128),
+    expectedRevision: z.number().int().nonnegative(),
+    expiresAt: timestampSchema,
+    charge: nonnegativeExactMoneySchema,
+    monthlyProjectFees: nonnegativeExactMoneySchema,
+    effectiveAt: timestampSchema,
+    formerIncludedWillBlock: z.boolean(),
+});
+export const projectBillingChangeRequestSchema = z
+    .object({
+    quote: z.string().min(1).max(128),
+    expectedRevision: z.number().int().nonnegative(),
+    confirmed: z.literal(true),
+})
+    .strict();
+export const projectBillingStateSchema = z.object({
+    includedProject: projectIdSchema.optional(),
+    desiredRevision: z.number().int().positive(),
+    effectiveRevision: z.number().int().nonnegative(),
+    pending: z.boolean(),
+    recurringProjectFees: nonnegativeExactMoneySchema,
+    projects: z.array(z.object({
+        name: z.string(),
+        project: projectIdSchema,
+        access: z.enum(["included", "paid", "blocked"]),
+        paidThroughAt: timestampSchema.optional(),
+        renewalGraceUntil: timestampSchema.optional(),
+        cancellationAt: timestampSchema.optional(),
+        deleted: z.boolean(),
+    })),
+    pendingOperations: z.array(z.object({
+        id: z.string().min(1).max(255),
+        kind: z.enum(["add", "cancel"]),
+        project: projectIdSchema,
+        state: z.enum(["pending", "action-required"]),
+        paymentUrl: z.string().url().optional(),
+        reason: z.string().min(1).max(128).optional(),
+    })),
+});
+export const billingPortalSchema = z.object({ url: z.string().url() });
+const savedCardSchema = z
+    .object({
+    brand: z.string().min(1).max(32),
+    last4: z.string().regex(/^\d{4}$/u),
+    expMonth: z.number().int().min(1).max(12),
+    expYear: z.number().int().min(2000).max(2200),
+})
+    .strict();
+/** How a saved payment method is named to a person, on every surface alike. */
+const paymentMethodLabelSchema = z.string().min(1).max(200);
+/**
+ * The organization's saved payment method (W9-09, widened by W9-14): the one
+ * method automatic top-ups and project subscriptions charge. It is the Stripe
+ * customer's default payment method, read by authenticated provider call and
+ * never stored by GreatWait beyond the provider's own identifier.
+ *
+ * `method` says what it is. A card keeps its brand and last four digits; Link
+ * carries the email it is registered to when the provider reports one; any
+ * other type the provider's checkout offered (Cash App Pay, Amazon Pay,
+ * Klarna) carries the provider's type name. Every variant carries `label`,
+ * the sentence-ready name the dashboard, command line and MCP all show, so no
+ * client needs its own table of provider types. `method` is null when nothing
+ * is saved.
+ *
+ * `card` is the pre-W9-14 field, kept so a client written against it keeps
+ * working: it is set exactly when `method.type` is `card`, and null otherwise
+ * — including when a non-card method is saved, which such a client reads as
+ * "no card".
+ */
+export const billingPaymentMethodSchema = z
+    .object({
+    card: savedCardSchema.nullable(),
+    method: z
+        .discriminatedUnion("type", [
+        savedCardSchema
+            .extend({
+            type: z.literal("card"),
+            label: paymentMethodLabelSchema,
+        })
+            .strict(),
+        z
+            .object({
+            type: z.literal("link"),
+            label: paymentMethodLabelSchema,
+            email: z.string().min(3).max(320).nullable(),
+        })
+            .strict(),
+        z
+            .object({
+            type: z.literal("other"),
+            label: paymentMethodLabelSchema,
+            providerType: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/u),
+        })
+            .strict(),
+    ])
+        .nullable(),
+})
+    .strict();
+/**
+ * Where hosted card setup returns. Optional: the configured dashboard billing
+ * page is the default, and a supplied address must share its origin, so the
+ * operation cannot be used to send a customer to a page GreatWait does not own.
+ */
+export const billingPaymentMethodSetupRequestSchema = z
+    .object({
+    returnUrl: z.string().url().max(2048).optional(),
+})
+    .strict();
+/** The hosted card-setup Checkout session a browser returned from. */
+export const billingPaymentMethodConfirmRequestSchema = z
+    .object({
+    checkoutSession: z
+        .string()
+        .min(4)
+        .max(255)
+        .regex(/^cs_[A-Za-z0-9_]+$/u),
+})
+    .strict();
+/**
+ * Removing the card on file (W9-09). The literal `true` is the caller's
+ * acknowledgement of what removal does: project subscriptions stop renewing,
+ * paid projects run to the end of the period already paid for and then stop,
+ * and automatic top-up turns off.
+ */
+export const billingPaymentMethodRemoveRequestSchema = z
+    .object({ confirmed: z.literal(true) })
+    .strict();
+/**
+ * One project subscription charge (W9-09): a provider invoice for the
+ * organization's project subscription, listed beside execution-credit
+ * payments so a customer who was charged for a project sees the charge and its
+ * receipt. `amount` is the invoice total, tax included. `receiptUrl` is the
+ * provider-hosted invoice page when there is one.
+ */
+export const billingInvoiceSchema = z
+    .object({
+    id: z.string().min(1).max(255),
+    createdAt: timestampSchema,
+    amount: nonnegativeExactMoneySchema,
+    state: z.enum(["paid", "open", "void", "uncollectible"]),
+    receiptUrl: z.string().url().optional(),
+})
+    .strict();
+/** Execution-credit payment history, with a bounded continuation. */
+export const billingPaymentHistoryPageSchema = pageSchema(billingPaymentOperationSchema).strict();
+/** Project subscription history; an empty filtered page may still have a cursor. */
+export const billingInvoiceHistoryPageSchema = pageSchema(billingInvoiceSchema).strict();
+/** Project subscription charges, most recent first, at most 24. */
+export const billingInvoiceListSchema = z
+    .object({ data: z.array(billingInvoiceSchema) })
+    .strict();
+/**
+ * The stable title of the refusal a card-dependent change receives when the
+ * organization has no card on file (W9-09): enabling or resuming automatic
+ * top-up, and quoting or confirming a paid project addition.
+ *
+ * **Why a title and not a new problem code.** The published CLI and SDK parse
+ * error bodies with this package's `problemSchema`, whose `code` is a closed
+ * enum, so a code an installed client does not know turns a precise refusal into
+ * "failed with status 409" with no problem at all. The refusal is therefore
+ * `state_conflict` — which is what it is: the request is well formed and would
+ * succeed once a card is saved — and this exact title is the discriminator.
+ * Detect it as `code === "state_conflict" && title ===
+ * BILLING_PAYMENT_METHOD_REQUIRED_TITLE`.
+ */
+export const BILLING_PAYMENT_METHOD_REQUIRED_TITLE = "A card on file is required";