@oxyhq/contracts 0.26.0 → 0.28.0

package/dist/types/inference/priceVersion.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Price versions — the immutable snapshots customer pricing is quoted and
+ * settled against.
+ *
+ * A price is never edited in place. A change publishes a NEW version that
+ * supersedes the old one, and every settled receipt keeps the id of the version
+ * it was priced with. That is what makes an invoice reproducible a year later:
+ * the receipt does not say "3.00 per million tokens", it says "priced under
+ * `pv_2026_08`", and that version still exists, unchanged, with its own
+ * effective window.
+ *
+ * Prices are exact decimal strings (see `money.ts`), never floats, and they are
+ * quoted per unit. The amount a customer owes is computed from them and is
+ * carried in the same exact form, so no step of the calculation passes through
+ * a representation that cannot hold the value.
+ *
+ * Decided in: docs/adr/0009-usage-reservation-and-settlement.md.
+ */
+import { z } from 'zod';
+/**
+ * Lifecycle of a price version.
+ *
+ * `draft` is quotable in Console previews but may never price a receipt;
+ * `active` is what live requests are priced with; `superseded` priced receipts
+ * in the past and still resolves for them forever.
+ */
+export declare const priceVersionStatusSchema: z.ZodEnum<["draft", "active", "superseded"]>;
+/**
+ * A published set of customer prices for one model reference on one provider.
+ *
+ * Scoped to a `(modelReference, provider)` pair rather than to a model alone
+ * because the same model costs different amounts on different providers, and a
+ * receipt has to be reproducible against the route that actually served it.
+ */
+export declare const priceVersionSchema: z.ZodEffects<z.ZodObject<{
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: z.ZodLiteral<1>;
+    priceVersionId: z.ZodString;
+    status: z.ZodEnum<["draft", "active", "superseded"]>;
+    modelReference: z.ZodString;
+    provider: z.ZodString;
+    currency: z.ZodString;
+    unitPrices: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        amount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+        per: z.ZodNumber;
+        currency: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }, {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }>, "many">;
+    effectiveFrom: z.ZodString;
+    /** Absent while this version is the current one. */
+    effectiveUntil: z.ZodOptional<z.ZodString>;
+    /** The version this one replaced, absent for the first version of a route. */
+    supersedesPriceVersionId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "active" | "superseded" | "draft";
+    createdAt: string;
+    currency: string;
+    provider: string;
+    schemaVersion: 1;
+    priceVersionId: string;
+    modelReference: string;
+    unitPrices: {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+    effectiveFrom: string;
+    effectiveUntil?: string | undefined;
+    supersedesPriceVersionId?: string | undefined;
+}, {
+    status: "active" | "superseded" | "draft";
+    createdAt: string;
+    currency: string;
+    provider: string;
+    schemaVersion: 1;
+    priceVersionId: string;
+    modelReference: string;
+    unitPrices: {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+    effectiveFrom: string;
+    effectiveUntil?: string | undefined;
+    supersedesPriceVersionId?: string | undefined;
+}>, {
+    status: "active" | "superseded" | "draft";
+    createdAt: string;
+    currency: string;
+    provider: string;
+    schemaVersion: 1;
+    priceVersionId: string;
+    modelReference: string;
+    unitPrices: {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+    effectiveFrom: string;
+    effectiveUntil?: string | undefined;
+    supersedesPriceVersionId?: string | undefined;
+}, {
+    status: "active" | "superseded" | "draft";
+    createdAt: string;
+    currency: string;
+    provider: string;
+    schemaVersion: 1;
+    priceVersionId: string;
+    modelReference: string;
+    unitPrices: {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+    effectiveFrom: string;
+    effectiveUntil?: string | undefined;
+    supersedesPriceVersionId?: string | undefined;
+}>;
+/**
+ * The price snapshot a settled receipt keeps.
+ *
+ * The unit prices are COPIED onto the receipt, not just referenced, so a receipt
+ * remains readable even if the price version record is later archived, and so
+ * that a mistake in the copy is visible as a disagreement with the version it
+ * names rather than silently invisible.
+ */
+export declare const priceSnapshotSchema: z.ZodObject<{
+    priceVersionId: z.ZodString;
+    currency: z.ZodString;
+    unitPrices: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        amount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+        per: z.ZodNumber;
+        currency: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }, {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    currency: string;
+    priceVersionId: string;
+    unitPrices: {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+}, {
+    currency: string;
+    priceVersionId: string;
+    unitPrices: {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+}>;
+export type PriceVersionStatus = z.infer<typeof priceVersionStatusSchema>;
+export type PriceVersion = z.infer<typeof priceVersionSchema>;
+export type PriceSnapshot = z.infer<typeof priceSnapshotSchema>;

package/dist/types/inference/providerConnection.d.ts

@@ -0,0 +1,297 @@
+/**
+ * BYOK provider connections — the metadata Oxy holds about a customer's own
+ * upstream provider credential.
+ *
+ * The credential itself is NOT here and cannot be put here. This shape carries
+ * a locator (`secretRef`) into Vault/KMS/managed secret storage, a prefix short
+ * enough to be useless, a fingerprint, and validation state. Two mechanisms
+ * make that structural rather than a convention somebody must remember:
+ *
+ *  - The object is `.strict()`. A producer that attaches `apiKey`, `secret`,
+ *    `token`, `privateKey` or `headers` fails the parse. Nothing is silently
+ *    stripped, because a stripped field is one that still exists upstream of
+ *    the parse, in a log line or an error report.
+ *  - `keyPrefix` is capped at 12 characters — shorter than any provider's
+ *    usable credential — so the one field designed to show part of a key cannot
+ *    be widened into showing all of it without changing the contract.
+ *
+ * BYOK does not move the billing relationship: the upstream provider bills the
+ * customer's own account directly, and Oxy charges only its platform fee. The
+ * record says so explicitly so a receipt against a BYOK route can be read
+ * correctly without consulting anything else.
+ *
+ * Decided in: issue #972 workstream 10.
+ */
+import { z } from 'zod';
+/**
+ * How widely a connection applies.
+ *
+ * In the unified account graph a project IS an account, so `account` and
+ * `project` differ by INHERITANCE, not by id space: an `account` connection is
+ * inherited by every descendant project and application, a `project` one
+ * applies to that project account alone, and an `application` one to a single
+ * application. Recording which the customer chose is what makes a later
+ * "why did this app use that key" answerable.
+ */
+export declare const providerConnectionScopeSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"account">;
+    accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+}, "strict", z.ZodTypeAny, {
+    kind: "account";
+    accountId: string & z.BRAND<"OxyAccountId">;
+}, {
+    kind: "account";
+    accountId: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"project">;
+    accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+}, "strict", z.ZodTypeAny, {
+    kind: "project";
+    accountId: string & z.BRAND<"OxyAccountId">;
+}, {
+    kind: "project";
+    accountId: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"application">;
+    accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    applicationId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "application";
+    accountId: string & z.BRAND<"OxyAccountId">;
+    applicationId: string;
+}, {
+    kind: "application";
+    accountId: string;
+    applicationId: string;
+}>]>;
+/**
+ * A locator for the credential in managed secret storage — never the credential.
+ *
+ * The scheme prefix is constrained to the stores Oxy actually uses, so a
+ * producer cannot pass a raw key through this field and have it look like a
+ * reference; whitespace is excluded for the same reason.
+ */
+export declare const providerSecretReferenceSchema: z.ZodString;
+/** Why a credential check failed, as a closed set the Console can render. */
+export declare const providerConnectionValidationSchema: z.ZodObject<{
+    state: z.ZodEnum<["unvalidated", "valid", "invalid", "expired"]>;
+    lastValidatedAt: z.ZodOptional<z.ZodString>;
+    /** Required when `invalid`: a failure nobody can act on is not a result. */
+    failureCode: z.ZodOptional<z.ZodEnum<["unauthorized", "forbidden", "not_found", "rate_limited", "network", "unknown"]>>;
+}, "strict", z.ZodTypeAny, {
+    state: "valid" | "invalid" | "expired" | "unvalidated";
+    lastValidatedAt?: string | undefined;
+    failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+}, {
+    state: "valid" | "invalid" | "expired" | "unvalidated";
+    lastValidatedAt?: string | undefined;
+    failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+}>;
+/** Lifecycle of a connection. `revoked` is terminal; `disabled` is reversible. */
+export declare const providerConnectionStatusSchema: z.ZodEnum<["pending_validation", "active", "disabled", "revoked"]>;
+/**
+ * A customer's provider connection, without secrets.
+ *
+ * This is the whole of what Oxy stores, and the whole of what the data plane
+ * is given.
+ * Resolving `secretRef` to credential material happens in the secret store, at
+ * use time, in the data plane — never in a database row, an API response, a
+ * Console screen or a log line.
+ */
+export declare const providerConnectionSchema: z.ZodEffects<z.ZodObject<{
+    /** See `version.ts`: exchanged with the data plane and rendered by Console. */
+    schemaVersion: z.ZodLiteral<1>;
+    connectionId: z.ZodString;
+    provider: z.ZodString;
+    /** The Oxy account that owns the connection and answers for its use. */
+    ownerAccountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    scope: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"account">;
+        accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    }, "strict", z.ZodTypeAny, {
+        kind: "account";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    }, {
+        kind: "account";
+        accountId: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"project">;
+        accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    }, "strict", z.ZodTypeAny, {
+        kind: "project";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    }, {
+        kind: "project";
+        accountId: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"application">;
+        accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+        applicationId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "application";
+        accountId: string & z.BRAND<"OxyAccountId">;
+        applicationId: string;
+    }, {
+        kind: "application";
+        accountId: string;
+        applicationId: string;
+    }>]>;
+    environment: z.ZodEnum<["development", "staging", "production"]>;
+    status: z.ZodEnum<["pending_validation", "active", "disabled", "revoked"]>;
+    secretRef: z.ZodString;
+    /**
+     * The leading characters of the credential, for recognition only. Capped at
+     * 12 — long enough to tell two keys apart, far too short to be one.
+     */
+    keyPrefix: z.ZodString;
+    /** SHA-256 of the credential, so rotation is verifiable without the key. */
+    fingerprint: z.ZodString;
+    validation: z.ZodObject<{
+        state: z.ZodEnum<["unvalidated", "valid", "invalid", "expired"]>;
+        lastValidatedAt: z.ZodOptional<z.ZodString>;
+        /** Required when `invalid`: a failure nobody can act on is not a result. */
+        failureCode: z.ZodOptional<z.ZodEnum<["unauthorized", "forbidden", "not_found", "rate_limited", "network", "unknown"]>>;
+    }, "strict", z.ZodTypeAny, {
+        state: "valid" | "invalid" | "expired" | "unvalidated";
+        lastValidatedAt?: string | undefined;
+        failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+    }, {
+        state: "valid" | "invalid" | "expired" | "unvalidated";
+        lastValidatedAt?: string | undefined;
+        failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+    }>;
+    /**
+     * Always `true` for a BYOK connection: the provider bills the customer's own
+     * upstream account, and Oxy charges only its platform fee. Stated as data so
+     * a receipt against this route is readable without a second lookup.
+     */
+    upstreamBillsCustomerDirectly: z.ZodLiteral<true>;
+    /** Set when the provider's terms require a per-customer acknowledgement. */
+    termsAcknowledgedAt: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    rotatedAt: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    environment: "development" | "staging" | "production";
+    validation: {
+        state: "valid" | "invalid" | "expired" | "unvalidated";
+        lastValidatedAt?: string | undefined;
+        failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+    };
+    status: "active" | "revoked" | "disabled" | "pending_validation";
+    scope: {
+        kind: "account";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    } | {
+        kind: "project";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    } | {
+        kind: "application";
+        accountId: string & z.BRAND<"OxyAccountId">;
+        applicationId: string;
+    };
+    createdAt: string;
+    provider: string;
+    schemaVersion: 1;
+    connectionId: string;
+    ownerAccountId: string & z.BRAND<"OxyAccountId">;
+    secretRef: string;
+    keyPrefix: string;
+    fingerprint: string;
+    upstreamBillsCustomerDirectly: true;
+    termsAcknowledgedAt?: string | undefined;
+    rotatedAt?: string | undefined;
+}, {
+    environment: "development" | "staging" | "production";
+    validation: {
+        state: "valid" | "invalid" | "expired" | "unvalidated";
+        lastValidatedAt?: string | undefined;
+        failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+    };
+    status: "active" | "revoked" | "disabled" | "pending_validation";
+    scope: {
+        kind: "account";
+        accountId: string;
+    } | {
+        kind: "project";
+        accountId: string;
+    } | {
+        kind: "application";
+        accountId: string;
+        applicationId: string;
+    };
+    createdAt: string;
+    provider: string;
+    schemaVersion: 1;
+    connectionId: string;
+    ownerAccountId: string;
+    secretRef: string;
+    keyPrefix: string;
+    fingerprint: string;
+    upstreamBillsCustomerDirectly: true;
+    termsAcknowledgedAt?: string | undefined;
+    rotatedAt?: string | undefined;
+}>, {
+    environment: "development" | "staging" | "production";
+    validation: {
+        state: "valid" | "invalid" | "expired" | "unvalidated";
+        lastValidatedAt?: string | undefined;
+        failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+    };
+    status: "active" | "revoked" | "disabled" | "pending_validation";
+    scope: {
+        kind: "account";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    } | {
+        kind: "project";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    } | {
+        kind: "application";
+        accountId: string & z.BRAND<"OxyAccountId">;
+        applicationId: string;
+    };
+    createdAt: string;
+    provider: string;
+    schemaVersion: 1;
+    connectionId: string;
+    ownerAccountId: string & z.BRAND<"OxyAccountId">;
+    secretRef: string;
+    keyPrefix: string;
+    fingerprint: string;
+    upstreamBillsCustomerDirectly: true;
+    termsAcknowledgedAt?: string | undefined;
+    rotatedAt?: string | undefined;
+}, {
+    environment: "development" | "staging" | "production";
+    validation: {
+        state: "valid" | "invalid" | "expired" | "unvalidated";
+        lastValidatedAt?: string | undefined;
+        failureCode?: "unknown" | "network" | "rate_limited" | "unauthorized" | "forbidden" | "not_found" | undefined;
+    };
+    status: "active" | "revoked" | "disabled" | "pending_validation";
+    scope: {
+        kind: "account";
+        accountId: string;
+    } | {
+        kind: "project";
+        accountId: string;
+    } | {
+        kind: "application";
+        accountId: string;
+        applicationId: string;
+    };
+    createdAt: string;
+    provider: string;
+    schemaVersion: 1;
+    connectionId: string;
+    ownerAccountId: string;
+    secretRef: string;
+    keyPrefix: string;
+    fingerprint: string;
+    upstreamBillsCustomerDirectly: true;
+    termsAcknowledgedAt?: string | undefined;
+    rotatedAt?: string | undefined;
+}>;
+export type ProviderConnectionScope = z.infer<typeof providerConnectionScopeSchema>;
+export type ProviderConnectionValidation = z.infer<typeof providerConnectionValidationSchema>;
+export type ProviderConnectionStatus = z.infer<typeof providerConnectionStatusSchema>;
+export type ProviderConnection = z.infer<typeof providerConnectionSchema>;