@byte_fluffy/nexra-sdk 0.1.0-alpha.20 → 0.1.0-alpha.21

package/README.md

@@ -9,18 +9,14 @@ npm install @byte_fluffy/nexra-sdk@next
 ```
 
 ```ts
-import { createNexra, getModelSpec, projectMediaGeometry } 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("openai/gpt-image-2");
-const geometry = projectMediaGeometry(spec!.operations[0]!.inputSchema);
-// geometry.resolution.options → ["1K","2K","4K"]; geometry.ratio.options → ["1:1", ...]
-
-const input = {
-  model: spec!.id,
-  prompt: "A paper boat on a blue table",
-  resolution: "1K",
-  ratio: "1:1",
+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({
@@ -28,10 +24,15 @@ 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 });
 ```
 
-Apps should send the unified geometry (`resolution` + `ratio` + `quality`). Quote and `run`/`create` map those fields onto the model's native catalog parameters (GPT Image `size: 1024x1024`, Seedream `size: 2K`, Grok `resolution: 1k` + `aspect_ratio`, …). `encodeMediaGeometry` / `decodeMediaGeometry` expose the same mapping without making a request. Native `size` already in the body is left unchanged.
+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.

package/dist/assets-dUJMQNJD.d.ts

@@ -0,0 +1,61 @@
+import { J as JsonObject } from './json-Drjj1OKl.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 AssetReference as A, MEDIA_KINDS as M, type AssetImportRequest as a, type AssetInput 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,5 +1,6 @@
-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-Ckr1-Mh3.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-Ckr1-Mh3.js';
+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-Bo6ukeIQ.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-Bo6ukeIQ.js';
+import './json-Drjj1OKl.js';
 
 declare class CatalogClient {
     private readonly transport;

package/dist/catalog.js

@@ -6,7 +6,8 @@ import {
   getModelSpec,
   listModelSpecs,
   projectMediaGeometry
-} from "./chunk-PAVF5LNU.js";
+} from "./chunk-WU62FGYW.js";
+import "./chunk-TA3YGQQY.js";
 export {
   CatalogClient,
   applyMediaGeometry,

package/dist/chunk-TA3YGQQY.js

@@ -0,0 +1,386 @@
+// ../contracts/src/assets.ts
+var MEDIA_KINDS = [
+  "image",
+  "video",
+  "audio",
+  "document",
+  "archive",
+  "other"
+];
+
+// ../contracts/src/media-api.ts
+var NEXRA_MEDIA_API_VERSION = 1;
+var NEXRA_GENERATION_OPERATIONS = [
+  "text.generate",
+  "image.generate",
+  "video.generate",
+  "audio.generate",
+  "image.upscale",
+  "video.upscale"
+];
+var NEXRA_MEDIA_OPERATIONS = [
+  "image.generate",
+  "video.generate",
+  "audio.generate",
+  "image.upscale",
+  "video.upscale"
+];
+var NEXRA_PUBLISHED_MEDIA_OPERATIONS = [
+  "image.generate",
+  "video.generate",
+  "audio.generate",
+  "image.upscale"
+];
+var NEXRA_MEDIA_FEATURES = [
+  "text-to-image",
+  "image-to-image",
+  "image-reference",
+  "image-edit",
+  "image-inpaint",
+  "image-control",
+  "text-to-video",
+  "first-frame",
+  "first-last-frame",
+  "image-to-video",
+  "video-to-video",
+  "audio-to-video",
+  "avatar-video",
+  "reference-image",
+  "reference-video",
+  "reference-audio",
+  "omni-reference",
+  "tts",
+  "music",
+  "sfx",
+  "voice-reference",
+  "scale-factor",
+  "target-resolution"
+];
+var NEXRA_MEDIA_OPERATION_DEFINITIONS = Object.freeze([
+  {
+    operation: "image.generate",
+    status: "active",
+    outputKind: "image",
+    features: ["text-to-image", "image-to-image", "image-reference", "image-edit", "image-inpaint", "image-control"],
+    parameterKeys: ["aspect_ratio", "resolution", "quality", "count", "output_format", "seed"]
+  },
+  {
+    operation: "video.generate",
+    status: "active",
+    outputKind: "video",
+    features: ["text-to-video", "first-frame", "first-last-frame", "image-to-video", "video-to-video", "audio-to-video", "avatar-video", "reference-image", "reference-video", "reference-audio", "omni-reference"],
+    parameterKeys: ["voice", "aspect_ratio", "resolution", "quality", "duration", "generate_audio", "output_format", "seed"]
+  },
+  {
+    operation: "audio.generate",
+    status: "active",
+    outputKind: "audio",
+    features: ["tts", "music", "sfx", "voice-reference"],
+    parameterKeys: ["voice", "language", "duration", "output_format", "sample_rate", "speed", "volume", "pitch", "emotion", "instrumental", "loop", "prompt_influence", "seed"]
+  },
+  {
+    operation: "image.upscale",
+    status: "active",
+    outputKind: "image",
+    features: ["scale-factor", "target-resolution"],
+    parameterKeys: ["scale", "resolution", "output_format", "preserve_details"]
+  },
+  {
+    operation: "video.upscale",
+    status: "hold",
+    outputKind: "video",
+    features: ["scale-factor", "target-resolution"],
+    parameterKeys: ["scale", "resolution", "output_format", "preserve_details"]
+  }
+]);
+var mediaSourceSchema = {
+  oneOf: [
+    { type: "string", minLength: 1 },
+    {
+      type: "object",
+      properties: { assetId: { type: "string", minLength: 1 } },
+      required: ["assetId"],
+      additionalProperties: false
+    }
+  ]
+};
+function textPartSchema(roles) {
+  return {
+    type: "object",
+    properties: {
+      type: { const: "text" },
+      text: { type: "string", minLength: 1 },
+      role: { type: "string", enum: [...roles] }
+    },
+    required: ["type", "text"],
+    additionalProperties: false
+  };
+}
+function mediaPartSchema(type, roles) {
+  return {
+    type: "object",
+    properties: {
+      type: { const: type },
+      source: structuredClone(mediaSourceSchema),
+      role: { type: "string", enum: [...roles] },
+      ...type === "image" ? { name: { type: "string", minLength: 1, maxLength: 64, pattern: "^[^\\s@]+$" } } : {}
+    },
+    required: ["type", "source"],
+    additionalProperties: false
+  };
+}
+function inputSchema(contentItems, properties, contentBounds = {}) {
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties: {
+      content: {
+        type: "array",
+        minItems: contentBounds.minItems ?? 1,
+        ...contentBounds.maxItems === void 0 ? {} : { maxItems: contentBounds.maxItems },
+        items: { oneOf: contentItems.map((item) => structuredClone(item)) },
+        "x-ui": { control: "content-parts", order: 0 }
+      },
+      ...properties
+    },
+    required: ["content"],
+    additionalProperties: false
+  };
+}
+var imagePart = mediaPartSchema("image", ["source", "reference", "first_frame", "last_frame", "mask", "control", "subject", "background"]);
+var videoPart = mediaPartSchema("video", ["source", "reference", "edit", "extend"]);
+var audioPart = mediaPartSchema("audio", ["source", "reference", "voice_reference"]);
+var draftPart = {
+  type: "object",
+  properties: {
+    type: { const: "draft_task" },
+    draft_task: { type: "object", properties: { id: { type: "string", minLength: 1 } }, required: ["id"], additionalProperties: false }
+  },
+  required: ["type", "draft_task"],
+  additionalProperties: false
+};
+var NEXRA_MEDIA_INPUT_SCHEMAS = Object.freeze({
+  "image.generate": inputSchema(
+    [textPartSchema(["prompt", "negative_prompt"]), imagePart],
+    {
+      aspect_ratio: { type: "string", minLength: 1, "x-ui": { order: 10 } },
+      resolution: { type: "string", minLength: 1, "x-ui": { order: 11 } },
+      quality: { type: "string", minLength: 1, "x-ui": { order: 12 } },
+      count: { type: "integer", minimum: 1, "x-ui": { order: 13, control: "number" } },
+      output_format: { type: "string", minLength: 1, "x-ui": { order: 14 } },
+      seed: { type: "integer", minimum: 0, "x-ui": { order: 15, control: "number" } }
+    }
+  ),
+  "video.generate": inputSchema(
+    [textPartSchema(["prompt", "negative_prompt", "script"]), imagePart, videoPart, audioPart, draftPart],
+    {
+      voice: { type: "string", minLength: 1, "x-ui": { order: 9, control: "resource", resource: "voice" } },
+      draft: { type: "boolean", "x-ui": { control: "switch" } },
+      aspect_ratio: { type: "string", minLength: 1, "x-ui": { order: 10 } },
+      resolution: { type: "string", minLength: 1, "x-ui": { order: 11 } },
+      quality: { type: "string", minLength: 1, "x-ui": { order: 12 } },
+      duration: { type: "number", exclusiveMinimum: 0, "x-ui": { order: 13, control: "number" } },
+      generate_audio: { type: "boolean", "x-ui": { order: 14, control: "switch" } },
+      output_format: { type: "string", minLength: 1, "x-ui": { order: 15 } },
+      seed: { type: "integer", minimum: 0, "x-ui": { order: 16, control: "number" } }
+    }
+  ),
+  "audio.generate": inputSchema(
+    [textPartSchema(["prompt", "script", "lyrics"]), audioPart],
+    {
+      voice: { type: "string", minLength: 1, "x-ui": { order: 10, control: "resource", resource: "voice" } },
+      language: { type: "string", minLength: 1, "x-ui": { order: 11 } },
+      duration: { type: "number", exclusiveMinimum: 0, "x-ui": { order: 12, control: "number" } },
+      output_format: { type: "string", minLength: 1, "x-ui": { order: 13 } },
+      sample_rate: { type: "integer", minimum: 1, "x-ui": { order: 14, control: "number" } },
+      speed: { type: "number", exclusiveMinimum: 0, "x-ui": { order: 15, control: "number" } },
+      volume: { type: "number", "x-ui": { order: 16, control: "number" } },
+      pitch: { type: "number", "x-ui": { order: 17, control: "number" } },
+      emotion: { type: "string", minLength: 1, "x-ui": { order: 18 } },
+      instrumental: { type: "boolean", "x-ui": { order: 19, control: "switch" } },
+      loop: { type: "boolean", "x-ui": { order: 20, control: "switch" } },
+      prompt_influence: { type: "number", minimum: 0, maximum: 1, "x-ui": { order: 21, control: "number" } },
+      seed: { type: "integer", minimum: 0, "x-ui": { order: 22, control: "number" } }
+    }
+  ),
+  "image.upscale": inputSchema(
+    [mediaPartSchema("image", ["source"])],
+    {
+      scale: { type: "number", exclusiveMinimum: 1, "x-ui": { order: 10, control: "number" } },
+      resolution: { type: "string", minLength: 1, "x-ui": { order: 11 } },
+      output_format: { type: "string", minLength: 1, "x-ui": { order: 12 } },
+      preserve_details: { type: "boolean", "x-ui": { order: 13, control: "switch" } }
+    },
+    { minItems: 1, maxItems: 1 }
+  )
+});
+function nexraMediaInputSchema(operation) {
+  if (!(operation in NEXRA_MEDIA_INPUT_SCHEMAS)) return void 0;
+  return structuredClone(NEXRA_MEDIA_INPUT_SCHEMAS[operation]);
+}
+function isNexraMediaInput(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const input = value;
+  if ("model" in input) return false;
+  const content = input.content;
+  return Array.isArray(content) && content.length > 0 && content.every((part) => {
+    if (!part || typeof part !== "object" || Array.isArray(part)) return false;
+    if (part.type === "text") return typeof part.text === "string" && part.text.length > 0;
+    if (!["image", "video", "audio"].includes(String(part.type))) return false;
+    if (typeof part.source === "string") return part.source.length > 0;
+    return Boolean(part.source && typeof part.source === "object" && !Array.isArray(part.source) && typeof part.source.assetId === "string" && part.source.assetId.length > 0);
+  });
+}
+function nexraMediaOperationForMode(mode) {
+  if (["text-to-image", "image-to-image"].includes(mode)) return "image.generate";
+  if (["text-to-video", "image-to-video", "multimodal-to-video", "avatar-video"].includes(mode)) return "video.generate";
+  if (["text-to-speech", "text-to-music", "text-to-sfx"].includes(mode)) return "audio.generate";
+  if (mode === "image-upscale") return "image.upscale";
+  return void 0;
+}
+function nexraMediaInputSchemaForMode(mode) {
+  const operation = nexraMediaOperationForMode(mode);
+  const schema = operation ? nexraMediaInputSchema(operation) : void 0;
+  if (!schema) return void 0;
+  const properties = schema.properties;
+  const content = properties.content;
+  const items = content.items;
+  const variants = Array.isArray(items.oneOf) ? items.oneOf : [];
+  if (mode === "avatar-video") {
+    for (const variant of variants) {
+      const variantProperties = variant.properties;
+      if (variantProperties.type.const === "text") {
+        variantProperties.role = { type: "string", enum: ["script"] };
+      }
+    }
+  }
+  const allowed = mode === "text-to-image" || mode === "text-to-video" || mode === "text-to-music" || mode === "text-to-sfx" ? /* @__PURE__ */ new Set(["text"]) : mode === "image-to-image" ? /* @__PURE__ */ new Set(["text", "image"]) : mode === "image-to-video" ? /* @__PURE__ */ new Set(["text", "image", "audio"]) : mode === "text-to-speech" ? /* @__PURE__ */ new Set(["text", "audio"]) : /* @__PURE__ */ new Set(["text", "image", "video", "audio"]);
+  items.oneOf = variants.filter((variant) => allowed.has(String(variant.properties.type.const)));
+  if (mode === "image-to-video") {
+    for (const variant of items.oneOf) {
+      const variantProperties = variant.properties;
+      if (variantProperties.type.const !== "image") continue;
+      variantProperties.role = { type: "string", enum: ["first_frame", "last_frame"] };
+      const required = new Set(Array.isArray(variant.required) ? variant.required.filter((key) => typeof key === "string") : []);
+      required.add("role");
+      variant.required = [...required];
+    }
+  }
+  if (mode === "multimodal-to-video") {
+    for (const variant of items.oneOf) {
+      const variantProperties = variant.properties;
+      const type = String(variantProperties.type.const);
+      if (!["image", "video", "audio"].includes(type)) continue;
+      variantProperties.role = type === "image" ? { type: "string", enum: ["reference", "subject", "background"] } : type === "video" ? { type: "string", enum: ["reference", "edit", "extend"] } : { type: "string", const: "reference" };
+      const required = new Set(Array.isArray(variant.required) ? variant.required.filter((key) => typeof key === "string") : []);
+      required.add("role");
+      variant.required = [...required];
+    }
+  }
+  const requiredMedia = mode === "image-to-image" || mode === "image-to-video" || mode === "avatar-video" ? "image" : void 0;
+  const requiresReferenceMedia = mode === "multimodal-to-video";
+  content.allOf = [
+    ...mode === "avatar-video" ? [] : [{
+      contains: { type: "object", properties: { type: { const: "text" } }, required: ["type"] },
+      minContains: 1
+    }],
+    ...requiredMedia ? [{
+      contains: { type: "object", properties: { type: { const: requiredMedia } }, required: ["type"] },
+      minContains: 1
+    }] : [],
+    ...requiresReferenceMedia ? [{
+      contains: { type: "object", properties: { type: { enum: ["image", "video", "audio"] } }, required: ["type"] },
+      minContains: 1
+    }] : []
+  ];
+  if (mode === "text-to-speech") {
+    properties.voice = { ...properties.voice, "x-ui": { order: 10, control: "resource", resource: "voice" } };
+  }
+  const allowedParameters = mode === "avatar-video" ? /* @__PURE__ */ new Set(["content", "voice", "aspect_ratio", "resolution"]) : mode === "text-to-speech" ? /* @__PURE__ */ new Set(["content", "voice", "language", "output_format", "sample_rate", "speed", "volume", "pitch", "emotion"]) : mode === "text-to-music" ? /* @__PURE__ */ new Set(["content", "duration", "output_format", "instrumental", "prompt_influence", "seed"]) : mode === "text-to-sfx" ? /* @__PURE__ */ new Set(["content", "duration", "output_format", "loop", "prompt_influence", "seed"]) : void 0;
+  if (allowedParameters) {
+    schema.properties = Object.fromEntries(Object.entries(properties).filter(([key]) => allowedParameters.has(key)));
+  }
+  return schema;
+}
+
+// ../contracts/src/tasks.ts
+var TASK_STATUSES = [
+  "queued",
+  "running",
+  "succeeded",
+  "failed",
+  "cancelling",
+  "cancelled"
+];
+var CREATE_TASK_CONTROL_FIELDS = [
+  "model",
+  "callback_url",
+  "metadata",
+  "quoteToken",
+  "submittedAt",
+  "schemaVersion",
+  "webhook"
+];
+function createTaskRequest(model, input, controls = {}) {
+  for (const field of [...CREATE_TASK_CONTROL_FIELDS, "input"]) {
+    if (Object.hasOwn(input, field)) {
+      throw new Error(`Nexra model parameters cannot use reserved Task field: ${field}`);
+    }
+  }
+  return { model, ...input, ...controls };
+}
+function isTerminalTaskStatus(status) {
+  return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+
+// ../contracts/src/ratio-display-order.ts
+function parseRatioParts(value) {
+  const matched = /^\s*(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)\s*$/.exec(value);
+  if (!matched) return void 0;
+  const w = Number(matched[1]);
+  const h = Number(matched[2]);
+  return w > 0 && h > 0 ? { w, h } : void 0;
+}
+function ratioDisplayOrderKey(value) {
+  const normalized = value.trim();
+  const parts = parseRatioParts(normalized);
+  if (!parts) {
+    const auto = normalized.toLowerCase() === "auto" ? 0 : 1;
+    return [0, auto, 0, 0, value];
+  }
+  if (parts.w === parts.h) return [1, 0, 0, 0, value];
+  const long = Math.max(parts.w, parts.h);
+  const short = Math.min(parts.w, parts.h);
+  const landscape = parts.w > parts.h ? 1 : 0;
+  return short === 1 ? [3, long, landscape, -short, value] : [2, long, landscape, -short, value];
+}
+function compareRatioDisplayOrder(a, b) {
+  const ka = ratioDisplayOrderKey(a);
+  const kb = ratioDisplayOrderKey(b);
+  for (let index = 0; index < ka.length; index += 1) {
+    if (ka[index] !== kb[index]) return ka[index] < kb[index] ? -1 : 1;
+  }
+  return 0;
+}
+function sortRatioDisplayOrder(values) {
+  return [...values].sort(compareRatioDisplayOrder);
+}
+
+export {
+  MEDIA_KINDS,
+  NEXRA_MEDIA_API_VERSION,
+  NEXRA_GENERATION_OPERATIONS,
+  NEXRA_MEDIA_OPERATIONS,
+  NEXRA_PUBLISHED_MEDIA_OPERATIONS,
+  NEXRA_MEDIA_FEATURES,
+  NEXRA_MEDIA_OPERATION_DEFINITIONS,
+  NEXRA_MEDIA_INPUT_SCHEMAS,
+  nexraMediaInputSchema,
+  isNexraMediaInput,
+  nexraMediaOperationForMode,
+  nexraMediaInputSchemaForMode,
+  TASK_STATUSES,
+  createTaskRequest,
+  isTerminalTaskStatus,
+  sortRatioDisplayOrder
+};