@oxyhq/contracts 0.26.0 → 0.27.0

package/dist/types/accountGraph.d.ts

@@ -12,8 +12,8 @@ import { z } from 'zod';
  *
  * `personal` is the only kind minted by signup and the only one that carries
  * its own credentials; every other kind is a child account created under a
- * parent and operated through `account_members`. The API schema, the Mongoose
- * model and the SDK all derive from this list rather than restating it, so a
+ * parent and operated through `account_members`. The API schema, the Drizzle
+ * table and the SDK all derive from this list rather than restating it, so a
  * new kind is one edit here instead of four literals that can drift.
  */
 export type AccountKind = 'personal' | 'organization' | 'project' | 'bot' | 'channel';
@@ -24,9 +24,10 @@ export type AccountKind = 'personal' | 'organization' | 'project' | 'bot' | 'cha
  * `db/schema/users.ts` mirrors to keep the `users_kind_check` CHECK honest.
  *
  * Deriving the union from the array instead would cost nothing here and be paid
- * by consumers: `kind` travels into `@oxyhq/services` through
- * `SwitchableAccount`, where an indexed-access type is materially more
- * expensive to check than a literal union.
+ * by consumers: `kind` travels into `@oxyhq/services` on every device-directory
+ * context (`deviceContextSchema.kind` → `DeviceContext` → the switcher rows),
+ * and an indexed-access type is materially more expensive to check there than a
+ * literal union.
  */
 export declare const ACCOUNT_KINDS: readonly ["personal", "organization", "project", "bot", "channel"];
 /** `never` while `ACCOUNT_KINDS` covers the union. */

package/dist/types/index.d.ts

