@oxy.so/contracts 4.10.0 → 4.11.0

package/dist/esm/inference/scopedExecution.js

@@ -1,8 +1,8 @@
-import { z } from "zod";
-import { deploymentIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, inferenceProviderSlugSchema, modelReferenceSchema, requestIdSchema, } from "./identifiers.js";
-import { exactDecimalSchema } from "./money.js";
+import { z } from 'zod';
+import { deploymentIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, inferenceProviderSlugSchema, modelReferenceSchema, requestIdSchema, } from './identifiers.js';
+import { exactDecimalSchema } from './money.js';
 /** Explicit extension negotiation; never replaces the legacy 3.5 handshake. */
-export const SCOPED_EXECUTION_CONTRACT_VERSION = "3.6.0";
+export const SCOPED_EXECUTION_CONTRACT_VERSION = '3.6.0';
 /** Scoped only; normal envelope v2 and metadata 3.5 remain unchanged. */
 export const SCOPED_REQUEST_ENVELOPE_VERSION = 3;
 const identity = z.string().min(1).max(256);
@@ -10,10 +10,10 @@ const sha256 = z.string().regex(/^[0-9a-f]{64}$/);
 const maxCost = exactDecimalSchema.refine((value) => {
     if (!exactDecimalSchema.safeParse(value).success)
         return false;
-    const [whole, fraction = ""] = value.split(".");
-    const units = BigInt(whole) * 1000000000000n + BigInt(fraction.padEnd(12, "0"));
+    const [whole, fraction = ''] = value.split('.');
+    const units = BigInt(whole) * 1000000000000n + BigInt(fraction.padEnd(12, '0'));
     return units > 0n && units <= 10000000000n;
-}, "scoped cost must be positive and at most 0.01 USD");
+}, 'scoped cost must be positive and at most 0.01 USD');
 /** Restriction only: none of these identities grants catalogue eligibility. */
 export const scopedExecutionAudienceSchema = z
     .object({
@@ -38,7 +38,7 @@ export const scopedExecutionAudienceSchema = z
     deploymentId: deploymentIdSchema,
     provider: inferenceProviderSlugSchema,
     keyId: identity,
-    modelReference: modelReferenceSchema.refine((value) => value.includes("@"), "must pin a revision"),
+    modelReference: modelReferenceSchema.refine((value) => value.includes('@'), 'must pin a revision'),
     upstreamModelId: identity,
     priceVersionId: identity,
     providerRateCardVersionId: identity,
@@ -59,25 +59,25 @@ export const scopedExecutionSchema = scopedExecutionAudienceSchema
  * reparsed/defaulted decision. Reject non-JSON values rather than dropping them.
  */
 export function canonicalScopedExecutionJson(value) {
-    if (value === null || typeof value === "string" || typeof value === "boolean")
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
         return JSON.stringify(value);
-    if (typeof value === "number" && Number.isFinite(value))
+    if (typeof value === 'number' && Number.isFinite(value))
         return JSON.stringify(value);
     if (Array.isArray(value)) {
         const entries = Array.from(value, (entry, index) => {
             if (!(index in value))
-                throw new Error("Scoped execution requires dense JSON arrays.");
+                throw new Error('Scoped execution requires dense JSON arrays.');
             return canonicalScopedExecutionJson(entry);
         });
-        return `[${entries.join(",")}]`;
+        return `[${entries.join(',')}]`;
     }
-    if (typeof value === "object" &&
+    if (typeof value === 'object' &&
         value !== null &&
         Object.getPrototypeOf(value) === Object.prototype) {
         const entries = Object.keys(value)
             .sort()
             .map((key) => `${JSON.stringify(key)}:${canonicalScopedExecutionJson(value[key])}`);
-        return `{${entries.join(",")}}`;
+        return `{${entries.join(',')}}`;
     }
-    throw new Error("Scoped execution requires JSON wire values.");
+    throw new Error('Scoped execution requires JSON wire values.');
 }

package/dist/esm/inference/usage.js

@@ -62,12 +62,7 @@ export const usageReservationRequestSchema = z.object({
     expiresInSeconds: z.number().int().positive().max(86400),
 });
 /** Lifecycle of a hold. Terminal states are `settled`, `released`, `expired`. */
-export const usageReservationStatusSchema = z.enum([
-    'held',
-    'settled',
-    'released',
-    'expired',
-]);
+export const usageReservationStatusSchema = z.enum(['held', 'settled', 'released', 'expired']);
 /**
  * A hold placed against an account's balance.
  *
@@ -267,9 +262,7 @@ export const usageReceiptSchema = z
  * ledger accounts and only the second one is visible on an invoice.
  */
 export const usageRefundSubjectSchema = z.discriminatedUnion('kind', [
-    z
-        .object({ kind: z.literal('reservation'), reservationId: z.string().min(1).max(128) })
-        .strict(),
+    z.object({ kind: z.literal('reservation'), reservationId: z.string().min(1).max(128) }).strict(),
     z.object({ kind: z.literal('receipt'), receiptId: z.string().min(1).max(128) }).strict(),
 ]);
 /** Why money was given back or a hold was released. */

package/dist/esm/notifications.js

@@ -61,18 +61,38 @@ export const createOxyNotificationRequestSchema = z
     .superRefine((value, context) => {
     if (value.type === 'system') {
         if (value.actorId !== value.recipientId)
-            context.addIssue({ code: z.ZodIssueCode.custom, path: ['actorId'], message: 'a system notification is from the recipient\'s own account' });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['actorId'],
+                message: "a system notification is from the recipient's own account",
+            });
         if (!value.title)
-            context.addIssue({ code: z.ZodIssueCode.custom, path: ['title'], message: 'title is required for a system notification' });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['title'],
+                message: 'title is required for a system notification',
+            });
         if (!value.message)
-            context.addIssue({ code: z.ZodIssueCode.custom, path: ['message'], message: 'message is required for a system notification' });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['message'],
+                message: 'message is required for a system notification',
+            });
     }
     else {
         if (value.url !== undefined) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: ['url'], message: 'url is only stored for a system notification' });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['url'],
