@oxy.so/contracts 4.2.0 → 4.4.0

package/dist/cjs/inference/request.js

@@ -25,7 +25,7 @@
  * docs/adr/0017-authorized-routes-in-the-envelope.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.inferenceRequestSchema = exports.inferenceSpeechParametersSchema = exports.clientRequestMetadataSchema = exports.inferenceReasoningSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = void 0;
+exports.inferenceRequestSchema = exports.inferenceAudioOutputParametersSchema = exports.inferenceSpeechParametersSchema = exports.clientRequestMetadataSchema = exports.inferenceReasoningSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = void 0;
 const zod_1 = require("zod");
 const attribution_1 = require("./attribution");
 const catalogue_1 = require("./catalogue");
@@ -292,16 +292,7 @@ exports.inferenceReasoningSchema = zod_1.z
 exports.clientRequestMetadataSchema = zod_1.z
     .object({
     /** The public dialect the customer called. The response is rendered in it. */
-    apiFormat: zod_1.z.enum([
-        "responses",
-        "chat_completions",
-        "embeddings",
-        "images_generations",
-        "audio_transcriptions",
-        "audio_speech",
-        "rerank",
-        "batches",
-    ]),
+    apiFormat: catalogue_1.inferenceApiFormatSchema,
     /** The public path, e.g. `/v1/responses`. */
     endpoint: zod_1.z.string().min(1).max(256),
     /** The customer's own correlation id, when they sent one. */
@@ -330,6 +321,25 @@ exports.inferenceSpeechParametersSchema = zod_1.z.object({
     responseFormat: zod_1.z.enum(["mp3", "opus", "aac", "flac", "wav", "pcm"]),
     speed: zod_1.z.number().min(0.25).max(4).optional(),
 }).strict();
+/**
+ * Spoken output from a CONVERSATIONAL model (contract set 3.2.0) — an audio chat
+ * model answering in its own voice, as opposed to `speech`, which reads given
+ * text aloud. Presence is the request: a chat request carrying this asks for
+ * the answer as audio AND its transcript, which is the only combination the
+ * audio chat models produce (OpenAI's `modalities: ["text", "audio"]`).
+ *
+ * The audio streams as `audio` events and the words as `delta` events on the
+ * `output_audio_transcript` channel — never as `output_text`, because a
+ * transcript of speech the customer is already hearing is not a second answer.
+ * `pcm` is the only format an audio chat model can STREAM; the refinement on the
+ * envelope holds that rather than leaving a provider to refuse it mid-flight.
+ */
+exports.inferenceAudioOutputParametersSchema = zod_1.z
+    .object({
+    voice: zod_1.z.string().min(1).max(64),
+    format: zod_1.z.enum(["wav", "mp3", "flac", "opus", "pcm"]),
+})
+    .strict();
 /**
  * The canonical internal request Oxy forwards to the data plane.
  *
@@ -352,6 +362,8 @@ exports.inferenceRequestSchema = zod_1.z
     /** Absent means the route's own default reasoning behaviour. */
     reasoning: exports.inferenceReasoningSchema.optional(),
     speech: exports.inferenceSpeechParametersSchema.optional(),
+    /** Spoken output from a conversational model. Contract set 3.2.0. */
+    audioOutput: exports.inferenceAudioOutputParametersSchema.optional(),
     tools: zod_1.z.array(exports.toolDefinitionSchema).default([]),
     toolChoice: exports.toolChoiceSchema.optional(),
     responseFormat: exports.responseFormatSchema.optional(),
@@ -401,6 +413,17 @@ exports.inferenceRequestSchema = zod_1.z
     if (!isSpeech && request.speech !== undefined) {
         ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["speech"], message: "speech parameters require the audio_speech API format" });
     }
