@byte_fluffy/nexra-sdk 0.1.0-alpha.3 → 0.1.0-alpha.31

package/README.md

@@ -9,14 +9,14 @@ npm install @byte_fluffy/nexra-sdk@next
 ```
 
 ```ts
-import { createNexra, getModelSpec } from "@byte_fluffy/nexra-sdk";
+import { createNexra, getModelSpec, type NexraImageGenerateInput } from "@byte_fluffy/nexra-sdk";
 
 const nexra = createNexra({ apiKey: process.env.NEXRA_API_KEY });
-const spec = getModelSpec("gpt-image-2");
-const input = {
-  model: spec!.id,
-  prompt: "A paper boat on a blue table",
-  size: "1024x1024",
+const spec = getModelSpec("openai/gpt-image-2");
+const input: NexraImageGenerateInput = {
+  content: [{ type: "text", text: "A paper boat on a blue table", role: "prompt" }],
+  resolution: "1k",
+  aspect_ratio: "1:1",
   quality: "medium",
 };
 const quote = await nexra.catalog.quote({
@@ -24,12 +24,318 @@ const quote = await nexra.catalog.quote({
   operation: "image.generate",
   input,
 });
-const result = await nexra.run(spec!.id, { input, quoteToken: quote.quoteToken });
+const result = await nexra.run(spec!.id, input, { quoteToken: quote.quoteToken });
 ```
 
+Media apps send the versioned Nexra category contract: ordered `content` parts plus
+the common parameters for `image.generate`, `video.generate`, `audio.generate` or
+`image.upscale`. The server resolves the selected model component and explicitly
+adapts that input to the channel Provider. The SDK does not expose or emulate
+Provider-native endpoints. Protocol constants, schemas and types are also
+available from `@byte_fluffy/nexra-sdk/media`.
+
 The default API base URL is `https://api.nexra-ai.com/v1`. When overriding
 `baseUrl`, include the `/v1` API prefix.
 
+## Error contract migration
+
+`0.1.0-alpha.30` introduces the flat public error response and matching SDK
+types and exception getters. Existing HTTP envelopes and historical Task
+objects remain supported as described below.
+
+New Nexra responses keep one platform request context at the root:
+`nexraRequestId` and `nexraHttpStatus`. Platform classification is
+`nexraError: { code, message, param? }`. Provider context uses the independent
+root fields `upstreamHttpStatus`, `upstreamRequestId` and `upstreamError`.
+Successful Task receipts and results can carry the platform context without
+an error. New Task results do not duplicate the old `requestId` or `error`
+wrapper. The SDK's exported `Task` and `TaskPage` types describe these public
+results, not the server's internal Task read model.
+
+`NexraApiError.status` remains the actual fetch response status. Its read-only
+`code` getter and inherited `message` expose the server's platform classification;
+`nexraError` retains that classification object. Both exception types expose
+`nexraHttpStatus`, `nexraRequestId`, `upstreamHttpStatus`, `upstreamRequestId` and
+`upstreamError`. `NexraTaskError` derives these fields and `taskId` from its
+retained `task`, and has no fetch `status`.
+
+Platform HTTP status and request ID describe the same originating request.
+A failed Task can retain its original creation HTTP 202 while a later GET
+returns HTTP 200; its provider might separately return HTTP 400. Missing origin
+evidence is omitted, not inferred from Task failure or a later query. The
+SDK preserves server messages and unknown code strings without localizing or
+reclassifying them. Set `Accept-Language: zh-CN` or `en` through existing client
+`headers` when needed.
+
+The SDK accepts old HTTP envelopes and Task error fields internally. Deprecated
+`requestId` and `details` exception getters return `nexraRequestId` and the
+parameter context, without adding serialized aliases. Use `nexraError.param`
+for new parameter handling. Public retry/category hints are removed; the SDK
+no longer exposes `NexraApiError.retryable`.
+
+`upstreamError` contains captured provider error content. When an older captured
+body has its own `error` member, input normalization selects that member once;
+otherwise it retains the complete captured error body. An already canonical
+`upstreamError` is not unwrapped again. Provider fields named `requestId`,
+`httpStatus`, `retryable` or `category` remain unchanged. Diagnostic flags such
+as `upstreamRedacted`, `upstreamTruncated`, `upstreamUnavailableReason`,
+`upstreamFormat` and `upstreamEvent` remain available when supplied by the server.
+This diagnostic projection does not rewrite original Native HTTP responses or
+Task outputs.
+
+Against older servers, `tasks.get`, `list`, `watch`, `wait` and
+`NexraTaskError.task` retain original Task/Event objects and their historical
+fields. Only exception getters adapt the input shape; the SDK does not clean
+returned objects or manufacture context for old successful responses.
+
+HTTP retry behavior is unchanged: eligible HTTP 503 requests make at most three
+attempts by default, and `maxRetries: 0` makes one attempt. Retry decisions use
+the actual fetch status rather than platform or provider payload metadata.
+Retried Task creation keeps the same idempotency key and payload; failed Tasks
+throw `NexraTaskError` without submitting another generation.
+`NexraWaitTimeoutError` remains a local wait timeout with the original `taskId`
+and does not mean generation failed.
+
+## Model display names
+
+`getModelSpec`, `listModelSpecs`, `nexra.models.search`, `nexra.models.get`, and
+`nexra.catalog.model` return display names with spaces between words and
+capitalized initials, such as
+`Grok Imagine Image`, `GPT 5.4`, and `Wan 2.7 Image Pro`. Brand spelling, acronyms,
+and decimal versions are preserved. Model detail family versions follow the same
+format.
+
+Use `formatModelDisplayName(name)` to apply this format to other display labels.
+It is available from the package root and `/catalog`. Formatting affects only
+`displayName`: use the static catalog's `id`, model discovery's `slug`, or the
+live catalog's `modelId` for requests, never the formatted display name.
+
+## Live model catalog
+
+`getModelSpec` and `listModelSpecs` read the catalog bundled with this SDK release.
+Use `catalog.model(publicId, operation)` to read the currently published database
+input schema, display name, sale prices and actual model revision. A successful
+`available: false` response authoritatively confirms an unavailable or retired
+public identity; HTTP failures throw and must preserve the last successful value.
+An unknown identity returns 404. Model IDs are URL-encoded by the SDK.
+
+`catalog.changes` lists lightweight public model/operation identities and their
+latest revisions. Start with `after: "0"` for initial alignment. Keep the first
+page's `revision` as `upper` for every remaining page and pass its opaque
+`nextCursor`. The cursor is bound to that `after`/`upper` window. Revisions are
+64-bit decimal strings; compare them with `BigInt`, not JavaScript numbers.
+
+```ts
+let after = "0";
+let cursor: string | undefined;
+let upper: string | undefined;
+do {
+  const page = await nexra.catalog.changes({ after, upper, cursor });
+  upper ??= page.revision;
+  // Record changed identities for independent background model reads.
+  enqueueChanges(page.data);
+  cursor = page.nextCursor;
+} while (cursor);
+after = upper!;
+
+for await (const event of nexra.catalog.events({ after, signal })) {
+  enqueueChanges(event.data);
+  after = event.revision;
+}
+```
+
+`enqueueChanges` is application code that records the affected identities before
+advancing the receiving cursor; it does not block on all model reads. Each model
+response carries its own actual revision. Do not label an older response with the
+requested target revision or let it overwrite newer state. An identity updated
+beyond a page window's fixed upper bound appears in the next window, including
+when its index row was replaced during pagination.
+
+`catalog.events` opens one authenticated SSE stream, ignores heartbeats, and
+emits complete `catalog.quote-context.changed` windows with `{ revision,
+changedAt, data }`. Notifications wake the API instance immediately; a per-instance
+60-second revision check recovers silent notification loss. When a stream ends or
+throws, the application reconnects using its retained `after` cursor; the SDK
+does not reconnect automatically. Abort the supplied signal to stop an active
+read. Leaving the iterator cancels and releases the response stream. Keep cached
+values and cursors separate for different API sources and authorization identities.
+No credentials, channel costs or user discounts are included in the public events.
+
+## Private ElevenLabs voices
+
+Voice design uses `elevenlabs/eleven_multilingual_ttv_v2`, with exactly one prompt
+and one script content part. Preview IDs remain in `task.output.previews`; the
+corresponding audio is returned in the ordered persisted `task.assets` list.
+
+```ts
+const design = await nexra.run("elevenlabs/eleven_multilingual_ttv_v2", {
+  content: [
+    { type: "text", role: "prompt", text: "A warm, clear and natural narrator voice." },
+    { type: "text", role: "script", text: previewScript },
+  ],
+}, { idempotencyKey: designKey });
+const creation = await nexra.voices.create({
+  name: "Narrator",
+  source: { kind: "design", taskId: design.task.id, previewId: selectedPreviewId },
+}, { idempotencyKey: saveKey });
+await nexra.tasks.wait(creation.taskId);
+const voice = await nexra.voices.get(creation.voice.id);
+```
+
+Cloning is a voice-resource operation, not a separate vendor model. Upload owned
+audio through `nexra.assets.upload`, then call `nexra.voices.create` with
+`source: { kind: "clone", samples: [sample.id] }`. The service accepts one to five
+stored audio samples totaling at most 25 MiB. Retain the sample IDs and the same
+idempotency key when retrying a creation.
+
+`nexra.voices.list` and `get` read current authenticated resource state. Only an
+active voice can be used for `elevenlabs/eleven_multilingual_v2` speech, using its
+public `voice_` ID. Creation and synthesis settle separately; creation does not
+imply verification or support for renewal, deletion, or voice conversion.
+
+Applications using a shared API key must enforce their own end-user ownership
+before reading or consuming a resource; API-key ownership covers the Nexra
+account, not an application's individual users. Published model choices are
+available through `nexra.models.resources(modelId, resource)`.
+
 Static catalog APIs are also available from `@byte_fluffy/nexra-sdk/catalog`.
 Exact non-negative decimal helpers are available from
 `@byte_fluffy/nexra-sdk/decimal`.
+
+The static catalog includes 14 Agnes and CTYun image/video model
+contracts. A catalog entry describes parameters; it does not grant access to a
+private model or publish a sale price. Check the selected environment's model
+listing and current prices before submitting a task.
+
+Agnes Video 2.5 Flash uses the same video Task input format as Seedance, with
+model-specific limits: `resolution: "720P"`, integer `duration` from 4 to 12,
+up to 5 reference images and 3 reference audio clips, and no video references.
+Keyframes use image content parts with `role: "first_frame"` or `"last_frame"`;
+they cannot be combined with reference media in the same request.
+
+```ts
+const flashInput = {
+  content: [{ type: "text", text: "A paper boat floats across a sunlit pond", role: "prompt" }],
+  duration: 4,
+  resolution: "720P",
+  aspect_ratio: "16:9",
+};
+const flashQuote = await nexra.catalog.quote({
+  modelId: "agnes/agnes-video-2-5-flash",
+  operation: "video.generate",
+  input: flashInput,
+});
+const flashResult = await nexra.run("agnes/agnes-video-2-5-flash", flashInput, {
+  quoteToken: flashQuote.quoteToken,
+});
+```
+
+## Native language models
+
+The optional `@byte_fluffy/nexra-sdk/language` entrypoint returns AI SDK
+`LanguageModelV4` models. Install its optional provider peers when using this
+entrypoint; the core SDK and media entrypoints do not load them. These provider
+versions require Node.js 22 or a supported Bun runtime:
+
+```sh
+npm install @ai-sdk/provider@^4.0.2 @ai-sdk/provider-utils@^5.0.21 \
+  @ai-sdk/openai@^4.0.11 @ai-sdk/anthropic@^4.0.30 @ai-sdk/google@^4.0.12 ai@^7
+```
+
+```ts
+import { generateText, streamText } from "ai";
+import { getLanguageModelBinding } from "@byte_fluffy/nexra-sdk/catalog";
+import { createNexraLanguageModel } from "@byte_fluffy/nexra-sdk/language";
+
+const modelId = "openai/gpt-6-sol";
+const binding = getLanguageModelBinding(modelId);
+const model = createNexraLanguageModel(modelId, {
+  apiKey: process.env.NEXRA_API_KEY!,
+});
+
+if (binding.supportsStreaming) {
+  const result = streamText({ model, prompt: "Explain a paper boat", maxRetries: 0 });
+  for await (const text of result.textStream) process.stdout.write(text);
+} else {
+  const result = await generateText({ model, prompt: "Explain a paper boat", maxRetries: 0 });
+  console.log(result.text);
+}
+```
+
+The binding selects a declared native endpoint, preferring Gemini, Responses,
+Chat Completions, then Messages. Pass `protocol` to choose another endpoint
+declared by that model. Native endpoint `inputSchema` and `outputSchema` describe
+wire parameters; language operation schemas may describe Playground inputs.
+`binding.maxOutputTokens` is the lower of the model capability and selected
+native endpoint limit. Messages requests validate the combined visible and
+thinking token budget before sending; explicit budgets are never clamped.
+The SDK does not wrap text requests in media Tasks or retry generations.
+
+Messages, tool history and ordered content parts use the AI SDK prompt contract.
+Chat Completions supports declared image/video/audio URLs and inline MP3, WAV,
+AAC and M4A audio without downloading URLs or changing codecs. Native model results and stream finish events retain `usage.raw`, including
+cache and modality details. With AI SDK 7, read `result.finalStep.usage.raw`
+or each step callback's usage. Aggregate `result.usage` and `totalUsage` do not
+retain raw records.
+
+Chat native extension fields are passed under `providerOptions.nexra`;
+Responses uses `openai`, Messages uses `anthropic`, and Gemini uses `google`.
+Explicit provider options are preserved. Model identity and prompt/stream
+fields stay owned by the SDK. Kimi K2.5 currently declares synchronous Chat
+Completions only, so use `generateText` for that model.
+
+Responses defaults to `store: false` in this SDK so each request replays the full
+conversation and encrypted reasoning instead of relying on stored item IDs.
+Pass `providerOptions.openai.store: true` explicitly for a stored conversation.
+The current Responses provider cannot preserve sampling parameters alongside
+reasoning for canonical Nexra IDs. Explicit `temperature` or `topP` therefore
+fails before sending instead of being silently discarded. A caller may select
+`forceReasoning: false` for sampling without explicit reasoning controls.
+The documented provider version floors are tested; Anthropic budget validation
+uses its exported capability helper and the shared provider budget mapper.
+
+Use `resolveNexraLanguageReasoning(modelId, { enabled: false })` from `/catalog`
+for a quiet generation policy. Its `providerOptions` select a declared off mode
+or the model's minimum reasoning effort; `canDisable` distinguishes those cases.
+An explicit AI SDK `reasoning: "none"` is rejected when the native model requires
+reasoning, rather than being changed silently. Explicit provider options take
+precedence over shared reasoning defaults.
+
+GPT-6 Sol and GPT-6 Luna are included in the language model catalog. Sale prices
+are not bundled into the SDK; use the current prices published by the selected
+Nexra environment:
+
+```ts
+const { prices } = await nexra.catalog.listPrices();
+const gpt6Prices = prices.filter(({ modelId }) =>
+  modelId === "openai/gpt-6-sol" || modelId === "openai/gpt-6-luna"
+);
+```
+
+## Directory layout
+
+```
+src/
+  index.ts                  Public entry; re-exports the catalog, client, etc.
+  catalog/
+    index.ts                CatalogClient, getModelSpec, listModelSpecs
+    generated/              Generated artifacts (committed; required to publish)
+      image.generated.json  Image model specs
+      language.generated.json  Text/language model specs
+      index.ts              Imports every kind JSON and exports the merged array
+  generated/
+    version.generated.ts    SDK_VERSION used by the transport
+  ...                       client, tasks, assets, input, sse, webhooks, errors, ...
+scripts/
+  generate-public-catalog.ts  Projects models from @nexra/models and writes
+                              src/catalog/generated/*
+```
+
+### Adding a model spec
+
+1. Add its ID to `SDK_MODEL_IDS` in `scripts/generate-public-catalog.ts`.
+2. Run `bun run generate` (from `packages/sdk`).
+3. The script groups projected models by `model.kind`, writes one
+   `src/catalog/generated/<kind>.generated.json` per kind (new kinds appear
+   automatically), regenerates the merging `index.ts`, and bumps
+   `src/generated/version.generated.ts`. No hand-written code changes.

package/dist/assets-Cusrjj7_.d.ts

@@ -0,0 +1,61 @@
+import { a as JsonObject } from './json-Cz0MkWQn.js';
+
+declare const MEDIA_KINDS: readonly ["image", "video", "audio", "document", "archive", "other"];
+type MediaKind = (typeof MEDIA_KINDS)[number];
+type MediaAssetStatus = "pending" | "ready" | "failed" | "deleted";
+interface MediaAsset {
+    id: string;
+    kind: MediaKind;
+    status: MediaAssetStatus;
+    source: "upload" | "generated" | "provider" | "imported";
+    name?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    checksumSha256?: string;
+    url?: string;
+    downloadUrl?: string;
+    expiresAt?: string;
+    metadata?: JsonObject;
+    createdAt: string;
+}
+interface AssetReference {
+    assetId: string;
+}
+type AssetInput = AssetReference | Blob | File | MediaAsset | string | URL;
+interface AssetUploadOptions {
+    kind?: MediaKind;
+    name?: string;
+    signal?: AbortSignal;
+}
+interface AssetImportRequest {
+    url: string;
+    kind?: MediaKind;
+    name?: string;
+}
+type AssetCertificationProvider = "seedance";
+type AssetCertificationStatus = "processing" | "ready" | "failed";
+interface AssetCertification {
+    assetId: string;
+    provider: AssetCertificationProvider;
+    status: AssetCertificationStatus;
+    providerAssetId?: string;
+    assetUri?: string;
+    groupId?: string;
+    library: "general" | "liveness";
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AssetCertificationRequest {
+    library?: "general" | "liveness";
+}
+interface AssetCertificationWaitOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+
+export { type AssetImportRequest as A, MEDIA_KINDS as M, type AssetInput as a, type AssetReference as b, type AssetUploadOptions as c, type MediaAsset as d, type MediaAssetStatus as e, type MediaKind as f, type AssetCertificationRequest as g, type AssetCertification as h, type AssetCertificationWaitOptions as i };

package/dist/catalog.d.ts

@@ -1 +1,44 @@
-export { d as CatalogClient, h as CreateNexraQuoteRequest, u as NexraBillingCurrency, v as NexraModelOperation, w as NexraModelSpec, x as NexraModelSpecFilter, y as NexraQuote, z as NexraSalePrice, N as NexraSettlement, R as getModelSpec, V as listModelSpecs } from './catalog-mytCeh5t.js';
+import { a as JsonObject } from './json-Cz0MkWQn.js';
+import { H as HttpTransport, A as NexraCatalogChangeParams, B as NexraCatalogChangePage, D as NexraCatalogModelState, u as NexraSalePriceList, d as CreateNexraQuoteRequest, s as NexraQuote, C as CreateNexraDisplayQuoteBatchRequest, n as NexraDisplayQuoteBatch, m as NexraCatalogRevision, q as NexraModelSpec, E as NexraModelEndpointSpec, r as NexraModelSpecFilter } from './media-geometry-DAVFGry1.js';
+export { e as MediaGeometryField, f as MediaGeometryProjection, l as NexraBillingCurrency, G as NexraCatalogModelIdentity, p as NexraModelOperation, t as NexraSalePrice, v as NexraSettlement, U as UnifiedMediaGeometry, w as applyMediaGeometry, x as decodeMediaGeometry, y as encodeMediaGeometry, z as projectMediaGeometry } from './media-geometry-DAVFGry1.js';
+
+declare function formatModelDisplayName(displayName: string): string;
+
+declare class CatalogClient {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    changes(params?: NexraCatalogChangeParams, signal?: AbortSignal): Promise<NexraCatalogChangePage>;
+    model(modelId: string, operation: string, signal?: AbortSignal): Promise<NexraCatalogModelState>;
+    events(options?: {
+        after?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<NexraCatalogChangePage>;
+    listPrices(signal?: AbortSignal): Promise<NexraSalePriceList>;
+    quote(request: CreateNexraQuoteRequest, signal?: AbortSignal): Promise<NexraQuote>;
+    quoteBatch(request: CreateNexraDisplayQuoteBatchRequest, signal?: AbortSignal): Promise<NexraDisplayQuoteBatch>;
+    revision(signal?: AbortSignal): Promise<NexraCatalogRevision>;
+}
+declare function getModelSpec(modelId: string): NexraModelSpec | undefined;
+declare function listModelSpecs(filter?: NexraModelSpecFilter): readonly NexraModelSpec[];
+type NexraLanguageProtocol = "gemini-generate-content" | "openai-responses" | "openai-chat-completions" | "anthropic-messages";
+type NexraLanguageModelBinding = Readonly<{
+    spec: NexraModelSpec;
+    endpoint: NexraModelEndpointSpec & {
+        protocol: NexraLanguageProtocol;
+    };
+    supportsStreaming: boolean;
+    maxOutputTokens?: number;
+}>;
+declare function getLanguageModelBinding(modelId: string, options?: {
+    protocol?: NexraLanguageProtocol;
+}): NexraLanguageModelBinding;
+type NexraLanguageReasoning = Readonly<{
+    providerOptions: Record<string, JsonObject>;
+    canDisable: boolean;
+}>;
+declare function resolveNexraLanguageReasoning(modelId: string, options: {
+    enabled: boolean;
+    protocol?: NexraLanguageProtocol;
+}): NexraLanguageReasoning;
+
+export { CatalogClient, CreateNexraDisplayQuoteBatchRequest, CreateNexraQuoteRequest, NexraCatalogChangePage, NexraCatalogChangeParams, NexraCatalogModelState, NexraCatalogRevision, NexraDisplayQuoteBatch, type NexraLanguageModelBinding, type NexraLanguageProtocol, type NexraLanguageReasoning, NexraModelEndpointSpec, NexraModelSpec, NexraModelSpecFilter, NexraQuote, NexraSalePriceList, formatModelDisplayName, getLanguageModelBinding, getModelSpec, listModelSpecs, resolveNexraLanguageReasoning };

package/dist/catalog.js

@@ -1,10 +1,25 @@
 import {
   CatalogClient,
+  applyMediaGeometry,
+  decodeMediaGeometry,
+  encodeMediaGeometry,
+  formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
-  listModelSpecs
-} from "./chunk-IMJZBLDE.js";
+  listModelSpecs,
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
+} from "./chunk-QXEDXMFI.js";
+import "./chunk-QBW7OCT3.js";
 export {
   CatalogClient,
+  applyMediaGeometry,
+  decodeMediaGeometry,
+  encodeMediaGeometry,
+  formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
-  listModelSpecs
+  listModelSpecs,
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
 };