+                message: 'url is only stored for a system notification',
+            });
         }
         if (value.entityType === 'app') {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: ['entityType'], message: "entityType 'app' is only valid for a system notification" });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['entityType'],
+                message: "entityType 'app' is only valid for a system notification",
+            });
         }
     }
 });

package/dist/esm/oauth.js

@@ -68,45 +68,61 @@ export const oauthAuthorizeCodeResponseSchema = z.object({
  * Reuses the ordinary public application projection and adds only the public
  * DCR client id needed to bind the consent surface to the request.
  */
-export const mcpOAuthClientApplicationSchema = publicApplicationSchema.extend({
+export const mcpOAuthClientApplicationSchema = publicApplicationSchema
+    .extend({
     clientId: z.string().min(1),
-}).strict();
+})
+    .strict();
 /**
  * An effectful MCP action the requested capability set can actually invoke.
  * Every field is picked from the canonical catalog tool schema so consent can
  * never maintain a second tool description or effect classification.
  */
-export const mcpOAuthWriteActionSchema = catalogToolSchema.innerType().pick({
+export const mcpOAuthWriteActionSchema = catalogToolSchema
+    .innerType()
+    .pick({
     name: true,
     version: true,
     description: true,
     requiredCapabilities: true,
     effect: true,
-}).strict().refine((action) => action.effect !== 'read', {
+})
+    .strict()
+    .refine((action) => action.effect !== 'read', {
     message: 'MCP consent write actions must be effectful',
     path: ['effect'],
 });
 /** Exact, server-resolved context rendered before an external MCP grant. */
-export const mcpOAuthConsentContextSchema = z.object({
+export const mcpOAuthConsentContextSchema = z
+    .object({
     client: mcpOAuthClientApplicationSchema,
-    account: z.object({
+    account: z
+        .object({
         id: z.string().min(1),
         displayName: z.string().min(1).optional(),
         handle: z.string().min(1).optional(),
         avatar: z.string().min(1).optional(),
-    }).strict(),
-    resource: z.object({
+    })
+        .strict(),
+    resource: z
+        .object({
         appId: z.string().min(1),
         uri: z.string().url(),
         application: publicApplicationSchema,
-    }).strict(),
+    })
+        .strict(),
     capabilities: z.array(z.string().min(1)).min(1),
     writeActions: z.array(mcpOAuthWriteActionSchema),
-}).strict();
-export const mcpOAuthClientInfoResponseSchema = z.object({
+})
+    .strict();
+export const mcpOAuthClientInfoResponseSchema = z
+    .object({
     application: mcpOAuthClientApplicationSchema,
-}).strict();
-export const mcpOAuthConsentResponseSchema = z.object({
+})
+    .strict();
+export const mcpOAuthConsentResponseSchema = z
+    .object({
     consentRequired: z.boolean(),
     context: mcpOAuthConsentContextSchema,
-}).strict();
+})
+    .strict();

package/dist/esm/oxyRecordTypes.js

@@ -7,8 +7,8 @@
  * is rejected as `invalid_envelope`.
  *
  * `oxySignedRecordTypeSchema` is that runtime gate (the API's `verifyEnvelope`
- * re-narrows with it; the Mongoose `SignedRecord.type` enum and the Postgres
- * CHECK on `signed_records.type` are both derived from `.options`);
+ * re-narrows with it; the Postgres CHECK on `signed_records.type` is derived
+ * from `.options`);
  * `OxySignedRecordType` is the matching compile-time union the SDK
  * identity/civic mixins type against.
  *

package/dist/esm/products/access.js

@@ -2,56 +2,176 @@ import { z } from 'zod';
 import { oxyAccountIdSchema, oxyApplicationIdSchema } from '../inference/identifiers.js';
 const identifier = z.string().min(1).max(160);
 const count = z.number().int().nonnegative().safe();
-const period = z.object({ start: z.string().datetime(), end: z.string().datetime() }).strict()
-    .refine(value => Date.parse(value.end) > Date.parse(value.start), 'period end must follow start');
+const period = z
+    .object({ start: z.string().datetime(), end: z.string().datetime() })
+    .strict()
+    .refine((value) => Date.parse(value.end) > Date.parse(value.start), 'period end must follow start');
 /** Product ownership and audience are registered together; branding grants no trust. */
-export const productDefinitionSchema = z.object({
-    schemaVersion: z.literal(1), id: identifier, ownerAccountId: oxyAccountIdSchema,
+export const productDefinitionSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    id: identifier,
+    ownerAccountId: oxyAccountIdSchema,
     applicationId: oxyApplicationIdSchema,
-}).strict();
-export const subjectProductAccessQuerySchema = z.object({
-    schemaVersion: z.literal(1), subjectAccountId: oxyAccountIdSchema, productId: identifier,
-}).strict();
+})
+    .strict();
+export const subjectProductAccessQuerySchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    subjectAccountId: oxyAccountIdSchema,
+    productId: identifier,
+})
+    .strict();
 /** Every quota declares its combination rule; there is no commercial default. */
 export const productBenefitSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('capability'), productId: identifier, key: identifier }).strict(),
