@imgly/plugin-ai-generation-web 1.79.0 → 1.80.0-hotfix-mcp.0

package/dist/gateway/GatewayError.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Typed representation of a failed IMG.LY gateway request.
+ *
+ * The gateway answers every failure with a single JSON envelope:
+ *
+ * ```json
+ * { "error": { "code": "insufficient_credits", "message": "Insufficient credits" } }
+ * ```
+ *
+ * Provider-originated failures add two more fields:
+ *
+ * ```json
+ * { "error": { "code": "upstream_error", "message": "Rate limit exceeded",
+ *              "provider": "fal.ai", "upstream_status": 429 } }
+ * ```
+ *
+ * This module turns that envelope into an `Error` subclass so callers can branch
+ * on `code` instead of pattern-matching a message string.
+ */
+/**
+ * Machine-readable failure reason reported by the gateway.
+ *
+ * The listed members mirror the gateway's own error catalog, but the type stays
+ * open on purpose: the gateway may introduce codes before this package is
+ * updated, and a closed union would silently mistype them.
+ *
+ * Two members are client-side sentinels rather than gateway codes: `'unknown'`
+ * when no code could be determined (unparseable body, non-gateway origin such as
+ * the presigned upload URL), and `'network_error'` when the request never
+ * produced a readable response at all.
+ */
+export type GatewayErrorCode = 'network_error' | 'insufficient_credits' | 'unauthorized' | 'provider_not_authorized' | 'invalid_request' | 'invalid_model_id' | 'validation_error' | 'provider_not_supported' | 'model_not_found' | 'provider_unavailable' | 'upstream_error' | 'generation_failed' | 'timeout' | 'internal_error' | 'service_error' | 'unknown' | (string & {});
+/** Which gateway interaction failed. */
+export type GatewayOperation = 'schema' | 'upload' | 'generate';
+export interface GatewayErrorInit {
+    code: GatewayErrorCode;
+    status: number;
+    operation: GatewayOperation;
+    /** Message reported by the gateway, used to build the developer-facing text. */
+    detail?: string;
+    provider?: string;
+    upstreamStatus?: number;
+    requestId?: string;
+}
+export declare class GatewayError extends Error {
+    /** Machine-readable failure reason. Prefer this over parsing `message`. */
+    readonly code: GatewayErrorCode;
+    /**
+     * HTTP status of the failed response. `0` when there is no status: a failure
+     * reported inside an already-open SSE stream, or a request that never reached
+     * the gateway (`network_error`).
+     */
+    readonly status: number;
+    /** Which gateway interaction failed. */
+    readonly operation: GatewayOperation;
+    /** Upstream model provider, present only for `upstream_error`. */
+    readonly provider?: string;
+    /** Status the upstream provider returned, present only for `upstream_error`. */
+    readonly upstreamStatus?: number;
+    /**
+     * Gateway request id. Include this when reporting a problem to support.
+     *
+     * Only present when the gateway makes it reachable: `x-request-id` is not a
+     * CORS-safelisted response header, so a cross-origin gateway must send
+     * `Access-Control-Expose-Headers: x-request-id` for the header to be readable
+     * — otherwise the id has to travel in the error body as `request_id`.
+     */
+    readonly requestId?: string;
+    constructor(init: GatewayErrorInit);
+}
+/**
+ * Narrows an unknown thrown value to a `GatewayError`.
+ *
+ * Uses a structural check rather than `instanceof` so it keeps working when the
+ * plugin packages are bundled separately and end up with distinct copies of this
+ * module.
+ */
+export declare function isGatewayError(error: unknown): error is GatewayError;
+/**
+ * Builds a `GatewayError` from a non-OK response.
+ *
+ * Consumes the response body, so call this only once per response.
+ */
+export declare function gatewayErrorFromResponse(response: Response, operation: GatewayOperation): Promise<GatewayError>;
+/**
+ * Builds a `GatewayError` for a request that never produced a readable response.
+ *
+ * `fetch` rejects instead of resolving when the request did not complete at all:
+ * the client is offline, DNS or TLS failed, the gateway is unreachable — or the
+ * browser blocked the response because it carried no CORS headers. The last case
+ * is indistinguishable from the others by design (the browser withholds the
+ * details) and is the most likely one in production, since an error page served
+ * by an edge proxy in front of the gateway will not add
+ * `Access-Control-Allow-Origin`. Whatever the cause, the failure is not a
+ * generation failure, and telling the user to try generating again is the wrong
+ * advice — so it gets its own code and its own copy.
+ */
+export declare function gatewayNetworkError(reason: unknown, operation: GatewayOperation): GatewayError;

