@particle-academy/prism 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TJ MIller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @particle-academy/prism
+
+A TypeScript port of [Prism](https://github.com/Particle-Academy/prism), the
+PHP/Laravel unified API layer over LLM providers.
+
+Real TypeScript: promises, discriminated unions, strict null checking. What it
+is *not* is a transliteration — the idioms are this language's. What crosses the
+wire, and what comes back, is identical.
+
+> **Working on this package?** Read **[`AGENTS.md`](AGENTS.md)** first — the boundary
+> this package has to hold, the gates that must be green, and the traps that have
+> already caught someone.
+> `@link AGENTS.md`
+
+## Scope
+
+**Every capability the reference has**, and three of its eighteen providers.
+That is the shape of the remaining drift: one axis, not two.
+
+- **Capabilities — all of them.** `text`, `structured`, `stream`, `embeddings`,
+  `images`, `moderation`, `audio` (`textToSpeech` and `speechToText`), `files`,
+  `batch`, `fim`. A user message carries images and documents, and each provider
+  spells them its own way.
+- **Providers — `anthropic`, `mistral`, `openai`.** The OpenAI provider speaks
+  the **Responses API**; Mistral brings the chat-completions shape, which is a
+  different wire format rather than a variant of it.
+
+Not included, and not stubbed: **the tool-execution loop** — a response that
+finishes on tool calls is refused with `tool_loop_not_supported` rather than
+half-executed — and the fifteen providers the reference has and this port does
+not. Asking for one fails with the `unsupported_provider_action` code rather
+than returning something plausible.
+
+Not every capability reaches every provider, because not every provider has one.
+`images`, `moderation`, `textToSpeech`, `files` and `batch` are OpenAI-only
+here, and `fim` is Mistral-only because Mistral is the only provider that
+implements it at all — in the reference as well. See the envelope's port gaps
+register for which of those are work someone could do and which are facts about
+the provider.
+
+Every value object serialises **and rebuilds** — `toObject()` and a static
+`fromObject()`. The PHP package has only the first half, which left each consumer
+to invent the second; one of those inventions shipped a defect that corrupted
+stored assistant messages. Both halves ship here, and the rebuild direction is
+pinned by fixtures.
+
+Failures carry a stable `code` (`PrismError.code`). The prose is not part of the
+contract and will change; the code will not.
+
+## Install
+
+```sh
+npm install @particle-academy/prism
+```
+
+Node 20 or newer.
+
+## Usage
+
+```ts
+import { Prism } from '@particle-academy/prism';
+
+const response = await Prism.text()
+  .using('openai', 'gpt-4o')
+  .withSystemPrompt('You are terse.')
+  .withPrompt('Who are you?')
+  .asText();
+
+console.log(response.text);
+console.log(response.usage.promptTokens, response.usage.completionTokens);
+```
+
+Configuration is explicit first, environment second — `OPENAI_API_KEY`,
+`OPENAI_URL`, `OPENAI_ORGANIZATION`, `OPENAI_PROJECT`:
+
+```ts
+Prism.text().using('openai', 'gpt-4o', { apiKey: 'sk-…', transport });
+```
+
+`transport` is the seam between the provider and the network. Pass one and no
+test ever touches a socket:
+
+```ts
+import type { HttpTransport } from '@particle-academy/prism';
+
+const transport: HttpTransport = async (request) => ({
+  status: 200,
+  headers: {},
+  body: recordedPayload,
+  rawBody: JSON.stringify(recordedPayload),
+});
+```
+
+Build a request without sending it, or parse a stored payload without HTTP:
+
+```ts
+import { buildRequestBody, canonicalJson, parseTextResponse } from '@particle-academy/prism';
+
+const request = Prism.text().using('openai', 'gpt-4o').withPrompt('hi').toRequest();
+
+canonicalJson(buildRequestBody(request)); // exactly the bytes that would be POSTed
+parseTextResponse(request, recordedPayload); // the same parse a live call performs
+```
+
+## Parity
+
+This port's behaviour is not defined by its own tests. It is pinned by
+[**prism-parity**](https://github.com/Particle-Academy/prism-parity) — a
+language-independent conformance corpus generated by executing the PHP
+reference, which states the rules once so three implementations cannot each
+drift into their own reading of them.
+
+The corpus and its loader install as `@particle-academy/prism-conformance`. The
+runner lives in [`conformance/runner.mjs`](conformance/runner.mjs) and implements
+prism-parity's subprocess contract, so `scripts/cross-check.mjs` can run this
+port and the others side by side and require **identical verdicts** — a stronger
+claim than three suites that each went green alone.
+
+```sh
+git clone https://github.com/Particle-Academy/prism-parity .parity
+npm install ./.parity/loaders/ts
+npm run conformance                       # every suite
+node conformance/runner.mjs --suite openai-text-request
+node conformance/runner.mjs --probe omit-null-keys
+```
+
+Two rows diverge from the reference on purpose, and the corpus says which and
+why: `trq-0021` and `trq-0022`, where the reference drops a prompt of `""` or
+`"0"` and this port sends it. Read the corpus for the rest — restating its rules
+here would only give them somewhere to drift.
+
+### Probes
+
+`--probe` runs the port with one deliberate defect injected, from the corpus's
+`probes/probes.json`. Each probe declares the exact set of case ids it must fail,
+and [`tests/probes.test.ts`](tests/probes.test.ts) asserts the observed set
+*equals* it — not that it is non-empty. A table every plausible implementation
+passes measures nothing.
+
+The mutants live in [`conformance/mutations.mjs`](conformance/mutations.mjs),
+outside `src/`: a defect you can switch on in production is a defect.
+
+## Development
+
+```sh
+npm run build       # tsc → dist/
+npm run typecheck
+npm run lint
+npm test
+npm run conformance
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/audio/pending-request.d.ts

@@ -0,0 +1,37 @@
+import type { JsonObject } from '../json.js';
+import type { Provider } from '../providers/provider.js';
+import { Audio } from '../value-objects/media/audio.js';
+import { SpeechToTextRequest, TextToSpeechRequest } from './request.js';
+import type { AudioResponse, AudioTextResponse } from './response.js';
+/**
+ * The builder for both audio directions.
+ *
+ * ONE builder with two terminals, matching the reference: `withInput()` takes
+ * either a string to speak or an `Audio` to transcribe, and the terminal method
+ * decides which request is built. The alternative — two builders — would force
+ * a caller to know the direction before they have the input, which is backwards
+ * from how audio work actually arrives.
+ */
+export declare class AudioPendingRequest {
+    #private;
+    using(provider: string, model?: string, providerConfig?: Record<string, unknown>): this;
+    /** A string to speak, or an `Audio` to transcribe. */
+    withInput(input: string | Audio): this;
+    withVoice(voice: string): this;
+    withProviderOptions(options?: Readonly<JsonObject>): this;
+    withClientOptions(options: Record<string, unknown>): this;
+    provider(): Provider;
+    /**
+     * @throws PrismError code `wrong_audio_input` when the input is an `Audio`.
+     *
+     * Refused rather than coerced. There is no sensible reading of "speak this
+     * recording", and the alternative — stringifying it — would send a provider
+     * something like `[object Object]` to read aloud.
+     */
+    toTextToSpeechRequest(): TextToSpeechRequest;
+    /** @throws PrismError code `wrong_audio_input` when the input is a string. */
+    toSpeechToTextRequest(): SpeechToTextRequest;
+    asAudio(): Promise<AudioResponse>;
+    asText(): Promise<AudioTextResponse>;
+}
+//# sourceMappingURL=pending-request.d.ts.map

package/dist/audio/pending-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-request.d.ts","sourceRoot":"","sources":["../../src/audio/pending-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEtE;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;;IAe9B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,cAAc,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAQvF,sDAAsD;IACtD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAMtC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM9B,mBAAmB,CAAC,OAAO,GAAE,QAAQ,CAAC,UAAU,CAAM,GAAG,IAAI;IAM7D,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMzD,QAAQ,IAAI,QAAQ;IAWpB;;;;;;OAMG;IACH,qBAAqB,IAAI,mBAAmB;IAe5C,8EAA8E;IAC9E,qBAAqB,IAAI,mBAAmB;IActC,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IAIjC,MAAM,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAG3C"}

package/dist/audio/pending-request.js

@@ -0,0 +1,91 @@
+import { PrismError } from '../errors.js';
+import { resolveProvider } from '../providers/registry.js';
+import { Audio } from '../value-objects/media/audio.js';
+import { SpeechToTextRequest, TextToSpeechRequest } from './request.js';
+/**
+ * The builder for both audio directions.
+ *
+ * ONE builder with two terminals, matching the reference: `withInput()` takes
+ * either a string to speak or an `Audio` to transcribe, and the terminal method
+ * decides which request is built. The alternative — two builders — would force
+ * a caller to know the direction before they have the input, which is backwards
+ * from how audio work actually arrives.
+ */
+export class AudioPendingRequest {
+    #provider = null;
+    #providerKey = '';
+    #model = '';
+    #input = null;
+    #voice = null;
+    #providerOptions = {};
+    #clientOptions = {};
+    using(provider, model = '', providerConfig = {}) {
+        this.#providerKey = provider;
+        this.#model = model;
+        this.#provider = resolveProvider(provider, providerConfig);
+        return this;
+    }
+    /** A string to speak, or an `Audio` to transcribe. */
+    withInput(input) {
+        this.#input = input;
+        return this;
+    }
+    withVoice(voice) {
+        this.#voice = voice;
+        return this;
+    }
+    withProviderOptions(options = {}) {
+        this.#providerOptions = { ...options };
+        return this;
+    }
+    withClientOptions(options) {
+        this.#clientOptions = { ...options };
+        return this;
+    }
+    provider() {
+        if (this.#provider === null) {
+            throw PrismError.unsupportedProviderAction('Sending a request', 'a pending request with no provider — call using() first');
+        }
+        return this.#provider;
+    }
+    /**
+     * @throws PrismError code `wrong_audio_input` when the input is an `Audio`.
+     *
+     * Refused rather than coerced. There is no sensible reading of "speak this
+     * recording", and the alternative — stringifying it — would send a provider
+     * something like `[object Object]` to read aloud.
+     */
+    toTextToSpeechRequest() {
+        if (typeof this.#input !== 'string') {
+            throw PrismError.wrongAudioInput('text to speak', 'an audio payload');
+        }
+        return new TextToSpeechRequest({
+            model: this.#model,
+            providerKey: this.#providerKey,
+            input: this.#input,
+            voice: this.#voice,
+            clientOptions: this.#clientOptions,
+            providerOptions: this.#providerOptions,
+        });
+    }
+    /** @throws PrismError code `wrong_audio_input` when the input is a string. */
+    toSpeechToTextRequest() {
+        if (!(this.#input instanceof Audio)) {
+            throw PrismError.wrongAudioInput('an audio payload', 'text');
+        }
+        return new SpeechToTextRequest({
+            model: this.#model,
+            providerKey: this.#providerKey,
+            input: this.#input,
+            clientOptions: this.#clientOptions,
+            providerOptions: this.#providerOptions,
+        });
+    }
+    async asAudio() {
+        return this.provider().textToSpeech(this.toTextToSpeechRequest());
+    }
+    async asText() {
+        return this.provider().speechToText(this.toSpeechToTextRequest());
+    }
+}
+//# sourceMappingURL=pending-request.js.map

package/dist/audio/pending-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-request.js","sourceRoot":"","sources":["../../src/audio/pending-request.ts"],"names":[],"mappings":"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"}

package/dist/audio/request.d.ts

@@ -0,0 +1,37 @@
+import type { JsonObject, JsonValue } from '../json.js';
+import type { Audio } from '../value-objects/media/audio.js';
+interface BaseOptions {
+    model: string;
+    providerKey: string;
+    clientOptions?: Readonly<Record<string, unknown>>;
+    providerOptions?: Readonly<JsonObject>;
+}
+declare abstract class AudioRequestBase {
+    #private;
+    constructor(options: BaseOptions);
+    model(): string;
+    providerKey(): string;
+    clientOptions(): Readonly<Record<string, unknown>>;
+    providerOptions(): JsonObject;
+    providerOptions(path: string): JsonValue | undefined;
+}
+export interface TextToSpeechRequestOptions extends BaseOptions {
+    input: string;
+    voice: string | null;
+}
+export declare class TextToSpeechRequest extends AudioRequestBase {
+    #private;
+    constructor(options: TextToSpeechRequestOptions);
+    input(): string;
+    voice(): string | null;
+}
+export interface SpeechToTextRequestOptions extends BaseOptions {
+    input: Audio;
+}
+export declare class SpeechToTextRequest extends AudioRequestBase {
+    #private;
+    constructor(options: SpeechToTextRequestOptions);
+    input(): Audio;
+}
+export {};
+//# sourceMappingURL=request.d.ts.map

package/dist/audio/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/audio/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAE7D,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,eAAe,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;CACxC;AAED,uBAAe,gBAAgB;;gBASjB,OAAO,EAAE,WAAW;IAOhC,KAAK,IAAI,MAAM;IAIf,WAAW,IAAI,MAAM;IAIrB,aAAa,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIlD,eAAe,IAAI,UAAU;IAC7B,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;CAIrD;AAED,MAAM,WAAW,0BAA2B,SAAQ,WAAW;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,qBAAa,mBAAoB,SAAQ,gBAAgB;;gBAK3C,OAAO,EAAE,0BAA0B;IAM/C,KAAK,IAAI,MAAM;IAIf,KAAK,IAAI,MAAM,GAAG,IAAI;CAGvB;AAED,MAAM,WAAW,0BAA2B,SAAQ,WAAW;IAC7D,KAAK,EAAE,KAAK,CAAC;CACd;AAED,qBAAa,mBAAoB,SAAQ,gBAAgB;;gBAG3C,OAAO,EAAE,0BAA0B;IAK/C,KAAK,IAAI,KAAK;CAGf"}

package/dist/audio/request.js

@@ -0,0 +1,50 @@
+class AudioRequestBase {
+    #model;
+    #providerKey;
+    #clientOptions;
+    #providerOptions;
+    constructor(options) {
+        this.#model = options.model;
+        this.#providerKey = options.providerKey;
+        this.#clientOptions = options.clientOptions ?? {};
+        this.#providerOptions = { ...(options.providerOptions ?? {}) };
+    }
+    model() {
+        return this.#model;
+    }
+    providerKey() {
+        return this.#providerKey;
+    }
+    clientOptions() {
+        return this.#clientOptions;
+    }
+    providerOptions(path) {
+        return path === undefined ? this.#providerOptions : this.#providerOptions[path];
+    }
+}
+export class TextToSpeechRequest extends AudioRequestBase {
+    #input;
+    #voice;
+    constructor(options) {
+        super(options);
+        this.#input = options.input;
+        this.#voice = options.voice;
+    }
+    input() {
+        return this.#input;
+    }
+    voice() {
+        return this.#voice;
+    }
+}
+export class SpeechToTextRequest extends AudioRequestBase {
+    #input;
+    constructor(options) {
+        super(options);
+        this.#input = options.input;
+    }
+    input() {
+        return this.#input;
+    }
+}
+//# sourceMappingURL=request.js.map

package/dist/audio/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/audio/request.ts"],"names":[],"mappings":"AAUA,MAAe,gBAAgB;IACpB,MAAM,CAAS;IAEf,YAAY,CAAS;IAErB,cAAc,CAAoC;IAElD,gBAAgB,CAAa;IAEtC,YAAY,OAAoB;QAC9B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;QACxC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;QAClD,IAAI,CAAC,gBAAgB,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,CAAC;IACjE,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAID,eAAe,CAAC,IAAa;QAC3B,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAClF,CAAC;CACF;AAOD,MAAM,OAAO,mBAAoB,SAAQ,gBAAgB;IAC9C,MAAM,CAAS;IAEf,MAAM,CAAgB;IAE/B,YAAY,OAAmC;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAC9B,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF;AAMD,MAAM,OAAO,mBAAoB,SAAQ,gBAAgB;IAC9C,MAAM,CAAQ;IAEvB,YAAY,OAAmC;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAC9B,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/audio/response.d.ts

@@ -0,0 +1,24 @@
+import type { JsonObject } from '../json.js';
+import type { GeneratedAudio } from '../value-objects/generated-audio.js';
+import type { Usage } from '../value-objects/usage.js';
+/** What `asAudio()` returns: speech, and whatever else the provider said. */
+export declare class AudioResponse {
+    readonly audio: GeneratedAudio;
+    readonly additionalContent: Readonly<JsonObject>;
+    constructor(audio: GeneratedAudio, additionalContent?: Readonly<JsonObject>);
+    toObject(): JsonObject;
+}
+/**
+ * What `asText()` returns: a transcript.
+ *
+ * `usage` is NULLABLE because transcription is billed by audio duration on most
+ * providers and they report no tokens at all. Zero would claim it was free.
+ */
+export declare class AudioTextResponse {
+    readonly text: string;
+    readonly usage: Usage | null;
+    readonly additionalContent: Readonly<JsonObject>;
+    constructor(text: string, usage?: Usage | null, additionalContent?: Readonly<JsonObject>);
+    toObject(): JsonObject;
+}
+//# sourceMappingURL=response.d.ts.map

package/dist/audio/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/audio/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAEvD,6EAA6E;AAC7E,qBAAa,aAAa;IAEtB,QAAQ,CAAC,KAAK,EAAE,cAAc;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,UAAU,CAAC;gBADvC,KAAK,EAAE,cAAc,EACrB,iBAAiB,GAAE,QAAQ,CAAC,UAAU,CAAM;IAGvD,QAAQ,IAAI,UAAU;CAGvB;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAE1B,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,UAAU,CAAC;gBAFvC,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,KAAK,GAAG,IAAW,EAC1B,iBAAiB,GAAE,QAAQ,CAAC,UAAU,CAAM;IAGvD,QAAQ,IAAI,UAAU;CAOvB"}

package/dist/audio/response.js

@@ -0,0 +1,36 @@
+/** What `asAudio()` returns: speech, and whatever else the provider said. */
+export class AudioResponse {
+    audio;
+    additionalContent;
+    constructor(audio, additionalContent = {}) {
+        this.audio = audio;
+        this.additionalContent = additionalContent;
+    }
+    toObject() {
+        return { audio: this.audio.toObject(), additional_content: { ...this.additionalContent } };
+    }
+}
+/**
+ * What `asText()` returns: a transcript.
+ *
+ * `usage` is NULLABLE because transcription is billed by audio duration on most
+ * providers and they report no tokens at all. Zero would claim it was free.
+ */
+export class AudioTextResponse {
+    text;
+    usage;
+    additionalContent;
+    constructor(text, usage = null, additionalContent = {}) {
+        this.text = text;
+        this.usage = usage;
+        this.additionalContent = additionalContent;
+    }
+    toObject() {
+        return {
+            text: this.text,
+            usage: this.usage === null ? null : this.usage.toObject(),
+            additional_content: { ...this.additionalContent },
+        };
+    }
+}
+//# sourceMappingURL=response.js.map

package/dist/audio/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/audio/response.ts"],"names":[],"mappings":"AAIA,6EAA6E;AAC7E,MAAM,OAAO,aAAa;IAEb;IACA;IAFX,YACW,KAAqB,EACrB,oBAA0C,EAAE;QAD5C,UAAK,GAAL,KAAK,CAAgB;QACrB,sBAAiB,GAAjB,iBAAiB,CAA2B;IACpD,CAAC;IAEJ,QAAQ;QACN,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,kBAAkB,EAAE,EAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;IAC7F,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAEjB;IACA;IACA;IAHX,YACW,IAAY,EACZ,QAAsB,IAAI,EAC1B,oBAA0C,EAAE;QAF5C,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAqB;QAC1B,sBAAiB,GAAjB,iBAAiB,CAA2B;IACpD,CAAC;IAEJ,QAAQ;QACN,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE;YACzD,kBAAkB,EAAE,EAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE;SAClD,CAAC;IACJ,CAAC;CACF"}

package/dist/batch/batch-job.d.ts

@@ -0,0 +1,91 @@
+import type { JsonObject } from '../json.js';
+import type { Usage } from '../value-objects/usage.js';
+/** Where a batch is in its lifecycle, as the provider names it. */
+export declare enum BatchStatus {
+    Validating = "validating",
+    InProgress = "in_progress",
+    Finalizing = "finalizing",
+    Completed = "completed",
+    Failed = "failed",
+    Cancelling = "cancelling",
+    Cancelled = "cancelled",
+    Expired = "expired"
+}
+/** How one item inside a batch turned out. */
+export declare enum BatchResultStatus {
+    Succeeded = "succeeded",
+    Errored = "errored",
+    Canceled = "canceled",
+    Expired = "expired"
+}
+/**
+ * How many requests are in each state.
+ *
+ * FIVE counts and a total, matching the reference — but OpenAI reports only
+ * three (`total`, `completed`, `failed`), so `canceled` and `expired` stay zero
+ * on that provider. They are not dropped, because a batch that was cancelled
+ * mid-flight is a real thing another provider does report.
+ */
+export declare class BatchJobRequestCounts {
+    readonly processing: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly canceled: number;
+    readonly expired: number;
+    readonly total: number;
+    constructor(processing?: number, succeeded?: number, failed?: number, canceled?: number, expired?: number, total?: number);
+    toObject(): JsonObject;
+}
+export interface BatchJobError {
+    code: string;
+    message: string;
+    line: number | null;
+    param: string | null;
+}
+/** A submitted batch: what it is, where it is, and what came of it. */
+export declare class BatchJob {
+    readonly id: string;
+    readonly status: BatchStatus;
+    readonly requestCounts: BatchJobRequestCounts;
+    /** ISO 8601, in UTC — see `parseBatchJob`. */
+    readonly createdAt: string | null;
+    readonly expiresAt: string | null;
+    readonly endedAt: string | null;
+    readonly resultsUrl: string | null;
+    readonly inputFileId: string | null;
+    readonly outputFileId: string | null;
+    readonly errorFileId: string | null;
+    readonly errors: readonly BatchJobError[];
+    constructor(id: string, status: BatchStatus, requestCounts: BatchJobRequestCounts, 
+    /** ISO 8601, in UTC — see `parseBatchJob`. */
+    createdAt?: string | null, expiresAt?: string | null, endedAt?: string | null, resultsUrl?: string | null, inputFileId?: string | null, outputFileId?: string | null, errorFileId?: string | null, errors?: readonly BatchJobError[]);
+    toObject(): JsonObject;
+}
+/** One page of batches. */
+export declare class BatchListResult {
+    readonly data: readonly BatchJob[];
+    readonly hasMore: boolean;
+    readonly lastId: string | null;
+    constructor(data: readonly BatchJob[], hasMore?: boolean, lastId?: string | null);
+    toObject(): JsonObject;
+}
+/**
+ * What one request in a batch produced.
+ *
+ * `text` and `usage` are null on a failure and `errorType`/`errorMessage` are
+ * null on a success — the four fields are read together with `status`, which is
+ * the field that says which pair means anything.
+ */
+export declare class BatchResultItem {
+    readonly customId: string;
+    readonly status: BatchResultStatus;
+    readonly text: string | null;
+    readonly usage: Usage | null;
+    readonly messageId: string | null;
+    readonly model: string | null;
+    readonly errorType: string | null;
+    readonly errorMessage: string | null;
+    constructor(customId: string, status: BatchResultStatus, text?: string | null, usage?: Usage | null, messageId?: string | null, model?: string | null, errorType?: string | null, errorMessage?: string | null);
+    toObject(): JsonObject;
+}
+//# sourceMappingURL=batch-job.d.ts.map

package/dist/batch/batch-job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-job.d.ts","sourceRoot":"","sources":["../../src/batch/batch-job.ts"],"names":[],"mappings":"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"}