@greatwait/contracts 0.2.1 → 0.2.2

package/dist/billing.d.ts

@@ -706,6 +706,92 @@ export declare const billingSummarySchema: import("zod").ZodObject<{
             microdollars: import("zod").ZodString;
             scale: import("zod").ZodLiteral<6>;
         }, import("zod/v4/core").$strip>;
+        byKind: import("zod").ZodOptional<import("zod").ZodObject<{
+            purchased: import("zod").ZodObject<{
+                available: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                reserved: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                consumed: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                forfeited: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                granted: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                expiresAt: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>;
+            trial: import("zod").ZodObject<{
+                available: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                reserved: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                consumed: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                forfeited: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                granted: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                expiresAt: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>;
+            promotional: import("zod").ZodObject<{
+                available: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                reserved: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                consumed: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                forfeited: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                granted: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+                expiresAt: import("zod").ZodOptional<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>;
+        }, import("zod/v4/core").$strip>>;
     }, import("zod/v4/core").$strip>;
     desiredRevision: import("zod").ZodNumber;
     effectiveRevision: import("zod").ZodNumber;
@@ -970,6 +1056,23 @@ export declare const projectBillingQuoteSchema: import("zod").ZodObject<{
     }, import("zod/v4/core").$strip>;
     effectiveAt: import("zod").ZodString;
     formerIncludedWillBlock: import("zod").ZodBoolean;
+    discount: import("zod").ZodOptional<import("zod").ZodObject<{
+        gross: import("zod").ZodObject<{
+            currency: import("zod").ZodLiteral<"USD">;
+            microdollars: import("zod").ZodString;
+            scale: import("zod").ZodLiteral<6>;
+        }, import("zod/v4/core").$strip>;
+        amount: import("zod").ZodObject<{
+            currency: import("zod").ZodLiteral<"USD">;
+            microdollars: import("zod").ZodString;
+            scale: import("zod").ZodLiteral<6>;
+        }, import("zod/v4/core").$strip>;
+        duration: import("zod").ZodEnum<{
+            once: "once";
+            repeating: "repeating";
+        }>;
+        durationInMonths: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>>;
 }, import("zod/v4/core").$strict>;
 export declare const projectBillingChangeRequestSchema: import("zod").ZodObject<{
     quote: import("zod").ZodString;
@@ -998,6 +1101,29 @@ export declare const projectBillingStateSchema: import("zod").ZodObject<{
         renewalGraceUntil: import("zod").ZodOptional<import("zod").ZodString>;
         cancellationAt: import("zod").ZodOptional<import("zod").ZodString>;
         deleted: import("zod").ZodBoolean;
+        complimentary: import("zod").ZodOptional<import("zod").ZodObject<{
+            grant: import("zod").ZodString;
+            endsAt: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+    discount: import("zod").ZodOptional<import("zod").ZodObject<{
+        grant: import("zod").ZodString;
+        duration: import("zod").ZodEnum<{
+            once: "once";
+            repeating: "repeating";
+        }>;
+        durationInMonths: import("zod").ZodOptional<import("zod").ZodNumber>;
+        percentOff: import("zod").ZodOptional<import("zod").ZodNumber>;
+        amountOff: import("zod").ZodOptional<import("zod").ZodObject<{
+            currency: import("zod").ZodLiteral<"USD">;
+            microdollars: import("zod").ZodString;
+            scale: import("zod").ZodLiteral<6>;
+        }, import("zod/v4/core").$strip>>;
+        state: import("zod").ZodEnum<{
+            pending: "pending";
+            applied: "applied";
+        }>;
+        appliedAt: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>>;
     pendingOperations: import("zod").ZodArray<import("zod").ZodObject<{
         id: import("zod").ZodString;
@@ -1230,4 +1356,217 @@ export type BillingInvoiceList = z.infer<typeof billingInvoiceListSchema>;
 export type BillingPaymentMethodSetupRequest = z.infer<typeof billingPaymentMethodSetupRequestSchema>;
 export type BillingPaymentMethodConfirmRequest = z.infer<typeof billingPaymentMethodConfirmRequestSchema>;
 export type BillingPaymentMethodRemoveRequest = z.infer<typeof billingPaymentMethodRemoveRequestSchema>;
+/**
+ * W7-15 launch promotions.
+ *
+ * A customer redeems a code; an operator grants directly. Either way the
+ * organization receives one benefit: promotional execution credit, a
+ * complimentary project slot, a perk, or a discount on the project
+ * subscription. Promotional value has no cash value, is never refunded and
+ * cannot move to another organization or product.
+ */
+export declare const PROMOTION_BENEFIT_KINDS: readonly ["credit", "project-slot", "perk", "discount"];
+export declare const promotionCodeSchema: import("zod").ZodString;
+export declare const billingRedeemRequestSchema: import("zod").ZodObject<{
+    code: import("zod").ZodString;
+    project: import("zod").ZodOptional<import("zod").ZodString>;
+    confirmed: import("zod").ZodLiteral<true>;
+}, import("zod/v4/core").$strict>;
+export declare const promotionGrantViewSchema: import("zod").ZodObject<{
+    id: import("zod").ZodString;
+    source: import("zod").ZodEnum<{
+        code: "code";
+        operator: "operator";
+    }>;
+    benefit: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"credit">;
+        amount: import("zod").ZodObject<{
+            currency: import("zod").ZodLiteral<"USD">;
+            microdollars: import("zod").ZodString;
+            scale: import("zod").ZodLiteral<6>;
+        }, import("zod/v4/core").$strip>;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"project-slot">;
+        project: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"perk">;
+        perk: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"discount">;
+        percentOff: import("zod").ZodOptional<import("zod").ZodNumber>;
+        amountOff: import("zod").ZodOptional<import("zod").ZodObject<{
+            currency: import("zod").ZodLiteral<"USD">;
+            microdollars: import("zod").ZodString;
+            scale: import("zod").ZodLiteral<6>;
+        }, import("zod/v4/core").$strip>>;
+        duration: import("zod").ZodEnum<{
+            once: "once";
+            repeating: "repeating";
+        }>;
+        durationInMonths: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>], "kind">;
+    state: import("zod").ZodEnum<{
+        expired: "expired";
+        active: "active";
+        revoked: "revoked";
+    }>;
+    startsAt: import("zod").ZodString;
+    endsAt: import("zod").ZodOptional<import("zod").ZodString>;
+    revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export type PromotionGrantView = z.infer<typeof promotionGrantViewSchema>;
+export declare const billingPromotionsSchema: import("zod").ZodObject<{
+    grants: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        source: import("zod").ZodEnum<{
+            code: "code";
+            operator: "operator";
+        }>;
+        benefit: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"credit">;
+            amount: import("zod").ZodObject<{
+                currency: import("zod").ZodLiteral<"USD">;
+                microdollars: import("zod").ZodString;
+                scale: import("zod").ZodLiteral<6>;
+            }, import("zod/v4/core").$strip>;
+        }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"project-slot">;
+            project: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"perk">;
+            perk: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"discount">;
+            percentOff: import("zod").ZodOptional<import("zod").ZodNumber>;
+            amountOff: import("zod").ZodOptional<import("zod").ZodObject<{
+                currency: import("zod").ZodLiteral<"USD">;
+                microdollars: import("zod").ZodString;
+                scale: import("zod").ZodLiteral<6>;
+            }, import("zod/v4/core").$strip>>;
+            duration: import("zod").ZodEnum<{
+                once: "once";
+                repeating: "repeating";
+            }>;
+            durationInMonths: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>], "kind">;
+        state: import("zod").ZodEnum<{
+            expired: "expired";
+            active: "active";
+            revoked: "revoked";
+        }>;
+        startsAt: import("zod").ZodString;
+        endsAt: import("zod").ZodOptional<import("zod").ZodString>;
+        revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    projectCapacity: import("zod").ZodObject<{
+        included: import("zod").ZodNumber;
+        paid: import("zod").ZodNumber;
+        complimentary: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    perks: import("zod").ZodArray<import("zod").ZodObject<{
+        perk: import("zod").ZodString;
+        endsAt: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    restrictions: import("zod").ZodArray<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export type BillingPromotions = z.infer<typeof billingPromotionsSchema>;
+export declare const billingRedeemResponseSchema: import("zod").ZodObject<{
+    grant: import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        source: import("zod").ZodEnum<{
+            code: "code";
+            operator: "operator";
+        }>;
+        benefit: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"credit">;
+            amount: import("zod").ZodObject<{
+                currency: import("zod").ZodLiteral<"USD">;
+                microdollars: import("zod").ZodString;
+                scale: import("zod").ZodLiteral<6>;
+            }, import("zod/v4/core").$strip>;
+        }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"project-slot">;
+            project: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"perk">;
+            perk: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+            kind: import("zod").ZodLiteral<"discount">;
+            percentOff: import("zod").ZodOptional<import("zod").ZodNumber>;
+            amountOff: import("zod").ZodOptional<import("zod").ZodObject<{
+                currency: import("zod").ZodLiteral<"USD">;
+                microdollars: import("zod").ZodString;
+                scale: import("zod").ZodLiteral<6>;
+            }, import("zod/v4/core").$strip>>;
+            duration: import("zod").ZodEnum<{
+                once: "once";
+                repeating: "repeating";
+            }>;
+            durationInMonths: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>], "kind">;
+        state: import("zod").ZodEnum<{
+            expired: "expired";
+            active: "active";
+            revoked: "revoked";
+        }>;
+        startsAt: import("zod").ZodString;
+        endsAt: import("zod").ZodOptional<import("zod").ZodString>;
+        revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>;
+    promotions: import("zod").ZodObject<{
+        grants: import("zod").ZodArray<import("zod").ZodObject<{
+            id: import("zod").ZodString;
+            source: import("zod").ZodEnum<{
+                code: "code";
+                operator: "operator";
+            }>;
+            benefit: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"credit">;
+                amount: import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"project-slot">;
+                project: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"perk">;
+                perk: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                kind: import("zod").ZodLiteral<"discount">;
+                percentOff: import("zod").ZodOptional<import("zod").ZodNumber>;
+                amountOff: import("zod").ZodOptional<import("zod").ZodObject<{
+                    currency: import("zod").ZodLiteral<"USD">;
+                    microdollars: import("zod").ZodString;
+                    scale: import("zod").ZodLiteral<6>;
+                }, import("zod/v4/core").$strip>>;
+                duration: import("zod").ZodEnum<{
+                    once: "once";
+                    repeating: "repeating";
+                }>;
+                durationInMonths: import("zod").ZodOptional<import("zod").ZodNumber>;
+            }, import("zod/v4/core").$strip>], "kind">;
+            state: import("zod").ZodEnum<{
+                expired: "expired";
+                active: "active";
+                revoked: "revoked";
+            }>;
+            startsAt: import("zod").ZodString;
+            endsAt: import("zod").ZodOptional<import("zod").ZodString>;
+            revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+        projectCapacity: import("zod").ZodObject<{
+            included: import("zod").ZodNumber;
+            paid: import("zod").ZodNumber;
+            complimentary: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>;
+        perks: import("zod").ZodArray<import("zod").ZodObject<{
+            perk: import("zod").ZodString;
+            endsAt: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+        restrictions: import("zod").ZodArray<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
+export type BillingRedeemResponse = z.infer<typeof billingRedeemResponseSchema>;
 export {};

package/dist/billing.js

@@ -1,5 +1,5 @@
 import { z } from "./zod.js";
-import { attemptIdSchema, projectIdSchema } from "./identifiers.js";
+import { attemptIdSchema, idSchema, projectIdSchema } from "./identifiers.js";
 import { pageRequestSchema, pageSchema, requiredIdempotencyRequestHeaderSchema, } from "./protocol.js";
 import { timestampSchema } from "./time.js";
 export const BILLING_AMOUNT_SCALE = 6;
@@ -598,6 +598,18 @@ export const billingPeriodSummarySchema = z.object({
     start: timestampSchema,
     end: timestampSchema,
 });
+function creditKindBalanceSchema() {
+    return z.object({
+        available: nonnegativeExactMoneySchema,
+        reserved: nonnegativeExactMoneySchema,
+        consumed: nonnegativeExactMoneySchema,
+        /** Expired or revoked before use; never spendable again. */
+        forfeited: nonnegativeExactMoneySchema,
+        granted: nonnegativeExactMoneySchema,
+        /** The earliest end of credit of this kind that is still available. */
+        expiresAt: timestampSchema.optional(),
+    });
+}
 export const billingSummarySchema = z
     .object({
     activation: z.object({
@@ -611,6 +623,18 @@ export const billingSummarySchema = z
         available: signedExactMoneySchema,
         consumed: nonnegativeExactMoneySchema,
         reserved: nonnegativeExactMoneySchema,
+        /**
+         * The same position by kind of credit (W7-15): purchased (never expires,
+         * refundable), trial and promotional (both expire, spent earliest
+         * expiry first and always before purchased credit).
+         */
+        byKind: z
+            .object({
+            purchased: creditKindBalanceSchema(),
+            trial: creditKindBalanceSchema(),
+            promotional: creditKindBalanceSchema(),
+        })
+            .optional(),
     }),
     desiredRevision: z.number().int().positive(),
     effectiveRevision: z.number().int().positive(),
@@ -682,6 +706,18 @@ export const projectBillingQuoteSchema = projectBillingQuoteRequestSchema.extend
     monthlyProjectFees: nonnegativeExactMoneySchema,
     effectiveAt: timestampSchema,
     formerIncludedWillBlock: z.boolean(),
+    /**
+     * A redeemed discount this charge receives (W7-15): `gross` less `amount`
+     * is `charge`, and `duration` says how many monthly invoices it covers.
+     */
+    discount: z
+        .object({
+        gross: nonnegativeExactMoneySchema,
+        amount: nonnegativeExactMoneySchema,
+        duration: z.enum(["once", "repeating"]),
+        durationInMonths: z.number().int().min(1).max(12).optional(),
+    })
+        .optional(),
 });
 export const projectBillingChangeRequestSchema = z
     .object({
@@ -690,6 +726,18 @@ export const projectBillingChangeRequestSchema = z
     confirmed: z.literal(true),
 })
     .strict();
+const promotionGrantIdSchema = idSchema("promotionGrant");
+/** A redeemed purchase discount on the project subscription (W7-15). */
+const projectDiscountSchema = z.object({
+    grant: promotionGrantIdSchema,
+    duration: z.enum(["once", "repeating"]),
+    durationInMonths: z.number().int().min(1).max(12).optional(),
+    percentOff: z.number().int().min(1).max(100).optional(),
+    amountOff: nonnegativeExactMoneySchema.optional(),
+    /** `pending` until it is attached to the subscription's invoices. */
+    state: z.enum(["pending", "applied"]),
+    appliedAt: timestampSchema.optional(),
+});
 export const projectBillingStateSchema = z.object({
     includedProject: projectIdSchema.optional(),
     desiredRevision: z.number().int().positive(),
@@ -704,7 +752,19 @@ export const projectBillingStateSchema = z.object({
         renewalGraceUntil: timestampSchema.optional(),
         cancellationAt: timestampSchema.optional(),
         deleted: z.boolean(),
+        /**
+         * A complimentary project slot (W7-15). The project costs nothing and
+         * is never part of the subscription; when the slot ends it is blocked
+         * until the customer chooses to add it as a paid project.
+         */
+        complimentary: z
+            .object({
+            grant: promotionGrantIdSchema,
+            endsAt: timestampSchema,
+        })
+            .optional(),
     })),
+    discount: projectDiscountSchema.optional(),
     pendingOperations: z.array(z.object({
         id: z.string().min(1).max(255),
         kind: z.enum(["add", "cancel"]),
@@ -841,3 +901,73 @@ export const billingInvoiceListSchema = z
  * BILLING_PAYMENT_METHOD_REQUIRED_TITLE`.
  */
 export const BILLING_PAYMENT_METHOD_REQUIRED_TITLE = "A card on file is required";
+/**
+ * W7-15 launch promotions.
+ *
+ * A customer redeems a code; an operator grants directly. Either way the
+ * organization receives one benefit: promotional execution credit, a
+ * complimentary project slot, a perk, or a discount on the project
+ * subscription. Promotional value has no cash value, is never refunded and
+ * cannot move to another organization or product.
+ */
+export const PROMOTION_BENEFIT_KINDS = [
+    "credit",
+    "project-slot",
+    "perk",
+    "discount",
+];
+/** A perk's name; which perks exist is the server's allowlist, now empty. */
+const promotionPerkNameSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9-]{0,63}$/u, "a perk's lowercase name");
+export const promotionCodeSchema = z
+    .string()
+    .trim()
+    .min(4)
+    .max(64)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9 _-]*$/u, "letters, digits, spaces, - and _");
+export const billingRedeemRequestSchema = z
+    .object({
+    code: promotionCodeSchema,
+    /** Required for a project-slot code: the project it covers. */
+    project: projectIdSchema.optional(),
+    confirmed: z.literal(true),
+})
+    .strict();
+const promotionBenefitViewSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("credit"), amount: nonnegativeExactMoneySchema }),
+    z.object({ kind: z.literal("project-slot"), project: projectIdSchema }),
+    z.object({ kind: z.literal("perk"), perk: promotionPerkNameSchema }),
+    z.object({
+        kind: z.literal("discount"),
+        percentOff: z.number().int().min(1).max(100).optional(),
+        amountOff: nonnegativeExactMoneySchema.optional(),
+        duration: z.enum(["once", "repeating"]),
+        durationInMonths: z.number().int().min(1).max(12).optional(),
+    }),
+]);
+export const promotionGrantViewSchema = z.object({
+    id: promotionGrantIdSchema,
+    source: z.enum(["operator", "code"]),
+    benefit: promotionBenefitViewSchema,
+    state: z.enum(["active", "expired", "revoked"]),
+    startsAt: timestampSchema,
+    /** The benefit's own end; a discount ends by `duration` instead. */
+    endsAt: timestampSchema.optional(),
+    revokedAt: timestampSchema.optional(),
+});
+export const billingPromotionsSchema = z.object({
+    grants: z.array(promotionGrantViewSchema),
+    /** Effective project capacity: each project that may deliver, by source. */
+    projectCapacity: z.object({
+        included: z.number().int().min(0),
+        paid: z.number().int().min(0),
+        complimentary: z.number().int().min(0),
+    }),
+    perks: z.array(z.object({ perk: promotionPerkNameSchema, endsAt: timestampSchema })),
+    restrictions: z.array(z.string().min(1).max(300)),
+});
+export const billingRedeemResponseSchema = z.object({
+    grant: promotionGrantViewSchema,
+    promotions: billingPromotionsSchema,
+});

package/dist/host-correlation.d.ts

@@ -0,0 +1,4 @@
+/** Nonunique: one host action may create several schedules. Exact, case-sensitive. */
+export declare const externalIdentifierSchema: import("zod").ZodString;
+export declare const scheduleTagSchema: import("zod").ZodString;
+export declare const scheduleTagsSchema: import("zod").ZodArray<import("zod").ZodString>;

package/dist/host-correlation.js

@@ -0,0 +1,18 @@
+import { z } from "./zod.js";
+/** Searchable host metadata is public schedule data; never put secrets here. */
+function boundedIdentifier(bytes) {
+    return z
+        .string()
+        .min(1)
+        .max(bytes)
+        .refine((value) => !value.includes("\u0000") &&
+        new TextEncoder().encode(value).length <= bytes, `must contain 1–${bytes} UTF-8 bytes and no NUL characters`);
+}
+/** Nonunique: one host action may create several schedules. Exact, case-sensitive. */
+export const externalIdentifierSchema = boundedIdentifier(256).describe("Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.");
+export const scheduleTagSchema = boundedIdentifier(64).describe("An exact, case-sensitive tag of at most 64 UTF-8 bytes.");
+export const scheduleTagsSchema = z
+    .array(scheduleTagSchema)
+    .max(16)
+    .refine((tags) => new Set(tags).size === tags.length, "must contain distinct tags")
+    .describe("Up to 16 distinct searchable tags. Omission preserves tags on replacement; [] clears them.");

package/dist/identifiers.d.ts

@@ -29,6 +29,8 @@ export declare const ID_PREFIXES: {
     readonly occurrence: "occ";
     readonly organization: "org";
     readonly project: "proj";
+    readonly promotionGrant: "grn";
+    readonly promotionOffer: "ofr";
     readonly schedule: "sch";
     readonly testSink: "tsk";
     readonly testSinkDelivery: "tsd";

package/dist/identifiers.js

@@ -41,6 +41,9 @@ export const ID_PREFIXES = {
     occurrence: "occ",
     organization: "org",
     project: "proj",
+    // A launch offer and one organization's grant of a benefit (W7-15).
+    promotionGrant: "grn",
+    promotionOffer: "ofr",
     schedule: "sch",
     // A deterministic test-only callback receiver, and one delivery it recorded.
     // The receipt has its own prefix rather than reusing `delivery`, which names

package/dist/index.d.ts

@@ -28,9 +28,10 @@ export { BILLABLE_TERMINAL_STATES, USAGE_BOUNDS, USAGE_WINDOW_REASONS, billableT
 export { BILLING_ACTIVATION_MODES, BILLING_AMOUNT_SCALE, BILLING_BLOCK_REASONS, BILLING_CURRENCY, BILLING_ENTRY_KINDS, BILLING_LEDGER_ENTRY_NOTES, BILLING_PAYMENT_KINDS, BILLING_PAYMENT_STATES, BILLING_NOTICE_KINDS, billingAutoTopUpApplyRequestSchema, billingAutoTopUpConfigurationSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingAutoTopUpRuleSchema, billingBudgetPolicySchema, billingBudgetUpdateRequestHeadersSchema, billingBudgetUpdateRequestSchema, billingBudgetUpdateResponseSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingFundingViewSchema, billingNoticePageSchema, billingNoticeRecoveryPathSchema, billingNoticeSchema, billingNotificationSettingsSchema, billingNotificationSettingsUpdateRequestSchema, billingLedgerEntrySchema, billingLedgerPageSchema, billingLedgerRequestSchema, billingPaymentOperationSchema, billingPeriodSummarySchema, billingPurchaseRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRefundRequestViewSchema, billingSummarySchema, exactCentMoneySchema, manualFundingCreditSchema, microdollarAmountSchema, nonnegativeMicrodollarAmountSchema, type BillingAutoTopUpApplyRequest, type BillingAutoTopUpConfiguration, type BillingAutoTopUpPreview, type BillingAutoTopUpPreviewRequest, type BillingAutoTopUpRule, type BillingCeilingUpdateRequest, type BillingFundingQuote, type BillingFundingQuoteRequest, type BillingFundingView, type BillingNotice, type BillingNoticePage, type BillingNotificationSettings, type BillingNotificationSettingsUpdateRequest, type BillingLedgerEntryView, type BillingLedgerPage, type BillingLedgerRequest, type BillingBudgetUpdateRequest, type BillingBudgetUpdateResponse, type BillingPaymentOperation, type BillingPurchaseRequest, type BillingRefundRequestCreate, type BillingRefundResolutionRequest, type BillingRefundRequestView, type BillingSummaryView, } from "./billing.js";
 export { DELIVERY_TIMING_TARGETS_MS, DELIVERY_TIMING_VERDICTS, deliveryTimingSummarySchema, timingThresholdSummarySchema, type DeliveryTimingSummaryView, type TimingThresholdView, } from "./timing.js";
 export { CALLBACK_RECEIVER_DISPOSITIONS, CALLBACK_RECEIVER_PROTOCOL, CALLBACK_RECEIVER_STATUS, TEST_SINK_BEHAVIORS, TEST_SINK_BEHAVIOR_FACTS, TEST_SINK_BOUNDS, TEST_SINK_CLIENT_ERROR_STATUSES, TEST_SINK_DISPOSITIONS, TEST_SINK_PROTOCOL_VERSION, TEST_SINK_SERVER_ERROR_STATUSES, callbackReceiverAcknowledgementSchema, callbackReceiverDispositionSchema, resolveTestSinkAction, testSinkBehaviorSchema, testSinkCreateRequestSchema, testSinkDeliveryBodySchema, testSinkDispositionSchema, testSinkDeliveryPageSchema, testSinkDeliverySchema, testSinkPageSchema, testSinkProgramSchema, testSinkSchema, type CallbackReceiverAcknowledgement, type CallbackReceiverDisposition, type TestSink, type TestSinkAction, type TestSinkBehavior, type TestSinkCreateRequest, type TestSinkDelivery, type TestSinkDeliveryBody, type TestSinkDeliveryPage, type TestSinkDisposition, type TestSinkPage, type TestSinkProgram, } from "./test-sink.js";
-export { PROJECT_BILLING_ACTIONS, projectBillingQuoteRequestSchema, projectBillingQuoteSchema, projectBillingChangeRequestSchema, projectBillingStateSchema, billingPortalSchema, BILLING_PAYMENT_METHOD_REQUIRED_TITLE, billingPaymentMethodSchema, billingPaymentMethodSetupRequestSchema, billingPaymentMethodConfirmRequestSchema, billingPaymentMethodRemoveRequestSchema, billingInvoiceSchema, billingInvoiceListSchema, billingPaymentHistoryPageSchema, billingInvoiceHistoryPageSchema, type BillingPaymentHistoryPage, type BillingInvoiceHistoryPage, type BillingInvoice, type BillingInvoiceList, type BillingPaymentMethod, type BillingPaymentMethodSetupRequest, type BillingPaymentMethodConfirmRequest, type BillingPaymentMethodRemoveRequest, type ProjectBillingQuoteRequest, type ProjectBillingQuote, type ProjectBillingChangeRequest, type ProjectBillingState, } from "./billing.js";
+export { PROMOTION_BENEFIT_KINDS, billingPromotionsSchema, billingRedeemRequestSchema, billingRedeemResponseSchema, promotionCodeSchema, promotionGrantViewSchema, type BillingPromotions, type BillingRedeemResponse, type PromotionGrantView, PROJECT_BILLING_ACTIONS, projectBillingQuoteRequestSchema, projectBillingQuoteSchema, projectBillingChangeRequestSchema, projectBillingStateSchema, billingPortalSchema, BILLING_PAYMENT_METHOD_REQUIRED_TITLE, billingPaymentMethodSchema, billingPaymentMethodSetupRequestSchema, billingPaymentMethodConfirmRequestSchema, billingPaymentMethodRemoveRequestSchema, billingInvoiceSchema, billingInvoiceListSchema, billingPaymentHistoryPageSchema, billingInvoiceHistoryPageSchema, type BillingPaymentHistoryPage, type BillingInvoiceHistoryPage, type BillingInvoice, type BillingInvoiceList, type BillingPaymentMethod, type BillingPaymentMethodSetupRequest, type BillingPaymentMethodConfirmRequest, type BillingPaymentMethodRemoveRequest, type ProjectBillingQuoteRequest, type ProjectBillingQuote, type ProjectBillingChangeRequest, type ProjectBillingState, } from "./billing.js";
 export { effectiveCustomerLimitsSchema, type EffectiveCustomerLimits, } from "./effective-limits.js";
 export * from "./members.js";
 export * from "./http-request.js";
 export { sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, } from "./attempt-diagnostics.js";
 export { PROJECT_NOTIFICATION_OPERATIONS, notificationEmailRecipientsSchema, notificationEmailSettingsSchema, statusWebhookEventSchema, statusWebhookConfigurationSchema, projectNotificationSettingsSchema, projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, statusSigningKeyCreatedSchema, statusWebhookPayloadSchema, statusWebhookDeliverySchema, statusWebhookDeliveryPageSchema, type ProjectNotificationSettings, type ProjectNotificationSettingsUpdateRequest, type StatusSigningKeyCreated, type StatusWebhookEvent, type StatusWebhookPayload, type StatusWebhookDelivery, type StatusWebhookDeliveryPage, } from "./project-notifications.js";
+export { externalIdentifierSchema, scheduleTagSchema, scheduleTagsSchema, } from "./host-correlation.js";

package/dist/index.js

@@ -28,9 +28,10 @@ export { BILLABLE_TERMINAL_STATES, USAGE_BOUNDS, USAGE_WINDOW_REASONS, billableT
 export { BILLING_ACTIVATION_MODES, BILLING_AMOUNT_SCALE, BILLING_BLOCK_REASONS, BILLING_CURRENCY, BILLING_ENTRY_KINDS, BILLING_LEDGER_ENTRY_NOTES, BILLING_PAYMENT_KINDS, BILLING_PAYMENT_STATES, BILLING_NOTICE_KINDS, billingAutoTopUpApplyRequestSchema, billingAutoTopUpConfigurationSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingAutoTopUpRuleSchema, billingBudgetPolicySchema, billingBudgetUpdateRequestHeadersSchema, billingBudgetUpdateRequestSchema, billingBudgetUpdateResponseSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingFundingViewSchema, billingNoticePageSchema, billingNoticeRecoveryPathSchema, billingNoticeSchema, billingNotificationSettingsSchema, billingNotificationSettingsUpdateRequestSchema, billingLedgerEntrySchema, billingLedgerPageSchema, billingLedgerRequestSchema, billingPaymentOperationSchema, billingPeriodSummarySchema, billingPurchaseRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRefundRequestViewSchema, billingSummarySchema, exactCentMoneySchema, manualFundingCreditSchema, microdollarAmountSchema, nonnegativeMicrodollarAmountSchema, } from "./billing.js";
 export { DELIVERY_TIMING_TARGETS_MS, DELIVERY_TIMING_VERDICTS, deliveryTimingSummarySchema, timingThresholdSummarySchema, } from "./timing.js";
 export { CALLBACK_RECEIVER_DISPOSITIONS, CALLBACK_RECEIVER_PROTOCOL, CALLBACK_RECEIVER_STATUS, TEST_SINK_BEHAVIORS, TEST_SINK_BEHAVIOR_FACTS, TEST_SINK_BOUNDS, TEST_SINK_CLIENT_ERROR_STATUSES, TEST_SINK_DISPOSITIONS, TEST_SINK_PROTOCOL_VERSION, TEST_SINK_SERVER_ERROR_STATUSES, callbackReceiverAcknowledgementSchema, callbackReceiverDispositionSchema, resolveTestSinkAction, testSinkBehaviorSchema, testSinkCreateRequestSchema, testSinkDeliveryBodySchema, testSinkDispositionSchema, testSinkDeliveryPageSchema, testSinkDeliverySchema, testSinkPageSchema, testSinkProgramSchema, testSinkSchema, } from "./test-sink.js";
-export { PROJECT_BILLING_ACTIONS, projectBillingQuoteRequestSchema, projectBillingQuoteSchema, projectBillingChangeRequestSchema, projectBillingStateSchema, billingPortalSchema, BILLING_PAYMENT_METHOD_REQUIRED_TITLE, billingPaymentMethodSchema, billingPaymentMethodSetupRequestSchema, billingPaymentMethodConfirmRequestSchema, billingPaymentMethodRemoveRequestSchema, billingInvoiceSchema, billingInvoiceListSchema, billingPaymentHistoryPageSchema, billingInvoiceHistoryPageSchema, } from "./billing.js";
+export { PROMOTION_BENEFIT_KINDS, billingPromotionsSchema, billingRedeemRequestSchema, billingRedeemResponseSchema, promotionCodeSchema, promotionGrantViewSchema, PROJECT_BILLING_ACTIONS, projectBillingQuoteRequestSchema, projectBillingQuoteSchema, projectBillingChangeRequestSchema, projectBillingStateSchema, billingPortalSchema, BILLING_PAYMENT_METHOD_REQUIRED_TITLE, billingPaymentMethodSchema, billingPaymentMethodSetupRequestSchema, billingPaymentMethodConfirmRequestSchema, billingPaymentMethodRemoveRequestSchema, billingInvoiceSchema, billingInvoiceListSchema, billingPaymentHistoryPageSchema, billingInvoiceHistoryPageSchema, } from "./billing.js";
 export { effectiveCustomerLimitsSchema, } from "./effective-limits.js";
 export * from "./members.js";
 export * from "./http-request.js";
 export { sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, } from "./attempt-diagnostics.js";
 export { PROJECT_NOTIFICATION_OPERATIONS, notificationEmailRecipientsSchema, notificationEmailSettingsSchema, statusWebhookEventSchema, statusWebhookConfigurationSchema, projectNotificationSettingsSchema, projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, statusSigningKeyCreatedSchema, statusWebhookPayloadSchema, statusWebhookDeliverySchema, statusWebhookDeliveryPageSchema, } from "./project-notifications.js";
+export { externalIdentifierSchema, scheduleTagSchema, scheduleTagsSchema, } from "./host-correlation.js";