@@ -60,3 +60,26 @@ export { devicePairingStatusSchema, deviceTransferInitRequestSchema, deviceTrans
 export type { DevicePairingStatus, DeviceTransferInitRequest, DeviceTransferInitResponse, DeviceTransferInfoResponse, DeviceTransferApproveRequest, DeviceTransferApproveResponse, DeviceTransferDenyResponse, } from './devicePairing';
 export { transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency';
 export type { TransparencyCheckpointSignature, TransparencyAnchor, TransparencyCheckpoint, TransparencyInclusionProof, TransparencyCheckpointList, } from './transparency';
+export { INFERENCE_CONTRACT_VERSION, } from './inference/version';
+export { oxyAccountIdSchema, delegatedUserIdSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, generationIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers';
+export type { OxyAccountId, DelegatedUserId, InferenceEnvironment, ModelReference, ModelId, } from './inference/identifiers';
+export { currencyCodeSchema, INFERENCE_MONEY_SCALE, exactDecimalSchema, moneySchema, USAGE_UNITS, usageUnitSchema, USAGE_SOURCES, usageSourceSchema, usageQuantitySchema, unitPriceSchema, } from './inference/money';
+export type { CurrencyCode, ExactDecimal, Money, UsageUnit, UsageSource, UsageQuantity, UnitPrice, } from './inference/money';
+export { INFERENCE_SCOPES, inferenceScopeSchema, billingPrincipalSchema, authenticatedPrincipalSchema, inferenceAttributionSchema, } from './inference/attribution';
+export type { InferenceScope, BillingPrincipal, AuthenticatedPrincipal, InferenceAttribution, } from './inference/attribution';
+export { INFERENCE_ERROR_CODES, NON_RETRYABLE_INFERENCE_ERROR_CODES, inferenceErrorCodeSchema, upstreamErrorCategorySchema, safeErrorTextSchema, providerErrorPassthroughSchema, inferenceErrorSchema, } from './inference/errors';
+export type { InferenceErrorCode, UpstreamErrorCategory, ProviderErrorPassthrough, InferenceError, } from './inference/errors';
+export { priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion';
+export type { PriceVersionStatus, PriceVersion, PriceSnapshot, } from './inference/priceVersion';
+export { inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue';
+export type { InferenceModality, ModelCapabilities, ModelLicense, ModelProvenance, InferenceDataPolicy, AvailabilityScope, CommercialPermission, ModelDeprecation, ModelEvaluationResult, ModelSafetyMetadata, ModelPublisher, CatalogueModel, ModelRevision, InferenceProvider, ModelDeployment, RoutingProfileCandidate, RoutingProfile, CataloguePublisherSummary, CatalogueServingProviderSummary, ModelCatalogueEntry, } from './inference/catalogue';
+export { routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, } from './inference/routingPolicy';
+export type { RoutingTarget, RoutingPolicyScope, RoutingFallbackPolicy, RoutingPolicy, RoutingPolicyReference, } from './inference/routingPolicy';
+export { inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, } from './inference/request';
+export type { InferenceContentSource, InferenceContentPart, InferenceToolCall, InferenceMessageRole, InferenceMessage, InferenceInput, SamplingParameters, ToolDefinition, ToolChoice, ResponseFormat, ClientRequestMetadata, InferenceRequest, } from './inference/request';
+export { inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents';
+export type { InferenceStreamStartEvent, InferenceStreamDeltaEvent, InferenceStreamToolCallEvent, InferenceStreamUsageEvent, InferenceRouteSwitchDetail, InferenceRouteSwitchReason, InferenceStreamRouteSwitchEvent, InferenceStreamErrorEvent, InferenceFinishReason, InferenceStreamDoneEvent, InferenceStreamEvent, } from './inference/streamEvents';
+export { usageReservationRequestSchema, usageReservationStatusSchema, usageReservationSchema, inferenceRequestOutcomeSchema, normalizedUsageReportSchema, usageReceiptSchema, usageRefundSubjectSchema, usageRefundReasonSchema, usageRefundSchema, } from './inference/usage';
+export type { UsageReservationRequest, UsageReservationStatus, UsageReservation, InferenceRequestOutcome, NormalizedUsageReport, UsageReceipt, UsageRefundSubject, UsageRefundReason, UsageRefund, } from './inference/usage';
+export { providerConnectionScopeSchema, providerSecretReferenceSchema, providerConnectionValidationSchema, providerConnectionStatusSchema, providerConnectionSchema, } from './inference/providerConnection';
+export type { ProviderConnectionScope, ProviderConnectionValidation, ProviderConnectionStatus, ProviderConnection, } from './inference/providerConnection';

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

@@ -0,0 +1,171 @@
+/**
+ * Canonical attribution for an inference request.
+ *
+ * Every accepted request resolves to an Oxy account, an Oxy application, the
+ * Oxy credential that authenticated it, an optional delegated end user, and the
+ * ids that correlate it across the edge, the data plane and the ledger. The
+ * data plane may store these as immutable references; it never owns or mutates
+ * them, and it never mints a customer identity of its own.
+ *
+ * The rule this file encodes structurally, rather than restating in prose:
+ * **the delegated `userId` can never be the billing identity.** Two independent
+ * mechanisms enforce it, one at compile time and one at parse time, because a
+ * delegated identity being charged for somebody else's workload is the kind of
+ * mistake that produces a correct-looking invoice for the wrong customer:
+ *
+ *  1. `accountId` and `userId` carry DIFFERENT brands, so neither is assignable
+ *     to the other in any consumer without a cast.
+ *  2. {@link billingPrincipalSchema} is `.strict()` and holds exactly one field,
+ *     so a payload that smuggles `userId` into the billing block is rejected at
+ *     the parse rather than stripped and forgotten.
+ *
+ * These shapes are EMBEDDED — they ride inside a request envelope, a receipt or
+ * a ledger record and inherit its `schemaVersion`. Versioning them separately
+ * would let one message claim two versions.
+ *
+ * Decided in: docs/adr/0007-canonical-request-attribution.md.
+ */
+import { z } from 'zod';
+/**
+ * The inference capability scopes the data plane needs to know about.
+ *
+ * A credential may carry many other Oxy scopes; only these cross the boundary,
+ * because the data plane's authorization questions are exactly "may this caller
+ * invoke", "may it read the catalogue", "may it read usage", "may it read or
+ * write routing", "may it read or write provider connections". Everything else
+ * is the control plane's business and is not the data plane's to hold.
+ */
+export declare const INFERENCE_SCOPES: readonly ["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"];
+export declare const inferenceScopeSchema: z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>;
+/**
+ * The financially responsible principal, and the ONLY identity a charge may be
+ * booked against.
+ *
+ * It is its own type — not a field on a larger principal object — precisely so
+ * that a function taking "who pays" cannot be handed a user, a session, a
+ * device or an application. It cannot be constructed from a delegated user id:
+ * the brands differ, and this object accepts no other key.
+ */
+export declare const billingPrincipalSchema: z.ZodObject<{
+    accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+}, "strict", z.ZodTypeAny, {
+    accountId: string & z.BRAND<"OxyAccountId">;
+}, {
+    accountId: string;
+}>;
+/**
+ * Who authenticated, as resolved by the Oxy edge before a request is forwarded.
+ *
+ * Mirrors what a verified Oxy service token carries (`appId`, `credentialId`,
+ * `ownerAccountId`, `environment`, effective scopes) so that the two
+ * authentication paths — a machine API key and a first-party service token —
+ * produce one shape downstream. The data plane authorizes against this
+ * envelope; it does not re-derive access from its own database, because it has
+ * no account graph to re-derive it from.
+ */
+export declare const authenticatedPrincipalSchema: z.ZodObject<{
+    billing: z.ZodObject<{
+        accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    }, "strict", z.ZodTypeAny, {
+        accountId: string & z.BRAND<"OxyAccountId">;
+    }, {
+        accountId: string;
+    }>;
+    applicationId: z.ZodString;
+    credentialId: z.ZodString;
+    environment: z.ZodEnum<["development", "staging", "production"]>;
+    inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    environment: "development" | "staging" | "production";
+    credentialId: string;
+    applicationId: string;
+    billing: {
+        accountId: string & z.BRAND<"OxyAccountId">;
+    };
+    inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+}, {
+    environment: "development" | "staging" | "production";
+    credentialId: string;
+    applicationId: string;
+    billing: {
+        accountId: string;
+    };
+    inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+}>;
+/**
+ * The attribution block carried by every request, receipt and ledger record.
+ *
+ * `userId` is the OPTIONAL delegated end user — Alia's `X-Oxy-User-Id`. It is
+ * attribution only: it never changes which account is charged, never grants
+ * access, and lives outside {@link billingPrincipalSchema} so that no code path
+ * can read it as the payer.
+ *
+ * `requestId` is generated by the data plane and always present; `generationId`
+ * is present
+ * once a generation exists, which is why it is optional on a request and
+ * expected on a receipt.
+ */
+export declare const inferenceAttributionSchema: z.ZodObject<{
+    principal: z.ZodObject<{
+        billing: z.ZodObject<{
+            accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+        }, "strict", z.ZodTypeAny, {
+            accountId: string & z.BRAND<"OxyAccountId">;
+        }, {
+            accountId: string;
+        }>;
+        applicationId: z.ZodString;
+        credentialId: z.ZodString;
+        environment: z.ZodEnum<["development", "staging", "production"]>;
+        inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string & z.BRAND<"OxyAccountId">;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    }, {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    }>;
+    userId: z.ZodOptional<z.ZodBranded<z.ZodString, "DelegatedUserId">>;
+    requestId: z.ZodString;
+    generationId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requestId: string;
+    principal: {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string & z.BRAND<"OxyAccountId">;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    };
+    userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+    generationId?: string | undefined;
+}, {
+    requestId: string;
+    principal: {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    };
+    userId?: string | undefined;
+    generationId?: string | undefined;
+}>;
+export type InferenceScope = z.infer<typeof inferenceScopeSchema>;
+export type BillingPrincipal = z.infer<typeof billingPrincipalSchema>;
+export type AuthenticatedPrincipal = z.infer<typeof authenticatedPrincipalSchema>;
+export type InferenceAttribution = z.infer<typeof inferenceAttributionSchema>;