@oxy.so/core 1.0.0

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

@@ -0,0 +1,342 @@
+/**
+ * The Oxy inference client — one surface, two credential lanes (issue #972,
+ * workstream 15).
+ *
+ * ```typescript
+ * // An OpenAI-style machine key: one bearer string, no session, no exchange.
+ * const oxy = new OxyInferenceClient({ credential: process.env.OXY_API_KEY });
+ *
+ * // Oxy auth: whatever bearer the session or the service-token mint holds.
+ * const oxy = oxyServices.inference();
+ * ```
+ *
+ * Both lanes reach the SAME endpoints and are told apart only by how the bearer
+ * is produced: a machine key is a constant string, and an Oxy bearer rotates, so
+ * it is a function this client calls on every request rather than a value it
+ * captures once. There is no third lane, and no method behaves differently
+ * depending on which one you used.
+ *
+ * `respond()` returns one completed response. `stream()` reads the same
+ * `/v1/responses` endpoint without buffering and validates every SSE event
+ * against `inferenceStreamEventSchema` before exposing it to the caller.
+ *
+ * ## Why this is a client and not more methods on `OxyServices`
+ *
+ * Two reasons, both structural. A machine-key holder has no Oxy session at all,
+ * so a surface reached only through the session client would be unreachable for
+ * exactly the developer this workstream exists to serve. And the `/v1` error
+ * body is the contract's `InferenceError` at the top level rather than the
+ * platform's `{ error, message }` envelope — it carries `requestId`, `retryable`
+ * and `retryAfterMs`, all of which `OxyServices.handleError` would flatten into a
+ * message string. `oxyServices.inference()` binds the session bearer into this
+ * client so a session-holding app writes no plumbing of its own.
+ *
+ * ## Streaming is an explicit method
+ *
+ * `stream()` injects `stream: true` on the wire. The request type deliberately
+ * has no `stream` field, so `respond({ stream: true })` cannot promise a JSON
+ * response while the server sends SSE, and `stream({ stream: false })` cannot
+ * silently buffer. The method is the transport choice.
+ *
+ * ## Field names, and the one place they could drift
+ *
+ * Every VALUE type here comes from `@oxy.so/contracts` — messages, tools, tool
+ * choice, response format, usage quantities, unit prices, error codes. The
+ * request FIELD NAMES cannot: they belong to `responsesRequestSchema`, which
+ * lives in the API because it is a public dialect rather than an Oxy↔data-plane
+ * contract. `packages/api/src/schemas/__tests__/sdkRequestCompatibility.test.ts`
+ * is the gate — it parses a value of this module's request type against that
+ * schema, so a rename on either side fails a build rather than a customer's
+ * request.
+ */
+import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceRequestOutcome, InferenceStreamEvent, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxy.so/contracts';
+/** The base URL of the Oxy API, when a caller names none. */
+export declare const OXY_INFERENCE_BASE_URL = "https://api.oxy.so";
+/**
+ * How this client gets its bearer.
+ *
+ * A `string` is a static machine credential (`oxy_sk_…`) — presented verbatim,
+ * exactly as a stock OpenAI SDK would present it. A function is the Oxy auth
+ * lane and is called on EVERY request, because a session bearer and a service
+ * token both rotate and a captured one goes stale inside the hour.
+ */
+export type OxyInferenceCredential = string | (() => string | null | Promise<string | null>);
+/**
+ * The `fetch` this client calls.
+ *
+ * The global signature rather than a narrowed one, so any drop-in
+ * implementation — a test double, an instrumented wrapper, a Node agent — is
+ * assignable without a cast at either end.
+ */
+export type OxyInferenceFetch = typeof fetch;
+export interface OxyInferenceClientOptions {
+    readonly credential: OxyInferenceCredential;
+    /** Defaults to {@link OXY_INFERENCE_BASE_URL}. A trailing slash is trimmed. */
+    readonly baseURL?: string;
+    /** Defaults to the global `fetch`. */
+    readonly fetch?: OxyInferenceFetch;
+}
+/**
+ * A request to `POST /v1/responses`.
+ *
+ * `model`, `routingProfile`, and `routingProfileId` are mutually exclusive and
+ * all are optional: an
+ * application whose routing policy carries a `defaultTarget` may name neither,
+ * which is what "per-application default model or routing profile" means. Naming
+ * both is refused by the edge with `invalid_request`.
+ */
+export interface OxyResponsesRequest {
+    /** `<publisher>/<model>` or `<publisher>/<model>@<revision>`. */
+    readonly model?: string;
+    /** A routing profile slug. Never contains a slash, so it is never a model id. */
+    readonly routingProfile?: string;
+    /** An exact opaque routing-profile database ID; serialized byte-for-byte. */
+    readonly routingProfileId?: string;
+    /** A prompt, or the message list it is shorthand for. */
+    readonly input: string | readonly InferenceMessage[];
+    readonly maxOutputTokens?: number;
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly topK?: number;
+    readonly frequencyPenalty?: number;
+    readonly presencePenalty?: number;
+    readonly seed?: number;
+    readonly stopSequences?: readonly string[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly toolChoice?: ToolChoice;
+    readonly responseFormat?: ResponseFormat;
+    /** Cost-attribution tags, echoed back on the receipt. At most 16. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Your own correlation id, echoed on the response. */
+    readonly clientRequestId?: string;
+}
+export interface OxyInferenceRequestOptions {
+    /**
+     * Abort the request. The edge treats a client disconnect as a cancellation:
+     * it settles what was produced and refunds the rest, so a cancelled request
+     * is a normal terminal state rather than an error to clean up after.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * `Idempotency-Key`. A key already bound to a reservation is REFUSED with
+     * `idempotency_conflict` rather than replayed — responses are not retained,
+     * so there is nothing to replay, and refusing is what makes "a retry never
+     * produces a second charge" structural. At most 128 characters.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * `X-Oxy-User-Id` — the end user this request is made on behalf of.
+     * ATTRIBUTION ONLY: it never changes which account is charged.
+     */
+    readonly delegatedUserId?: string;
+}
+/** The body of a successful `POST /v1/responses`. */
+export interface OxyInferenceResponse {
+    readonly schemaVersion: 1;
+    /** Also on `X-Oxy-Request-Id`, on success and on every refusal. */
+    readonly requestId: string;
+    readonly generationId?: string;
+    /** Always revision-pinned, even when you named only the model line. */
+    readonly model: string;
+    readonly servingProvider: string;
+    readonly finishReason: InferenceFinishReason;
+    readonly output: readonly InferenceMessage[];
+    /** Metered quantities. Never money — the charge is on the receipt. */
+    readonly usage: readonly UsageQuantity[];
+    /** The exact policy version this request was admitted under. */
+    readonly routingPolicy: RoutingPolicyReference;
+    /**
+     * How long Oxy took over this request, in whole milliseconds — also on
+     * `X-Oxy-Latency-Ms`.
+     *
+     * Measured from the moment the edge received the request through
+     * authentication, admission, routing, the reservation, the call to the
+     * inference data plane and the settlement of the hold. Most of it is the
+     * upstream generating tokens; it does not separate the two.
+     *
+     * It is NOT the round trip you can measure yourself, which additionally
+     * covers DNS, TLS, both network legs and your own parse. Report them side by
+     * side rather than picking one — this figure has no network in it and yours
+     * cannot be attributed to the model.
+     *
+     * Optional because it is additive: an Oxy deployment older than the field
+     * omits it, and a streamed request never carries it (the head is written
+     * before the first frame arrives, so the number does not exist yet).
+     */
+    readonly latencyMs?: number;
+}
+/**
+ * A settled receipt, as `GET /v1/generations/:id` returns it.
+ *
+ * Carries the price SNAPSHOT rather than a reference to a price version, so the
+ * arithmetic stays checkable after that version has been superseded.
+ */
+export interface OxyGenerationReceipt {
+    readonly schemaVersion: 1;
+    readonly receiptId: string;
+    readonly requestId: string;
+    readonly generationId?: string;
+    readonly applicationId: string;
+    readonly credentialId: string;
+    /** Attribution only. Never the billing identity. */
+    readonly delegatedUserId?: string;
+    readonly environment: InferenceEnvironment;
+    readonly outcome: InferenceRequestOutcome;
+    readonly usageSource: UsageSource;
+    /** EVERY unit, including the zeros — see `usageSource` for what a zero means. */
+    readonly units: readonly UsageQuantity[];
+    readonly resolvedModelReference: string;
+    readonly servingProvider: string;
+    readonly priceSnapshot: {
+        readonly priceVersionId: string;
+        readonly currency: CurrencyCode;
+        readonly unitPrices: readonly UnitPrice[];
+    };
+    readonly billedAmount: ExactDecimal;
+    readonly currency: CurrencyCode;
+    /** A BYOK route: `billedAmount` is Oxy's fee, not the cost of the tokens. */
+    readonly platformFeeOnly: boolean;
+    readonly settledAt: string;
+}
+/**
+ * Anything the inference API refused.
+ *
+ * `retryable` is asserted by the server and looked up from a total map over the
+ * closed code set — never inferred here from the status. A client that decides
+ * retryability from an HTTP status is exactly what the contract's retryability
+ * rule exists to prevent, so this class carries the server's answer and does not
+ * compute one.
+ */
+export declare class OxyInferenceError extends Error {
+    readonly code: InferenceErrorCode;
+    readonly retryable: boolean;
+    readonly requestId: string;
+    readonly status: number;
+    /** How long to wait. Only ever present when `retryable`. */
+    readonly retryAfterMs?: number;
+    /** The request field at fault, for `invalid_request`. */
+    readonly param?: string;
+    constructor(input: {
+        code: InferenceErrorCode;
+        message: string;
+        retryable: boolean;
+        requestId: string;
+        status: number;
+        retryAfterMs?: number;
+        param?: string;
+    });
+}
+/**
+ * The edge opened an SSE response but its framing or one of its events violated
+ * the published inference stream contract.
+ *
+ * This is distinct from {@link OxyInferenceError}: the latter is a refusal the
+ * server deliberately returned, while this error means the client could not
+ * safely interpret a nominally successful stream.
+ */
+export declare class OxyInferenceProtocolError extends Error {
+    /** The request id from the response header, when the edge supplied one. */
+    readonly requestId?: string;
+    constructor(message: string, requestId?: string);
+}
+/**
+ * The Oxy inference API.
+ *
+ * Stateless: it holds a base URL, a way to get a bearer and a `fetch`. Nothing
+ * is cached, because the two things worth caching here are a catalogue that is
+ * audience-scoped and a receipt that is immutable but rarely re-read.
+ *
+ * Completed JSON responses are TYPED, not re-parsed. The server validates every
+ * one against its own schema before serving it, and a second client-side parse
+ * of a non-strict shape would silently DROP fields a newer API added — turning
+ * forward compatibility into data loss. Stream events are different: each is a
+ * versioned wire message and is parsed against the shared contract before it is
+ * yielded. Refusals are read defensively, because two routers answer under `/v1`
+ * and an unreadable failure must still reach the caller as one.
+ */
+export declare class OxyInferenceClient {
+    #private;
+    constructor(options: OxyInferenceClientOptions);
+    /**
+     * The models this caller may use — `GET /v1/models`.
+     *
+     * Audience-scoped server-side. A machine credential and an anonymous caller
+     * both see the PUBLIC catalogue; only an internal/system application's
+     * service token sees internal-only routes.
+     *
+     * **`[]` is a normal answer**, and is the only answer today: the catalogue
+     * is populated by operators, and a route is not publicly exposed until
+     * somebody has reviewed the right to resell it.
+     */
+    listModels(options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelCatalogueEntry[]>;
+    /**
+     * One catalogue entry by its canonical id — `GET /v1/models/:publisher/:model`.
+     *
+     * The id is TWO path segments, because a canonical model id contains a slash
+     * and a single encoded segment would never match the route.
+     *
+     * A model you may not see answers 404 identically to one that does not
+     * exist, deliberately: the catalogue is never an existence oracle for what
+     * Oxy runs internally.
+     *
+     * @param modelId - `<publisher>/<model>`. A revision pin
+     *   (`<publisher>/<model>@<revision>`) names a model REFERENCE rather than a
+     *   model and is rejected here rather than sent, because the catalogue is
+     *   keyed on models and a pinned reference would 404 indistinguishably from
+     *   "no such model".
+     */
+    getModel(modelId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelCatalogueEntry>;
+    /**
+     * The routing profiles this caller may select — `GET /v1/models/routing-profiles`.
+     *
+     * A profile is a named strategy for CHOOSING among routes, not a model: no
+     * publisher, no revision, no licence, no weights. Like the model list, `[]`
+     * is a normal answer.
+     */
+    listRoutingProfiles(options?: {
+        signal?: AbortSignal;
+    }): Promise<RoutingProfile[]>;
+    /**
+     * Send one non-streaming inference request — `POST /v1/responses`.
+     *
+     * @throws {OxyInferenceError} for every refusal, carrying the server's own
+     *   `code`, `retryable` and `requestId`.
+     */
+    respond(request: OxyResponsesRequest, options?: OxyInferenceRequestOptions): Promise<OxyInferenceResponse>;
+    /**
+     * Stream one inference request from `POST /v1/responses`.
+     *
+     * The transport choice is method-level: this method adds `stream: true` and
+     * requests SSE, while {@link respond} never does. Every yielded value has
+     * already passed `inferenceStreamEventSchema`, belongs to the request id in
+     * the response header and advances the stream sequence. A terminal `error`
+     * event is yielded as part of the published union; an HTTP refusal before
+     * the stream opens throws {@link OxyInferenceError}.
+     *
+     * Breaking out of the iterator cancels the response body. Passing an abort
+     * signal additionally lets the caller cancel while waiting for the first or
+     * any later event.
+     *
+     * @throws {OxyInferenceError} when the edge refuses before opening SSE.
+     * @throws {OxyInferenceProtocolError} when a successful SSE response cannot
+     *   be interpreted under the published stream contract.
+     */
+    stream(request: OxyResponsesRequest, options?: OxyInferenceRequestOptions): AsyncGenerator<InferenceStreamEvent>;
+    /**
+     * Read back the settled receipt for one request —
+     * `GET /v1/generations/:id`.
+     *
+     * `id` is the `requestId` you already hold (it is on every response and
+     * every error) or the `generationId`. Requires the `inference:usage:read`
+     * scope; a caller without it, or one whose application did not make the
+     * request, is told the receipt does not exist rather than that it belongs to
+     * somebody else.
+     */
+    getGeneration(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<OxyGenerationReceipt>;
+}

package/dist/types/logger/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @oxy.so/core/logger — the ecosystem-wide logging chokepoint.
+ *
+ * A tiny, dependency-free, universal logger that works unchanged in React
+ * Native, browsers, Node, and Bun. Every Oxy app and package should log
+ * through here instead of calling `console.*` directly, so that level,
+ * formatting, and transport are controlled in ONE place.
+ *
+ * Design goals:
+ *  - Zero dependencies. No Node-only imports, no `process.stdout` assumptions.
+ *  - Four levels (`debug` | `info` | `warn` | `error`) plus `silent`.
+ *  - Namespaced child loggers via `createLogger('mention:feed')` / `.child()`.
+ *  - Structured context objects carried through to the sink.
+ *  - A single pluggable sink so backends can pipe to pino / CloudWatch / etc.
+ *    without touching any call site.
+ *  - Debug is off in production by default (`__DEV__` on RN, `NODE_ENV`
+ *    elsewhere); override globally with `configureLogger({ level })`.
+ *
+ * @module logger
+ */
+/** Ordered severity levels. `silent` disables all output. */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/** The levels that actually emit an entry (everything but `silent`). */
+export type EmittableLogLevel = Exclude<LogLevel, 'silent'>;
+/**
+ * Structured, JSON-friendly context attached to a log line. The well-known
+ * keys are optional hints; arbitrary keys are allowed so callers can attach
+ * whatever structured fields their sink cares about.
+ */
+export interface LogContext {
+    component?: string;
+    method?: string;
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    [key: string]: unknown;
+}
+/** A single normalized log record handed to the active sink. */
+export interface LogEntry {
+    level: EmittableLogLevel;
+    message: string;
+    /** Colon-joined namespace, e.g. `mention:feed`. Absent for the root logger. */
+    namespace?: string;
+    /** Merged structured context (logger base context + per-call context). */
+    context?: LogContext;
+    /** The error value passed to `.error(message, error, …)`, if any. */
+    error?: unknown;
+    /** Extra variadic args passed after the context. */
+    args: unknown[];
+    /** ISO-8601 timestamp of when the entry was created. */
+    timestamp: string;
+}
+/** A transport that receives every emitted (level-passing) entry. */
+export type LogSink = (entry: LogEntry) => void;
+/** Global logger configuration. */
+export interface LoggerConfig {
+    level: LogLevel;
+    sink: LogSink;
+}
+/** A namespaced logger. Instances are cheap; derive children with `.child()`. */
+export interface Logger {
+    /** The logger's colon-joined namespace, if any. */
+    readonly namespace?: string;
+    debug(message: string, context?: LogContext, ...args: unknown[]): void;
+    info(message: string, context?: LogContext, ...args: unknown[]): void;
+    warn(message: string, context?: LogContext, ...args: unknown[]): void;
+    error(message: string, error?: unknown, context?: LogContext, ...args: unknown[]): void;
+    /** Derive a child logger with an extended namespace and merged base context. */
+    child(namespace: string, context?: LogContext): Logger;
+}
+/**
+ * True in development. Uses React Native's `__DEV__` when present, otherwise
+ * falls back to `process.env.NODE_ENV === 'development'`. Never throws.
+ */
+export declare function isDev(): boolean;
+/**
+ * Default sink: routes each entry to the matching `console` method. `info` and
+ * `debug` go to `console.log` (RN/browser-safe — `console.debug`/`console.info`
+ * are inconsistently surfaced across runtimes).
+ */
+export declare const consoleSink: LogSink;
+/**
+ * Update the global logger configuration. Affects every logger instance
+ * (root and children) immediately. Pass `{ level }` to gate output and/or
+ * `{ sink }` to redirect transport (pino, CloudWatch, a test capture, …).
+ */
+export declare function configureLogger(partial: Partial<LoggerConfig>): void;
+/** Read a snapshot of the current global configuration. */
+export declare function getLoggerConfig(): Readonly<LoggerConfig>;
+/** Restore the default level (env-derived) and the console sink. */
+export declare function resetLoggerConfig(): void;
+/** The shared root logger. Prefer a namespaced `createLogger(...)` in modules. */
+export declare const logger: Logger;
+/**
+ * Create a namespaced logger.
+ *
+ * @example
+ * ```ts
+ * const log = createLogger('mention:feed');
+ * log.info('loaded', { count: 20 });
+ * const sub = log.child('prefetch'); // namespace → 'mention:feed:prefetch'
+ * ```
+ */
+export declare function createLogger(namespace?: string, context?: LogContext): Logger;