+    if (request.audioOutput !== undefined) {
+        if (request.client.apiFormat !== "chat_completions") {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["audioOutput"], message: "spoken output from a conversational model requires the chat_completions API format" });
+        }
+        if (request.modality !== "audio" || request.input.format !== "messages") {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["audioOutput"], message: "spoken output requires audio modality and a messages input" });
+        }
+        if (request.stream && request.audioOutput.format !== "pcm") {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["audioOutput", "format"], message: "streamed spoken output is pcm; the other formats exist only whole" });
+        }
+    }
     if (request.toolChoice !== undefined && request.tools.length === 0) {
         ctx.addIssue({
             code: zod_1.z.ZodIssueCode.custom,

package/dist/cjs/inference/streamEvents.js

@@ -62,7 +62,13 @@ exports.inferenceStreamDeltaEventSchema = zod_1.z.object({
     sequence: zod_1.z.number().int().nonnegative().safe(),
     /** Which output of a multi-output response this chunk belongs to. */
     outputIndex: zod_1.z.number().int().nonnegative().safe(),
-    channel: zod_1.z.enum(['output_text', 'reasoning', 'refusal']),
+    /**
+     * `output_audio_transcript` (contract set 3.2.0) carries the words of spoken
+     * output requested with `audioOutput`. It is its own channel for the same
+     * reason `reasoning` is: a renderer that shows it as `output_text` presents
+     * the transcript of what the customer is hearing as a second, written answer.
+     */
+    channel: zod_1.z.enum(['output_text', 'reasoning', 'refusal', 'output_audio_transcript']),
     text: zod_1.z.string(),
 });
 /** The encodings an audio output may carry. */

package/dist/cjs/inference/version.js

@@ -102,4 +102,4 @@ exports.INFERENCE_CONTRACT_VERSION = void 0;
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-exports.INFERENCE_CONTRACT_VERSION = '3.1.0';
+exports.INFERENCE_CONTRACT_VERSION = '3.2.0';

package/dist/cjs/stickers.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Stickers — the wire shape of Oxy's shared sticker catalogue.
+ *
+ * One catalogue serves every app: Allo sends a sticker in a chat, Mention draws
+ * one in an empty state, and both resolve the same id to the same animation.
+ * The API validates its output against these schemas and `@oxy.so/stickers`
+ * validates its input against the same ones.
+ *
+ * A sticker is a Lottie animation plus a static fallback image, both served
+ * from Oxy's CDN at content-addressed, immutable URLs. The fallback is what a
+ * surface that cannot animate shows — a push notification, a federated copy of
+ * a post, a person who asked for reduced motion.
+ *
+ * Platform-agnostic — zod only. ESM-safe (no `require()`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateStickerPackRequestSchema = exports.createStickerPackRequestSchema = exports.reorderStickerPacksRequestSchema = exports.resolveStickersResponseSchema = exports.resolveStickersRequestSchema = exports.stickerRefSchema = exports.installedStickerPackSchema = exports.stickerPackSchema = exports.stickerPackSummarySchema = exports.stickerSchema = exports.stickerFileSchema = exports.stickerPackStatusSchema = exports.stickerIdSchema = exports.stickerPackSlugSchema = exports.stickerSha256Schema = exports.STICKER_RESOLVE_MAX_IDS = exports.STICKER_MAX_INSTALLED_PACKS = exports.STICKER_PACK_MAX_STICKERS = exports.STICKER_MAX_FALLBACK_BYTES = exports.STICKER_MAX_ANIMATION_BYTES = exports.STICKER_MAX_UPLOAD_BYTES = exports.STICKER_MAX_FRAME_RATE = exports.STICKER_MAX_DURATION_MS = exports.STICKER_FALLBACK_SIZE = exports.STICKER_CANVAS_SIZES = void 0;
+const zod_1 = require("zod");
+/* -------------------------------------------------------------------------- */
+/*  Limits                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * The square canvases a sticker may be authored at. Lottie is vectors, so the
+ * canvas is a coordinate space rather than a resolution: a 1024 file draws as
+ * sharply in a 128-point bubble as a 512 one.
+ */
+exports.STICKER_CANVAS_SIZES = [512, 1024];
+/** Size of the static fallback image every sticker gets. */
+exports.STICKER_FALLBACK_SIZE = 512;
+/** Longest loop a sticker may have. */
+exports.STICKER_MAX_DURATION_MS = 10000;
+/** Highest frame rate a sticker may declare. */
+exports.STICKER_MAX_FRAME_RATE = 60;
+/**
+ * Largest Lottie JSON accepted on upload, before the API normalizes it.
+ * Exported animations carry pretty-printing and full float precision, so the
+ * raw file is routinely many times the size of what is stored.
+ */
+exports.STICKER_MAX_UPLOAD_BYTES = 8 * 1024 * 1024;
+/**
+ * Largest animation STORED, after normalization (minified, floats rounded,
+ * expressions removed). The CDN compresses JSON in transit, which takes a
+ * typical sticker to a few tens of kilobytes on the wire.
+ */
+exports.STICKER_MAX_ANIMATION_BYTES = 1024 * 1024;
+/** Largest static fallback accepted on upload, when one is supplied. */
+exports.STICKER_MAX_FALLBACK_BYTES = 256 * 1024;
+/** How many stickers one pack may hold. */
+exports.STICKER_PACK_MAX_STICKERS = 120;
+/** How many packs one person may have installed. */
+exports.STICKER_MAX_INSTALLED_PACKS = 200;
+/** How many ids one resolve call may ask about. */
+exports.STICKER_RESOLVE_MAX_IDS = 100;
+/* -------------------------------------------------------------------------- */
+/*  Primitives                                                                */
+/* -------------------------------------------------------------------------- */
+/** Lowercase-hex SHA-256 of a file's bytes. */
+exports.stickerSha256Schema = zod_1.z
+    .string()
+    .regex(/^[a-f0-9]{64}$/, 'sha256 must be 64 lowercase hex characters');
+/** A pack's public URL segment. */
+exports.stickerPackSlugSchema = zod_1.z
+    .string()
+    .min(2)
+    .max(64)
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'slug must be lowercase words joined by hyphens');
+exports.stickerIdSchema = zod_1.z.string().min(1).max(64);
+exports.stickerPackStatusSchema = zod_1.z.enum(['draft', 'published', 'archived']);
+/** One stored file: where to fetch it and the hash its bytes must have. */
+exports.stickerFileSchema = zod_1.z.object({
+    url: zod_1.z.string().url(),
+    sha256: exports.stickerSha256Schema,
+    mime: zod_1.z.string(),
+    bytes: zod_1.z.number().int().nonnegative(),
+});
+/* -------------------------------------------------------------------------- */
+/*  Catalogue                                                                 */
+/* -------------------------------------------------------------------------- */
+exports.stickerSchema = zod_1.z.object({
+    id: exports.stickerIdSchema,
+    packId: zod_1.z.string(),
+    emoji: zod_1.z.array(zod_1.z.string()).min(1),
+    keywords: zod_1.z.array(zod_1.z.string()),
+    size: zod_1.z.number().int().positive(),
+    durationMs: zod_1.z.number().int().positive(),
+    /** The Lottie JSON. */
+    animation: exports.stickerFileSchema,
+    /** A static image of the same sticker. */
+    fallback: exports.stickerFileSchema,
+});
+/** What a shop card needs. */
+exports.stickerPackSummarySchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    slug: exports.stickerPackSlugSchema,
+    title: zod_1.z.string(),
+    description: zod_1.z.string().nullable(),
+    author: zod_1.z.string().nullable(),
+    status: exports.stickerPackStatusSchema,
+    publishedAt: zod_1.z.string().nullable(),
+    stickerCount: zod_1.z.number().int().nonnegative(),
+    /** The first sticker, drawn as the pack's cover. Null for an empty draft. */
+    cover: exports.stickerSchema.nullable(),
+});
+exports.stickerPackSchema = exports.stickerPackSummarySchema.extend({
+    stickers: zod_1.z.array(exports.stickerSchema),
+});
+/** A pack in someone's picker. */
+exports.installedStickerPackSchema = exports.stickerPackSchema.extend({
+    installedAt: zod_1.z.string(),
+});
+/* -------------------------------------------------------------------------- */
+/*  References                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * How an app stores or sends a sticker: its id, the pack it came from, and the
+ * hash of the animation it showed. The hash lets a receiver verify the bytes it
+ * fetched are the ones the sender saw — which matters in an end-to-end
+ * encrypted chat, where the server relaying the message never sees it.
+ */
+exports.stickerRefSchema = zod_1.z.object({
+    stickerId: exports.stickerIdSchema,
+    packId: zod_1.z.string().min(1).max(64),
+    sha256: exports.stickerSha256Schema,
+});
+/* -------------------------------------------------------------------------- */
+/*  Requests                                                                  */
+/* -------------------------------------------------------------------------- */
+/** POST /stickers/resolve */
+exports.resolveStickersRequestSchema = zod_1.z.object({
+    ids: zod_1.z.array(exports.stickerIdSchema).min(1).max(exports.STICKER_RESOLVE_MAX_IDS),
+});
+/** Unknown ids are absent, not errors: a caller checks what came back. */
+exports.resolveStickersResponseSchema = zod_1.z.object({
+    stickers: zod_1.z.array(exports.stickerSchema),
+});
+/** PATCH /stickers/me/packs/order — the installed pack ids, first to last. */
+exports.reorderStickerPacksRequestSchema = zod_1.z.object({
+    packIds: zod_1.z.array(zod_1.z.string().min(1).max(64)).max(exports.STICKER_MAX_INSTALLED_PACKS),
+});
+/** POST /stickers/admin/packs */
+exports.createStickerPackRequestSchema = zod_1.z.object({
+    slug: exports.stickerPackSlugSchema,
+    title: zod_1.z.string().trim().min(1).max(64),
+    description: zod_1.z.string().trim().max(500).nullish(),
+    author: zod_1.z.string().trim().max(64).nullish(),
+});
+/** PATCH /stickers/admin/packs/:packId */
+exports.updateStickerPackRequestSchema = exports.createStickerPackRequestSchema
+    .omit({ slug: true })
+    .partial();