-    z.object({ kind: z.literal('quota'), productId: identifier, key: identifier,
-        unit: identifier, included: count, combination: z.enum(['maximum', 'sum', 'exclusive']) }).strict(),
+    z
+        .object({
+        kind: z.literal('quota'),
+        productId: identifier,
+        key: identifier,
+        unit: identifier,
+        included: count,
+        combination: z.enum(['maximum', 'sum', 'exclusive']),
+    })
+        .strict(),
 ]);
 /** A version names a frozen offer. An empty bundle grants nothing. */
-export const productOfferSchema = z.object({
-    schemaVersion: z.literal(1), id: identifier, version: z.number().int().positive().safe(),
-    kind: z.enum(['individual', 'bundle']), benefits: z.array(productBenefitSchema),
-}).strict().refine(value => value.kind === 'bundle' || new Set(value.benefits.map(benefit => benefit.productId)).size <= 1, 'individual offers cannot cover multiple products');
-export const productSubscriptionSourceSchema = z.object({
-    schemaVersion: z.literal(1), id: identifier,
-    beneficiaryAccountId: oxyAccountIdSchema, payerAccountId: oxyAccountIdSchema,
-    provider: z.enum(['stripe', 'peable']), providerSubscriptionId: identifier,
-    status: z.enum(['active', 'trialing', 'past_due', 'unpaid', 'canceled', 'paused', 'incomplete', 'incomplete_expired']),
-    period, cancelAtPeriodEnd: z.boolean(),
-}).strict();
+export const productOfferSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    id: identifier,
+    version: z.number().int().positive().safe(),
+    kind: z.enum(['individual', 'bundle']),
+    benefits: z.array(productBenefitSchema),
+})
+    .strict()
+    .refine((value) => value.kind === 'bundle' ||
+    new Set(value.benefits.map((benefit) => benefit.productId)).size <= 1, 'individual offers cannot cover multiple products');
+export const productSubscriptionSourceSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    id: identifier,
+    beneficiaryAccountId: oxyAccountIdSchema,
+    payerAccountId: oxyAccountIdSchema,
+    provider: z.enum(['stripe', 'peable']),
+    providerSubscriptionId: identifier,
+    status: z.enum([
+        'active',
+        'trialing',
+        'past_due',
+        'unpaid',
+        'canceled',
+        'paused',
+        'incomplete',
+        'incomplete_expired',
+    ]),
+    period,
+    cancelAtPeriodEnd: z.boolean(),
+})
+    .strict();
 /** A frozen paid-period/offer segment; upgrades append, never rewrite it. */
