@byte_fluffy/nexra-sdk 0.1.0-alpha.29 → 0.1.0-alpha.30

package/README.md

@@ -37,6 +37,65 @@ 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

package/dist/{assets-dUJMQNJD.d.ts → assets-Cusrjj7_.d.ts}

@@ -1,4 +1,4 @@
-import { J as JsonObject } from './json-Drjj1OKl.js';
+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];
@@ -58,4 +58,4 @@ interface AssetCertificationWaitOptions {
     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 };
+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,6 +1,6 @@
-import { J as JsonObject } from './json-Drjj1OKl.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 NexraModelEndpointSpec, j as NexraModelSpecFilter } from './media-geometry-nJ7I7ohO.js';
-export { M as MediaGeometryField, k as MediaGeometryProjection, l as NexraBillingCurrency, m as NexraCatalogModelIdentity, 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-nJ7I7ohO.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;
 

package/dist/catalog.js

@@ -9,8 +9,8 @@ import {
   listModelSpecs,
   projectMediaGeometry,
   resolveNexraLanguageReasoning
-} from "./chunk-ESV6ODRA.js";
-import "./chunk-IEBCNRT4.js";
+} from "./chunk-3CF6PDT3.js";
+import "./chunk-DKQZWIQ7.js";
 export {
   CatalogClient,
   applyMediaGeometry,

package/dist/{chunk-ESV6ODRA.js → chunk-3CF6PDT3.js}

@@ -1,6 +1,8 @@
 import {
+  normalizePublicErrorInput,
+  pickPublicErrorFields,
   sortRatioDisplayOrder
-} from "./chunk-IEBCNRT4.js";
+} from "./chunk-DKQZWIQ7.js";
 
 // src/catalog/generated/audio.generated.json
 var audio_generated_default = [
@@ -50341,27 +50343,98 @@ function applyNoWatermark(inputSchema, input) {
 // src/errors.ts
 var NexraApiError = class extends Error {
   status;
-  code;
-  requestId;
-  retryable;
-  details;
+  nexraError;
+  nexraRequestId;
+  nexraHttpStatus;
+  upstreamHttpStatus;
+  upstreamRequestId;
+  upstreamError;
+  upstreamRedacted;
+  upstreamTruncated;
+  upstreamUnavailableReason;
+  upstreamFormat;
+  upstreamEvent;
   constructor(message, options) {
-    super(message);
+    const classification = options.nexraError ?? { code: options.code ?? "api_error", message };
+    const { nexraError, ...metadata } = pickPublicErrorFields({ ...options, nexraError: classification });
+    super(nexraError?.message ?? message);
     this.name = "NexraApiError";
     this.status = options.status;
-    this.code = options.code ?? "api_error";
-    this.requestId = options.requestId;
-    this.retryable = options.retryable ?? false;
-    this.details = options.details;
+    this.nexraError = nexraError ?? classification;
+    Object.assign(this, metadata);
+  }
+  get code() {
+    return this.nexraError.code;
+  }
+  /** @deprecated Use nexraRequestId. */
+  get requestId() {
+    return this.nexraRequestId;
+  }
+  /** @deprecated Use nexraError.param. */
+  get details() {
+    return this.nexraError.param ? { param: this.nexraError.param } : void 0;
   }
 };
 var NexraTaskError = class extends Error {
   task;
   constructor(task) {
-    super(task.error?.message ?? `Task ${task.id} ended with status ${task.status}`);
+    const fields = pickPublicErrorFields(task);
+    const legacyMessage = Object.hasOwn(task, "nexraError") ? void 0 : task.error?.message;
+    super(fields.nexraError?.message ?? legacyMessage ?? `Task ${task.id} ended with status ${task.status}`);
     this.name = "NexraTaskError";
     this.task = task;
   }
+  get nexraError() {
+    return this.publicFields.nexraError;
+  }
+  get code() {
+    return this.nexraError?.code;
+  }
+  /** @deprecated Use nexraError.param. */
+  get details() {
+    const param = this.nexraError?.param;
+    return param ? { param } : void 0;
+  }
+  /** @deprecated Use nexraRequestId. */
+  get requestId() {
+    return this.nexraRequestId;
+  }
+  get nexraRequestId() {
+    return this.publicFields.nexraRequestId;
+  }
+  get nexraHttpStatus() {
+    return this.publicFields.nexraHttpStatus;
+  }
+  get upstreamHttpStatus() {
+    return this.publicFields.upstreamHttpStatus;
+  }
+  get upstreamRequestId() {
+    return this.publicFields.upstreamRequestId;
+  }
+  get upstreamError() {
+    return this.publicFields.upstreamError;
+  }
+  get upstreamRedacted() {
+    return this.publicFields.upstreamRedacted;
+  }
+  get upstreamTruncated() {
+    return this.publicFields.upstreamTruncated;
+  }
+  get upstreamUnavailableReason() {
+    return this.publicFields.upstreamUnavailableReason;
+  }
+  get upstreamFormat() {
+    return this.publicFields.upstreamFormat;
+  }
+  get upstreamEvent() {
+    return this.publicFields.upstreamEvent;
+  }
+  get publicFields() {
+    return pickPublicErrorFields(this.task);
+  }
+  get taskId() {
+    return this.task.id;
+  }
 };
 var NexraWaitTimeoutError = class extends Error {
   taskId;
@@ -50375,7 +50448,7 @@ var NexraWaitTimeoutError = class extends Error {
 };
 
 // src/generated/version.generated.ts
-var SDK_VERSION = "0.1.0-alpha.29";
+var SDK_VERSION = "0.1.0-alpha.30";
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.nexra-ai.com/v1";
@@ -50475,13 +50548,18 @@ async function createApiError(response) {
     payload = await response.clone().json();
   } catch {
   }
-  const error = payload?.error;
-  return new NexraApiError(error?.message ?? `Nexra API returned HTTP ${response.status}`, {
+  const requestId = response.headers.get("x-request-id") ?? void 0;
+  const normalized = normalizePublicErrorInput(payload, { nexraRequestId: requestId, nexraHttpStatus: response.status });
+  const owner = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  const candidate = Object.hasOwn(owner, "nexraError") ? owner.nexraError : owner.error ?? owner;
+  const error = candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : {};
+  const message = normalized?.nexraError.message ?? (typeof error.message === "string" ? error.message : `Nexra API returned HTTP ${response.status}`);
+  return new NexraApiError(message, {
+    ...normalized,
     status: response.status,
-    code: error?.code,
-    requestId: error?.requestId ?? response.headers.get("x-request-id") ?? void 0,
-    retryable: error?.retryable ?? shouldRetryStatus(response.status),
-    details: error?.details
+    code: normalized?.nexraError.code ?? (typeof error.code === "string" ? error.code : void 0),
+    nexraRequestId: normalized?.nexraRequestId ?? requestId,
+    nexraHttpStatus: normalized ? normalized.nexraHttpStatus : requestId ? response.status : void 0
   });
 }
 function isSafeMethod(method) {