@oxy.so/contracts 4.10.0 → 4.11.0-oxy-one.0

package/dist/esm/index.js

@@ -14,7 +14,7 @@ export { ACCOUNT_ACTOR_NATURES, ACCOUNT_SUBJECT_CONTRACT_VERSION, FINANCIAL_EFFE
 export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, RESERVED_USERNAME_MESSAGE, NUMERIC_USERNAME_MESSAGE, } from './username.js';
 export { 
 // Schemas
-userNameSchema, userRelationshipSchema, themePreferenceSchema, dateOfBirthSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, 
+userNameSchema, userRelationshipSchema, themePreferenceSchema, USER_PROFILE_COLOR_PRESETS, dateOfBirthSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, 
 // Helpers
 resolveUserId, safeParseContract, } from './userResponse.js';
 export { 
@@ -192,8 +192,10 @@ export { SCOPED_EXECUTION_CONTRACT_VERSION, SCOPED_REQUEST_ENVELOPE_VERSION, sco
 export { scopedInferenceRequestSchema } from './inference/request.js';
 export { PRIVATE_AUTO_EXECUTION_CONTRACT_VERSION, PRIVATE_AUTO_REQUEST_ENVELOPE_VERSION, PRIVATE_AUTO_LIMITS, PRIVATE_AUTO_INSTRUCTIONS, PRIVATE_AUTO_QUESTION, privateAutoPrincipalSchema, privateAutoSourceApprovalSchema, privateAutoExecutionSchema, privateAutoInputSchema, privateAutoOperationId, } from './inference/privateAutoExecution.js';
 export { privateAutoInferenceRequestSchema } from './inference/request.js';
-export { productDefinitionSchema, subjectProductAccessQuerySchema, productBenefitSchema, productOfferSchema, productSubscriptionSourceSchema, productAccessGrantSchema, productOfferSegmentSchema, subjectProductAccessSchema, } from './products/access.js';
+export { productDefinitionSchema, subjectProductAccessQuerySchema, productBenefitSchema, productOfferSchema, productSubscriptionSourceSchema, productAccessGrantSchema, subjectProductGrantSnapshotSchema, productOfferSegmentSchema, subjectProductAccessSchema, } from './products/access.js';
 export { meteredGenerationSchema } from "./inference/economics.js";
 export { canonicalCapabilityJson, inputSatisfiesCapabilityLimits, isLoopbackOrigin } from './capabilityBindings.js';
 export * from './agentKeys.js';
 export { productSubscriptionSummarySchema, productSubscriptionsResponseSchema, subscriptionCreditGrantSchema, subscriptionCreditGrantsResponseSchema, cancelProductSubscriptionSchema, productSubscriptionCancellationResultSchema } from './products/billing.js';
+export { personalPlanDisplayPriceSchema, personalPlanCatalogueSchema } from './products/plans.js';
+export * from './products/checkout.js';

package/dist/esm/products/access.js

@@ -55,3 +55,34 @@ export const subjectProductAccessSchema = z.object({
         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

@@ -21,7 +21,7 @@ export const subscriptionCreditGrantSchema = z.object({ id, invoiceId: id,
     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();
+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,14 @@
+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://') }).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,20 @@
+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/userResponse.js

@@ -1,3 +1,5 @@
+/** Canonical profile/theme preset identities accepted by Oxy writes. */
+export const USER_PROFILE_COLOR_PRESETS = ['teal', 'blue', 'green', 'amber', 'red', 'purple', 'pink', 'sky', 'orange', 'mint', 'mono', 'oxy'];
 /**
  * Canonical API user-response contracts.
  *
@@ -220,6 +222,7 @@ export const userResponseSchema = z
      * `GET /session/user/:sessionId`) and absent until the user sets it.
      */
     themePreference: themePreferenceSchema.optional(),
+    personalization: z.object({ mentionMono: z.object({ allowed: z.boolean(), expiresAt: z.string().datetime().nullable() }).strict() }).strict().optional(),
 })
     .passthrough();
 export const userProfileUpdateSchema = z