-export const productOfferSegmentSchema = z.object({
-    schemaVersion: z.literal(1), id: identifier, subscriptionId: identifier,
-    beneficiaryAccountId: oxyAccountIdSchema, offerId: identifier,
-    offerVersion: z.number().int().positive().safe(), origin: z.enum(['individual', 'bundle']), period,
-}).strict();
+export const productOfferSegmentSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    id: identifier,
+    subscriptionId: identifier,
+    beneficiaryAccountId: oxyAccountIdSchema,
+    offerId: identifier,
+    offerVersion: z.number().int().positive().safe(),
+    origin: z.enum(['individual', 'bundle']),
+    period,
+})
+    .strict();
 /** Provenance survives cancellation: deactivate a source, never delete history. */
-export const productAccessGrantSchema = z.object({
-    schemaVersion: z.literal(1), id: identifier, sourceSegmentId: identifier,
-    beneficiaryAccountId: oxyAccountIdSchema, offerId: identifier,
+export const productAccessGrantSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    id: identifier,
+    sourceSegmentId: identifier,
+    beneficiaryAccountId: oxyAccountIdSchema,
+    offerId: identifier,
     offerVersion: z.number().int().positive().safe(),
-    origin: z.enum(['individual', 'bundle']), benefit: productBenefitSchema,
-    period, revokedAt: z.string().datetime().nullable(),
-}).strict();
+    origin: z.enum(['individual', 'bundle']),
+    benefit: productBenefitSchema,
+    period,
+    revokedAt: z.string().datetime().nullable(),
+})
+    .strict();
 /** Access answers contain no payer, provider reference, price or account balance. */
