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

package/dist/billing.js

@@ -0,0 +1,684 @@
+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",
+];
+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({
+    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,
+    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),
+    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() });

package/dist/callback-safety.d.ts

@@ -4,8 +4,8 @@
  * DNS is deliberately not represented here: names are resolved and every
  * returned address is passed through `isPublicCallbackAddress` by the caller.
  *
- * **That caller is endpoint creation and verification, and since 2026-08-11 it
- * is nowhere else.** This comment used to end "and immediately before a send",
+ * **That caller is endpoint creation and update, and since 2026-08-11 it is
+ * nowhere else.** This comment used to end "and immediately before a send",
  * which FXO-1566 made false when it removed the send-time re-resolution. What
  * runs at send time is `evaluateCallbackUrl` alone — a string check, which
  * cannot see where a hostname points now. FXO-1575 measured what the platform