@byte_fluffy/nexra-sdk 0.1.0-alpha.26 → 0.1.0-alpha.28

package/README.md

@@ -37,6 +37,108 @@ 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.
 
+## 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`.

package/dist/catalog.d.ts

@@ -1,10 +1,18 @@
-import { H as HttpTransport, N as NexraSalePriceList, C as CreateNexraQuoteRequest, a as NexraQuote, b as CreateNexraDisplayQuoteBatchRequest, c as NexraDisplayQuoteBatch, d as NexraCatalogRevision, e as NexraModelSpec, f as NexraModelSpecFilter } from './media-geometry-CRCAkREf.js';
-export { M as MediaGeometryField, g as MediaGeometryProjection, h as NexraBillingCurrency, i as NexraModelEndpointSpec, j as NexraModelOperation, k as NexraSalePrice, l as NexraSettlement, U as UnifiedMediaGeometry, m as applyMediaGeometry, n as decodeMediaGeometry, o as encodeMediaGeometry, p as projectMediaGeometry } from './media-geometry-CRCAkREf.js';
+import { H as HttpTransport, N as NexraCatalogChangeParams, a as NexraCatalogChangePage, b as NexraCatalogModelState, c as NexraSalePriceList, C as CreateNexraQuoteRequest, d as NexraQuote, e as CreateNexraDisplayQuoteBatchRequest, f as NexraDisplayQuoteBatch, g as NexraCatalogRevision, h as NexraModelSpec, i as NexraModelSpecFilter } from './media-geometry-BoxkWQlj.js';
+export { M as MediaGeometryField, j as MediaGeometryProjection, k as NexraBillingCurrency, l as NexraCatalogModelIdentity, m as NexraModelEndpointSpec, n as NexraModelOperation, o as NexraSalePrice, p as NexraSettlement, U as UnifiedMediaGeometry, q as applyMediaGeometry, r as decodeMediaGeometry, s as encodeMediaGeometry, t as projectMediaGeometry } from './media-geometry-BoxkWQlj.js';
 import './json-Drjj1OKl.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>;
@@ -13,4 +21,4 @@ declare class CatalogClient {
 declare function getModelSpec(modelId: string): NexraModelSpec | undefined;
 declare function listModelSpecs(filter?: NexraModelSpecFilter): readonly NexraModelSpec[];
 
-export { CatalogClient, CreateNexraDisplayQuoteBatchRequest, CreateNexraQuoteRequest, NexraCatalogRevision, NexraDisplayQuoteBatch, NexraModelSpec, NexraModelSpecFilter, NexraQuote, NexraSalePriceList, getModelSpec, listModelSpecs };
+export { CatalogClient, CreateNexraDisplayQuoteBatchRequest, CreateNexraQuoteRequest, NexraCatalogChangePage, NexraCatalogChangeParams, NexraCatalogModelState, NexraCatalogRevision, NexraDisplayQuoteBatch, NexraModelSpec, NexraModelSpecFilter, NexraQuote, NexraSalePriceList, formatModelDisplayName, getModelSpec, listModelSpecs };

package/dist/catalog.js

@@ -3,16 +3,18 @@ import {
   applyMediaGeometry,
   decodeMediaGeometry,
   encodeMediaGeometry,
+  formatModelDisplayName,
   getModelSpec,
   listModelSpecs,
   projectMediaGeometry
-} from "./chunk-73CGYVFV.js";
-import "./chunk-KEAAHI25.js";
+} from "./chunk-ECF5MLSM.js";
+import "./chunk-IEBCNRT4.js";
 export {
   CatalogClient,
   applyMediaGeometry,
   decodeMediaGeometry,
   encodeMediaGeometry,
+  formatModelDisplayName,
   getModelSpec,
   listModelSpecs,
   projectMediaGeometry