-export const subjectProductAccessSchema = z.object({
-    schemaVersion: z.literal(1), subjectAccountId: oxyAccountIdSchema, productId: identifier,
+export const subjectProductAccessSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    subjectAccountId: oxyAccountIdSchema,
+    productId: identifier,
     evaluatedAt: z.string().datetime(),
     capabilities: z.array(z.object({ key: identifier, grantIds: z.array(identifier) }).strict()),
-    quotas: z.array(z.object({ key: identifier, unit: identifier, included: count,
-        combination: z.enum(['maximum', 'sum', 'exclusive']), grantIds: z.array(identifier) }).strict()),
-    conflicts: z.array(z.object({ key: identifier,
-        reason: z.enum(['combination_mismatch', 'unit_mismatch', 'exclusive_overlap', 'unsafe_total']),
-        grantIds: z.array(identifier) }).strict()),
-}).strict();
+    quotas: z.array(z
+        .object({
+        key: identifier,
+        unit: identifier,
+        included: count,
+        combination: z.enum(['maximum', 'sum', 'exclusive']),
+        grantIds: z.array(identifier),
+    })
+        .strict()),
+    conflicts: z.array(z
+        .object({
+        key: identifier,
+        reason: z.enum([
+            'combination_mismatch',
+            'unit_mismatch',
+            'exclusive_overlap',
+            'unsafe_total',
+        ]),
+        grantIds: z.array(identifier),
+    })
+        .strict()),
+})
+    .strict();
+/** Active grant periods for metering adapters; no financial/provider identity. */
+export const subjectProductGrantSnapshotSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    access: subjectProductAccessSchema,
+    grants: z.array(productAccessGrantSchema),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const active = new Set([...value.access.capabilities, ...value.access.quotas].flatMap((entry) => entry.grantIds));
+    if (active.size !== value.grants.length ||
+        new Set(value.grants.map((g) => g.id)).size !== value.grants.length ||
+        value.grants.some((g) => g.beneficiaryAccountId !== value.access.subjectAccountId ||
+            g.benefit.productId !== value.access.productId ||
+            !active.has(g.id) ||
+            // A future revocation is still active at evaluation time, as in access composition.
+            (g.revokedAt !== null &&
+                Date.parse(g.revokedAt) <= Date.parse(value.access.evaluatedAt)) ||
+            Date.parse(g.period.start) > Date.parse(value.access.evaluatedAt) ||
+            Date.parse(g.period.end) <= Date.parse(value.access.evaluatedAt)))
+        ctx.addIssue({ code: 'custom', message: 'Active grant snapshot attribution differs' });
+    for (const quota of value.access.quotas) {
+        const benefits = quota.grantIds.map((id) => value.grants.find((g) => g.id === id)?.benefit);
+        if (benefits.some((b) => !b ||
+            b.kind !== 'quota' ||
+            b.key !== quota.key ||
+            b.unit !== quota.unit ||
+            b.combination !== quota.combination)) {
+            ctx.addIssue({ code: 'custom', message: 'Grant quota terms differ' });
+            continue;
+        }
+        const amounts = benefits.map((b) => (b?.kind === 'quota' ? BigInt(b.included) : 0n));
+        const included = quota.combination === 'sum'
+            ? amounts.reduce((sum, n) => sum + n, 0n)
+            : amounts.reduce((maximum, n) => (n > maximum ? n : maximum), 0n);
+        if (included !== BigInt(quota.included) ||
+            (quota.combination === 'exclusive' && benefits.length > 1))
+            ctx.addIssue({ code: 'custom', message: 'Grant quota composition differs' });
+    }
+    for (const capability of value.access.capabilities)
+        if (capability.grantIds.some((id) => {
+            const benefit = value.grants.find((g) => g.id === id)?.benefit;
+            return benefit?.kind !== 'capability' || benefit.key !== capability.key;
+        }))
+            ctx.addIssue({ code: 'custom', message: 'Grant capability terms differ' });
+});

package/dist/esm/products/billing.js

@@ -3,25 +3,79 @@ import { oxyAccountIdSchema } from '../inference/identifiers.js';
 const id = z.string().min(1).max(160);
 const name = z.string().min(1).max(100);
 const count = z.number().int().nonnegative().safe();
-const period = z.object({ start: z.string().datetime(), end: z.string().datetime() }).strict()
-    .refine(value => Date.parse(value.end) > Date.parse(value.start), 'Period end must follow start');
+const period = z
+    .object({ start: z.string().datetime(), end: z.string().datetime() })
+    .strict()
+    .refine((value) => Date.parse(value.end) > Date.parse(value.start), 'Period end must follow start');
 /** Self-service provenance; no payer/provider identifiers or balances in access metadata. */
