@oxy.so/contracts 4.8.0 → 4.9.1

package/dist/esm/inference/economics.js

@@ -0,0 +1,132 @@
+/**
+ * Economic treatment and durable usage/cost reporting for inference
+ * (issue #1526, plan item I09).
+ *
+ * ## Two treatments, decided by the server
+ *
+ *  - `commercial` — the default for every caller. Reserve → settle → refund
+ *    (ADR 0009), when this deployment charges at all.
+ *  - `internal_metered` — a product relationship Oxy itself configured and
+ *    versioned (e.g. Alia consuming Kaana through the Oxy edge). No hold, no
+ *    receipt, no promotional grant, no `platform_revenue` entry and no transfer
+ *    between products; usage and cost are still recorded durably, and scopes,
+ *    revocation, technical capacity, model eligibility, privacy and
+ *    idempotency all still apply.
+ *
+ * The treatment is derived from the AUTHENTICATED application, its environment
+ * and lane, against a versioned policy. Nothing a caller sends — body, header,
+ * bot kind, agent id, delegated user — can select it, so neither value is ever
+ * accepted on a request shape.
+ *
+ * ## Four numbers that never merge
+ *
+ * A usage report separates what was consumed (units), upstream cost evidence
+ * (`providerCost`, reported or rate-card-estimated by Kaana's operator feed), what the published
+ * tariff would have charged (`tariff`) and what a customer was actually charged
+ * (`customerCharge`, from settled receipts only). A tariff is not a cost, and an
+ * UNKNOWN cost is reported as unknown — counted, never summed as zero.
+ */
+import { z } from 'zod';
+import { costCenterSchema } from './entitlement.js';
+import { currencyCodeSchema, exactDecimalSchema, usageSourceSchema, usageQuantitySchema } from './money.js';
+import { inferenceEnvironmentSchema, modelReferenceSchema } from './identifiers.js';
+import { inferenceRequestOutcomeSchema } from './usage.js';
+/** How a request is treated economically. The first entry is the default. */
+export const INFERENCE_ECONOMIC_TREATMENTS = ['commercial', 'internal_metered'];
+export const inferenceEconomicTreatmentSchema = z.enum(INFERENCE_ECONOMIC_TREATMENTS);
+/**
+ * Where an upstream attempt's cost came from, exactly as Kaana's operator feed
+ * states it: an exact provider billing fact, a versioned rate-card estimate, or
+ * nothing known. `unknown` carries no amount, so it cannot be summed as free.
+ */
+export const PROVIDER_COST_SOURCES = ['provider_reported', 'rate_card', 'unknown'];
+export const providerCostSourceSchema = z.enum(PROVIDER_COST_SOURCES);
+const nonNegativeCount = z.number().int().nonnegative().safe();
+/** One amount family, with the rows it could not include counted beside it. */
+const knownAmountSchema = z
+    .object({
+    /** Sum of the rows whose amount is known, in `currency`. */
+    amount: exactDecimalSchema,
+    /** Rows (requests or attempts) whose amount is known. */
+    knownCount: nonNegativeCount,
+    /** Rows that exist and have NO amount. Never folded into `amount` as zero. */
+    unknownCount: nonNegativeCount,
+})
+    .strict();
+/**
+ * What one cost centre consumed over a window under one economic treatment.
+ *
+ * `customerCharge` is always zero with zero receipts for `internal_metered`:
+ * those requests have no receipt by construction, and saying so is the point.
+ */
+export const costCenterUsageSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    /** `null` for usage booked to an account with no cost centre above it. */
+    costCenter: costCenterSchema.nullable(),
+    treatment: inferenceEconomicTreatmentSchema,
+    currency: currencyCodeSchema,
+    periodStart: z.string().datetime(),
+    periodEnd: z.string().datetime(),
+    /** Requests settled in the window (completed, failed, cancelled or partial). */
+    requestCount: nonNegativeCount,
+    /** Requests admitted and not yet settled when the report was read. */
+    inFlightCount: nonNegativeCount,
+    /** Expired admissions with no authoritative terminal usage; never called in-flight. */
+    expiredCount: nonNegativeCount.default(0),
+    /** Metered units, by unit name, summed over the settled requests. */
+    units: z.record(z.string(), nonNegativeCount),
+    /** The published tariff at each request's pinned price version. Not a cost. */
+    tariff: knownAmountSchema,
+    /** Upstream cost evidence, reported or estimated, per attempt including failed failovers. */
+    providerCost: knownAmountSchema.extend({
+        /** Attempts with a known subtotal and incomplete upstream cost coverage. */
+        partialCount: nonNegativeCount.default(0),
+        /** Requests with no ingested provider-cost attempt yet; never measured zero. */
+        missingRequestCount: nonNegativeCount.default(0),
+        /** Attempts priced in a different currency, excluded without currency conversion. */
+        otherCurrencyCount: nonNegativeCount.default(0),
+        /** Amount stated by the provider; this is not a copy of its invoice. */
+        providerReportedAmount: exactDecimalSchema.default('0'),
+        providerReportedCount: nonNegativeCount.default(0),
+        /** Amount estimated from Kaana's immutable rate card, never described as invoiced. */
+        estimatedAmount: exactDecimalSchema.default('0'),
+        estimatedCount: nonNegativeCount.default(0),
+    }),
+    /**
+     * What customers were actually charged, from settled receipts only. A
+     * request with no receipt was not charged — an internal one by
+     * construction, a shadow-metered one because charging is off.
+     */
+    customerCharge: z
+        .object({ amount: exactDecimalSchema, receiptCount: nonNegativeCount })
+        .strict(),
+})
+    .strict();
+/** A technical generation record for an internal request, never a financial receipt. */
+export const meteredGenerationSchema = z.object({
+    schemaVersion: z.literal(2),
+    kind: z.literal('metered_usage'),
+    meteredUsageId: z.string().min(1),
+    requestId: z.string().min(1),
+    generationId: z.string().min(1).optional(),
+    parentRequestId: z.string().min(1).optional(),
+    applicationId: z.string().min(1),
+    credentialId: z.string().min(1),
+    delegatedUserId: z.string().min(1).optional(),
+    environment: inferenceEnvironmentSchema,
+    economicTreatment: z.literal('internal_metered'),
+    economicPolicyVersion: z.string().min(1),
+    outcome: inferenceRequestOutcomeSchema,
+    usageSource: usageSourceSchema,
+    units: z.array(usageQuantitySchema),
+    resolvedModelReference: modelReferenceSchema,
+    servingProvider: z.string().min(1),
+    tariff: z.discriminatedUnion('status', [
+        z.object({ status: z.literal('quoted'), amount: exactDecimalSchema, currency: currencyCodeSchema,
+            priceVersionId: z.string().min(1) }).strict(),
+        z.object({ status: z.literal('unpriced'), priceVersionId: z.string().min(1).nullable() }).strict(),
+    ]),
+    customerCharge: z.object({ status: z.literal('not_charged') }).strict(),
+    settledAt: z.string().datetime(),
+}).strict();

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();
 /**