package/dist/gateway/gatewayErrorNotification.d.ts

@@ -0,0 +1,29 @@
+import type { NotificationDuration } from '@cesdk/cesdk-js';
+/**
+ * Translation key shown when nothing more specific applies. Also the documented
+ * fallback inside `handleGenerationError`.
+ */
+export declare const GENERIC_FAILURE_KEY = "common.ai-generation.failed";
+/**
+ * Picks the translation key for a failed generation.
+ *
+ * Non-gateway errors fall through to the generic key rather than surfacing
+ * their raw message, which is usually a third-party string.
+ */
+export declare function getGatewayErrorMessageKey(error: unknown): string;
+/**
+ * Default `output.notification.error` configuration for gateway providers.
+ *
+ * Integrators who want different copy, or an action button pointing at their
+ * own billing page, add an error-handling middleware — see the "Custom Error
+ * Handling Middleware" section of the AI integration guide. A middleware can
+ * call `options.preventDefault()` to suppress this notification entirely.
+ */
+export declare function createGatewayErrorNotification<I>(): {
+    show: true;
+    message: (context: {
+        input?: I;
+        error: unknown;
+    }) => string;
+    duration: NotificationDuration;
+};

package/dist/gateway/index.d.ts

@@ -1,3 +1,4 @@
 export { createGatewayProvider } from './createGatewayProvider';
 export { createGatewayClient, type GatewayClient } from './createGatewayClient';
+export { GatewayError, isGatewayError, type GatewayErrorCode, type GatewayOperation } from './GatewayError';
 export type { GatewayCapability, GatewayProviderConfiguration, GatewayProviderOptions, GatewayInput, GatewaySchemaResult, GatewaySSEOutput, GatewaySSECompletedData, GatewaySSEDeltaData, GatewaySSEFailedData, GatewayUploadResult } from './types';

package/dist/gateway/types.d.ts

@@ -211,6 +211,16 @@ export interface GatewaySSEFailedData {
     status: 'failed';
     error: {
         message: string;
+        /**
+         * Same catalog as the HTTP error envelope. Optional because the gateway does
+         * not put it on every failed event yet — without it the client can report
+         * that the generation failed, but not why.
+         */
+        code?: string;
+        /** Upstream model provider, for provider-originated failures. */
+        provider?: string;
+        /** Status the upstream provider returned. */
+        upstream_status?: number;
     };
 }
 export interface GatewaySSEDeltaData {

package/dist/generation/createGenerateFunction.d.ts

@@ -15,6 +15,12 @@ export type ResultSuccess<O> = {
 export type Result<O> = ResultSuccess<O> | {
     status: 'error';
     message: string;
+    /**
+     * The value that was thrown, preserved so consumers can inspect it
+     * instead of pattern-matching `message`. Gateway failures carry a
+     * `GatewayError` here — narrow it with `isGatewayError`.
+     */
+    error?: unknown;
     middlewareOptions?: GenerationOptions;
 } | {
     status: 'aborted';

package/dist/index.d.ts

@@ -31,5 +31,6 @@ export { extractAndSetSchemaTranslations } from './openapi/extractSchemaTranslat
 export { AI_EDIT_MODE, AI_METADATA_KEY } from './ui/quickActions/utils';
 export { createGatewayProvider } from './gateway/createGatewayProvider';
 export { createGatewayClient, type GatewayClient } from './gateway/createGatewayClient';
+export { GatewayError, isGatewayError, type GatewayErrorCode, type GatewayOperation } from './gateway/GatewayError';
 export type { GatewayProviderConfiguration, GatewayProviderOptions, GatewayInput, GatewaySchemaResult, GatewaySSEOutput, GatewaySSECompletedData, GatewaySSEDeltaData, GatewaySSEFailedData, GatewayUploadResult, GatewayTokenActionResult } from './gateway/types';
 export { setDefaultTranslations, createTranslationCallback, buildTranslationKeys } from './utils/translationHelpers';