-export const productSubscriptionSummarySchema = z.object({ sourceId: id,
-    status: z.enum(['active', 'trialing', 'past_due', 'unpaid', 'canceled', 'paused', 'incomplete', 'incomplete_expired']),
-    period, cancelAtPeriodEnd: z.boolean(), canCancel: z.boolean(),
-    offers: z.array(z.object({ segmentId: id, offerId: id, offerVersion: z.number().int().positive().safe(),
-        displayName: name, origin: z.enum(['individual', 'bundle']), period, current: z.boolean(),
+export const productSubscriptionSummarySchema = z
+    .object({
+    sourceId: id,
+    status: z.enum([
+        'active',
+        'trialing',
+        'past_due',
+        'unpaid',
+        'canceled',
+        'paused',
+        'incomplete',
+        'incomplete_expired',
+    ]),
+    period,
+    cancelAtPeriodEnd: z.boolean(),
+    canCancel: z.boolean(),
+    offers: z.array(z
+        .object({
+        segmentId: id,
+        offerId: id,
+        offerVersion: z.number().int().positive().safe(),
+        displayName: name,
+        origin: z.enum(['individual', 'bundle']),
+        period,
+        current: z.boolean(),
         products: z.array(z.object({ id, displayName: name }).strict()),
-    }).strict()),
-}).strict();
-export const productSubscriptionsResponseSchema = z.object({ subscriptions: z.array(productSubscriptionSummarySchema) }).strict();
-export const subscriptionCreditGrantSchema = z.object({ id, invoiceId: id,
-    origin: z.enum(['subscription_payment', 'subscription_proration', 'subscription_promotional_grant']),
-    period, granted: count, consumed: count, clawed: count, remaining: count,
-    promotionId: id.nullable(), createdAt: z.string().datetime(),
-}).strict().refine(value => BigInt(value.consumed) + BigInt(value.clawed) + BigInt(value.remaining) === BigInt(value.granted), 'Grant conservation differs');
-export const subscriptionCreditGrantsResponseSchema = z.object({ grants: z.array(subscriptionCreditGrantSchema) }).strict();
-export const cancelProductSubscriptionSchema = z.object({ sourceId: id, expectedSubjectAccountId: oxyAccountIdSchema.optional() }).strict();
+    })
+        .strict()),
+})
+    .strict();
+export const productSubscriptionsResponseSchema = z
+    .object({ subscriptions: z.array(productSubscriptionSummarySchema) })
+    .strict();
+export const subscriptionCreditGrantSchema = z
+    .object({
+    id,
+    invoiceId: id,
+    origin: z.enum([
+        'subscription_payment',
+        'subscription_proration',
+        'subscription_promotional_grant',
+    ]),
+    period,
+    granted: count,
+    consumed: count,
+    clawed: count,
+    remaining: count,
+    promotionId: id.nullable(),
+    createdAt: z.string().datetime(),
+})
+    .strict()
+    .refine((value) => BigInt(value.consumed) + BigInt(value.clawed) + BigInt(value.remaining) ===
+    BigInt(value.granted), 'Grant conservation differs');
+export const subscriptionCreditGrantsResponseSchema = z
+    .object({ grants: z.array(subscriptionCreditGrantSchema) })
+    .strict();
+export const cancelProductSubscriptionSchema = z
+    .object({
+    sourceId: id,
+    actionId: z
+        .string()
+        .min(8)
+        .max(160)
+        .regex(/^[a-zA-Z0-9_-]+$/)
+        .optional(),
+    expectedSubjectAccountId: oxyAccountIdSchema.optional(),
+})
+    .strict();
 /** Remote acceptance is distinct from completed local reconciliation. */
 export const productSubscriptionCancellationResultSchema = z.union([
     z.object({ sourceId: id, cancelAtPeriodEnd: z.literal(true) }).strict(),

package/dist/esm/products/checkout.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { oxyAccountIdSchema } from '../inference/identifiers.js';
+export const personalPlanCheckoutRequestSchema = z
+    .object({
+    expectedSubjectAccountId: oxyAccountIdSchema,
+    offerId: z.string().min(1).max(160),
+    offerVersion: z.number().int().positive().safe(),
+    idempotencyKey: z
+        .string()
+        .min(8)
+        .max(160)
+        .regex(/^[a-zA-Z0-9_-]+$/),
+})
+    .strict();
+/** No grant or subscription is created by checkout completion in the browser. */
+export const personalPlanCheckoutResultSchema = z.discriminatedUnion('state', [
+    z
+        .object({
+        state: z.literal('unconfigured'),
+        reason: z.enum(['provider_unconfigured', 'offer_unconfigured', 'price_unconfigured']),
+    })
+        .strict(),
+    z
+        .object({
+        state: z.literal('pending'),
+        intentId: z.string().min(1).max(160),
+        checkoutUrl: z.string().url().startsWith('https://').optional(),
+    })
+        .strict(),
+    z.object({ state: z.literal('closed'), intentId: z.string().min(1).max(160) }).strict(),
+    z.object({ state: z.literal('fulfilled'), intentId: z.string().min(1).max(160) }).strict(),
+]);

package/dist/esm/products/plans.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { productBenefitSchema } from './access.js';
+/** Approved display terms never identify or activate a billing-provider price. */
+export const personalPlanDisplayPriceSchema = z
+    .object({
+    currency: z.string().regex(/^[A-Z]{3}$/),
+    amountMinorUnits: z.number().int().positive().safe(),
+    interval: z.literal('month'),
+    trial: z.literal('none'),
+    taxTreatment: z.literal('inclusive'),
+    merchantTotal: z.literal('final'),
+})
+    .strict();
+/** Public discovery is separate from customer access. No provider or owner IDs. */
+export const personalPlanCatalogueSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    state: z.enum(['unconfigured', 'configured']),
+    purchase: z.literal('unavailable'),
+    plans: z.array(z
+        .object({
+        offerId: z.string().min(1).max(160),
+        offerVersion: z.number().int().positive().safe(),
+        displayName: z.string().min(1).max(100),
+        audience: z.literal('personal'),
+        kind: z.literal('oxy_one'),
+        price: personalPlanDisplayPriceSchema.optional(),
+        benefits: z.array(z
+            .object({ displayName: z.string().min(1).max(100), benefit: productBenefitSchema })
+            .strict()),
+    })
+        .strict()),
+})
+    .strict()
+    .refine((value) => (value.state === 'unconfigured') === (value.plans.length === 0), 'Catalogue state must match published plans');

