@oxy.so/contracts 4.7.0 → 4.9.0

package/dist/esm/inference/request.js

@@ -25,6 +25,7 @@
  */
 import { decisionInputSchema } from './decisions.js';
 import { z } from "zod";
+import { scopedExecutionSchema, SCOPED_REQUEST_ENVELOPE_VERSION } from "./scopedExecution.js";
 import { inferenceAttributionSchema } from "./attribution.js";
 import { inferenceApiFormatSchema, inferenceModalitySchema, reasoningEffortSchema, } from "./catalogue.js";
 import { idempotencyKeySchema, inferenceTimestampSchema } from "./identifiers.js";
@@ -351,6 +352,8 @@ export const inferenceRequestSchema = z
     .object({
     /** See `version.ts`: this is the Oxy→data-plane request envelope. */
     schemaVersion: z.literal(2),
+    /** Recognized so v2 refuses rather than silently stripping a restriction. */
+    scopedExecution: scopedExecutionSchema.optional(),
     attribution: inferenceAttributionSchema,
     target: routingTargetSchema,
     modality: inferenceModalitySchema,
@@ -405,6 +408,8 @@ export const inferenceRequestSchema = z
     authorizedRoutes: z.array(authorizedRouteSchema).min(1).optional(),
 })
     .superRefine((request, ctx) => {
+    if (request.scopedExecution !== undefined)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["scopedExecution"], message: "Scoped execution requires envelope v3." });
     if (request.input.format === "decisions" || request.client.apiFormat === "decisions") {
         const exactModel = request.target.kind === "model" && request.target.modelReference.includes('@');
         const foreignRoute = request.authorizedRoutes?.some((route) => request.target.kind !== "model" || route.modelReference !== request.target.modelReference || route.substitution !== "same_model");
@@ -534,3 +539,30 @@ export const inferenceRequestSchema = z
         });
     }
 });
+/** Explicit restrictive generation: old v2 receivers reject this version whole. */
+export const scopedInferenceRequestSchema = inferenceRequestSchema.innerType()
+    .extend({ schemaVersion: z.literal(SCOPED_REQUEST_ENVELOPE_VERSION), scopedExecution: scopedExecutionSchema })
+    .superRefine((request, ctx) => {
+    const { scopedExecution: scope, ...base } = request;
+    const legacy = inferenceRequestSchema.safeParse({ ...base, schemaVersion: 2 });
+    if (!legacy.success)
+        for (const issue of legacy.error.issues)
+            ctx.addIssue(issue);
+    const principal = request.attribution.principal;
+    const route = request.authorizedRoutes?.[0];
+    if (request.input.format !== "decisions" || request.client.apiFormat !== "decisions" ||
+        scope.requestId !== request.attribution.requestId ||
+        scope.idempotencyKey !== request.idempotencyKey ||
+        scope.principal.accountId !== principal.billing.accountId ||
+        scope.principal.applicationId !== principal.applicationId ||
+        scope.principal.credentialId !== principal.credentialId ||
+        scope.principal.environment !== principal.environment ||
+        scope.policy.routingPolicyId !== request.routingPolicy.routingPolicyId ||
+        scope.policy.policyVersion !== request.routingPolicy.policyVersion ||
+        request.authorizedRoutes?.length !== 1 || route?.customerProviderCredential !== undefined ||
+        route?.deploymentId !== scope.deploymentId || route?.provider !== scope.provider ||
+        route?.modelReference !== scope.modelReference ||
+        request.target.kind !== "model" || request.target.modelReference !== scope.modelReference) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["scopedExecution"], message: "Scoped execution must restrict the exact attributed decisions request and one platform route." });
+    }
+});

package/dist/esm/inference/scopedExecution.js

@@ -0,0 +1,83 @@
+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";
+/** 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);
+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"));
+    return units > 0n && units <= 10000000000n;
+}, "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({
+    permitId: identity,
+    idempotencyKey: idempotencyKeySchema,
+    fixtureSha256: sha256,
+    expiresAt: z.string().datetime(),
+    principal: z
+        .object({
+        accountId: identity,
+        applicationId: identity,
+        credentialId: identity,
+        environment: inferenceEnvironmentSchema,
+    })
+        .strict(),
+    policy: z
+        .object({
+        routingPolicyId: z.string().min(1).max(128),
+        policyVersion: z.number().int().positive().safe(),
+    })
+        .strict(),
+    deploymentId: deploymentIdSchema,
+    provider: inferenceProviderSlugSchema,
+    keyId: identity,
+    modelReference: modelReferenceSchema.refine((value) => value.includes("@"), "must pin a revision"),
+    upstreamModelId: identity,
+    priceVersionId: identity,
+    providerRateCardVersionId: identity,
+    providerSourceVersion: identity,
+    maxCostUsd: maxCost,
+})
+    .strict();
+export const scopedExecutionSchema = scopedExecutionAudienceSchema
+    .extend({
+    requestId: requestIdSchema,
+    snapshotId: identity,
+    catalogueEvidenceHash: sha256,
+})
+    .strict();
+/**
+ * Canonical JSON wire bytes: recursive UTF-16 key order, JSON string/number
+ * encoding, arrays in order, no whitespace. Hash the whole signed input, not a
+ * reparsed/defaulted decision. Reject non-JSON values rather than dropping them.
+ */
+export function canonicalScopedExecutionJson(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(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.");
+            return canonicalScopedExecutionJson(entry);
+        });
+        return `[${entries.join(",")}]`;
+    }
+    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(",")}}`;
+    }
+    throw new Error("Scoped execution requires JSON wire values.");
+}

package/dist/esm/products/access.js

@@ -0,0 +1,57 @@
+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');
+/** Product ownership and audience are registered together; branding grants no trust. */
+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();
+/** 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(),
+]);
+/** 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();
+/** 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();
+/** 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,
+    offerVersion: z.number().int().positive().safe(),
+    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,
+    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();

package/dist/esm/products/billing.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+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');
+/** 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(),
+        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();
+/** Remote acceptance is distinct from completed local reconciliation. */
+export const productSubscriptionCancellationResultSchema = z.union([
+    z.object({ sourceId: id, cancelAtPeriodEnd: z.literal(true) }).strict(),
+    z.object({ sourceId: id, reconciliationPending: z.literal(true) }).strict(),
+]);

package/dist/esm/signIn.js

@@ -194,7 +194,7 @@ export function isSecondFactorRequired(result) {
  * What a re-verification email code confirms. The code is bound to it: a code
  * asked for one change never authorises another, and the email names it.
  */
-export const REAUTH_ACTIONS = ['change_password', 'totp', 'link_commons', 'delete_account'];
+export const REAUTH_ACTIONS = ['change_password', 'totp', 'link_commons', 'delete_account', 'credentials_manage'];
 /** `POST /users/me/reauth/email` */
 export const reauthEmailStartRequestSchema = z.object({ action: z.enum(REAUTH_ACTIONS) }).strict();
 /**