package/dist/esm/recommendations.js

@@ -13,11 +13,7 @@
 import { z } from 'zod';
 import { userNameSchema } from './userResponse.js';
 /** User-type filters a caller may exclude from the recommendation surface. */
-export const recommendationExcludeTypeSchema = z.enum([
-    'federated',
-    'agent',
-    'automated',
-]);
+export const recommendationExcludeTypeSchema = z.enum(['federated', 'agent', 'automated']);
 /**
  * A caller-supplied editorial boost. `userIds` are nudged up (or down, for a
  * negative weight) in the ranking; the optional `reason` is for audit/telemetry
@@ -122,7 +118,9 @@ export const appUserSignalIngestSchema = z
     endorsements: z.array(appEndorsementInputSchema).max(500).optional(),
     interests: z.array(appInterestInputSchema).max(500).optional(),
 })
-    .refine((value) => (value.endorsements?.length ?? 0) > 0 || (value.interests?.length ?? 0) > 0, { message: 'At least one of endorsements or interests must be non-empty' });
+    .refine((value) => (value.endorsements?.length ?? 0) > 0 || (value.interests?.length ?? 0) > 0, {
+    message: 'At least one of endorsements or interests must be non-empty',
+});
 /**
  * The directed interaction types a consuming app may report between two users.
  * Each type carries a server-side default weight (see the API's