@anuragpal02/zcl-contracts 0.29.0 → 0.30.0

package/dist/generation.d.ts

@@ -255,6 +255,40 @@ export declare const panelVideoDescriptorSchema: z.ZodDiscriminatedUnion<[z.ZodO
     nativeH: z.ZodNumber;
     mode: z.ZodLiteral<"mirror">;
 }, z.core.$strip>], "mode">;
+/**
+ * Why a job failed, in a form a client may map to human copy.
+ *
+ * A CLOSED set, deliberately. The server stores its failure reasons in two
+ * places and neither is safe to forward verbatim:
+ *   - `generation_job_events.data.reason` — written by EVERY failure path, but
+ *     heterogeneous: the image paths store short codes, while the video paths
+ *     store `err.message.slice(0, 200)`, an arbitrary provider exception that
+ *     can carry an endpoint URL or a request id.
+ *   - `generation_job_steps.error` — short codes, but the IMAGE paths only; it
+ *     covers no video failure and no reconciler-reaped job.
+ *
+ * Because something must map either way, the mapping lives at the API boundary
+ * and this enum makes it total: a value nobody mapped cannot reach a client, it
+ * degrades to `unknown`. That containment is structural rather than a matter of
+ * reviewer discipline — the next person to add a workflow cannot leak by
+ * default.
+ *
+ * Members name the USER'S SITUATION, not the system's fault, so client copy
+ * falls out of the code almost mechanically. The test: if a member's best copy
+ * is "something went wrong", it belongs in `internal_error`.
+ */
+export declare const generationFailureReasonSchema: z.ZodEnum<{
+    internal_error: "internal_error";
+    unknown: "unknown";
+    prompt_blocked: "prompt_blocked";
+    content_blocked: "content_blocked";
+    no_image: "no_image";
+    invalid_request: "invalid_request";
+    provider_unavailable: "provider_unavailable";
+    source_missing: "source_missing";
+    panel_geometry_missing: "panel_geometry_missing";
+    timed_out: "timed_out";
+}>;
 export declare const generationJobSchema: z.ZodObject<{
     id: z.ZodString;
     workspaceId: z.ZodString;
@@ -291,6 +325,18 @@ export declare const generationJobSchema: z.ZodObject<{
     sourceAssetIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
     parentJobId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     variantGroupId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    failureReason: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+        internal_error: "internal_error";
+        unknown: "unknown";
+        prompt_blocked: "prompt_blocked";
+        content_blocked: "content_blocked";
+        no_image: "no_image";
+        invalid_request: "invalid_request";
+        provider_unavailable: "provider_unavailable";
+        source_missing: "source_missing";
+        panel_geometry_missing: "panel_geometry_missing";
+        timed_out: "timed_out";
+    }>>>;
 }, z.core.$strip>;
 export declare const createGenerationJobRequestSchema: z.ZodObject<{
     prompt: z.ZodString;
@@ -343,6 +389,18 @@ export declare const generationJobResponseSchema: z.ZodObject<{
         sourceAssetIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
         parentJobId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         variantGroupId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        failureReason: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            internal_error: "internal_error";
+            unknown: "unknown";
+            prompt_blocked: "prompt_blocked";
+            content_blocked: "content_blocked";
+            no_image: "no_image";
+            invalid_request: "invalid_request";
+            provider_unavailable: "provider_unavailable";
+            source_missing: "source_missing";
+            panel_geometry_missing: "panel_geometry_missing";
+            timed_out: "timed_out";
+        }>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const createSmartVideoResponseSchema: z.ZodObject<{
@@ -383,6 +441,18 @@ export declare const createSmartVideoResponseSchema: z.ZodObject<{
             sourceAssetIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
             parentJobId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
             variantGroupId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            failureReason: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+                internal_error: "internal_error";
+                unknown: "unknown";
+                prompt_blocked: "prompt_blocked";
+                content_blocked: "content_blocked";
+                no_image: "no_image";
+                invalid_request: "invalid_request";
+                provider_unavailable: "provider_unavailable";
+                source_missing: "source_missing";
+                panel_geometry_missing: "panel_geometry_missing";
+                timed_out: "timed_out";
+            }>>>;
         }, z.core.$strip>;
         videoPlan: z.ZodObject<{
             jobs: z.ZodArray<z.ZodObject<{
@@ -502,6 +572,18 @@ export declare const createPanelSetResponseSchema: z.ZodObject<{
         sourceAssetIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
         parentJobId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         variantGroupId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        failureReason: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            internal_error: "internal_error";
+            unknown: "unknown";
+            prompt_blocked: "prompt_blocked";
+            content_blocked: "content_blocked";
+            no_image: "no_image";
+            invalid_request: "invalid_request";
+            provider_unavailable: "provider_unavailable";
+            source_missing: "source_missing";
+            panel_geometry_missing: "panel_geometry_missing";
+            timed_out: "timed_out";
+        }>>>;
     }, z.core.$strip>;
     panels: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         jobId: z.ZodString;
@@ -579,6 +661,18 @@ export declare const listGenerationJobsResponseSchema: z.ZodObject<{
         sourceAssetIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
         parentJobId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         variantGroupId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        failureReason: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            internal_error: "internal_error";
+            unknown: "unknown";
+            prompt_blocked: "prompt_blocked";
+            content_blocked: "content_blocked";
+            no_image: "no_image";
+            invalid_request: "invalid_request";
+            provider_unavailable: "provider_unavailable";
+            source_missing: "source_missing";
+            panel_geometry_missing: "panel_geometry_missing";
+            timed_out: "timed_out";
+        }>>>;
     }, z.core.$strip>>;
     pagination: z.ZodObject<{
         nextCursor: z.ZodNullable<z.ZodString>;
@@ -602,6 +696,7 @@ export type PanelPlanEntry = z.infer<typeof panelPlanEntrySchema>;
 export type VideoPlan = z.infer<typeof videoPlanSchema>;
 export type PanelVideoDescriptor = z.infer<typeof panelVideoDescriptorSchema>;
 export type CreateSmartVideoResponse = z.infer<typeof createSmartVideoResponseSchema>;
+export type GenerationFailureReason = z.infer<typeof generationFailureReasonSchema>;
 export type GenerationJob = z.infer<typeof generationJobSchema>;
 export type CreateGenerationJobRequest = z.input<typeof createGenerationJobRequestSchema>;
 export type ListGenerationJobsQuery = z.input<typeof listGenerationJobsQuerySchema>;

package/dist/generation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../src/generation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,yBAAyB;;;;;;EAAmE,CAAA;AAEzG,eAAO,MAAM,uBAAuB;;;;;;;;;;;EAWlC,CAAA;AAKF,eAAO,MAAM,iBAAiB;;;EAA2B,CAAA;AAEzD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;iBAoBpC,CAAA;AAEF,eAAO,MAAM,8BAA8B;;;;;iBAKzC,CAAA;AAEF,eAAO,MAAM,2BAA2B;;;;iBAItC,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;iBAK9B,CAAA;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;iBAWvC,CAAA;AAKF,eAAO,MAAM,+BAA+B;;;iBAG1C,CAAA;AAKF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;iBAUxC,CAAA;AAKF,eAAO,MAAM,eAAe;;;EAA0B,CAAA;AACtD,eAAO,MAAM,iBAAiB;;;EAA2B,CAAA;AAEzD,eAAO,MAAM,oBAAoB;;;;;;;iBAO/B,CAAA;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAWzB,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;iBAU/B,CAAA;AAEF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW1B,CAAA;AAgBF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAIrC,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4B9B,CAAA;AAEF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;iBAA4B,CAAA;AAEzE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAwC,CAAA;AAGhF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK1C,CAAA;AAeD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;2BAIhC,CAAA;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEvC,CAAA;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;iBAMxC,CAAA;AAEF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG3C,CAAA;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAC3E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AACvE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAC3D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAC3E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAA;AACrF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAC/E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC/D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AACjF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA;AACvF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAA;AACnF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAC3D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACjE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AACrD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACjE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AACvD,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAC7E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAA;AACrF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC/D,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAA;AACzF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAA;AACnF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAC/E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAA;AACzF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AACnE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA"}
+{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../src/generation.ts"],"names":[],"mappings":"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"}

package/dist/generation.js

@@ -153,6 +153,55 @@ export const panelVideoDescriptorSchema = z.discriminatedUnion('mode', [
     z.object({ mode: z.literal('reuse'), ...panelVideoDescriptorBase, assetId: idSchema }),
     z.object({ mode: z.literal('mirror'), ...panelVideoDescriptorBase, sourcePanelId: ledPanelIdSchema })
 ]);
+/**
+ * Why a job failed, in a form a client may map to human copy.
+ *
+ * A CLOSED set, deliberately. The server stores its failure reasons in two
+ * places and neither is safe to forward verbatim:
+ *   - `generation_job_events.data.reason` — written by EVERY failure path, but
+ *     heterogeneous: the image paths store short codes, while the video paths
+ *     store `err.message.slice(0, 200)`, an arbitrary provider exception that
+ *     can carry an endpoint URL or a request id.
+ *   - `generation_job_steps.error` — short codes, but the IMAGE paths only; it
+ *     covers no video failure and no reconciler-reaped job.
+ *
+ * Because something must map either way, the mapping lives at the API boundary
+ * and this enum makes it total: a value nobody mapped cannot reach a client, it
+ * degrades to `unknown`. That containment is structural rather than a matter of
+ * reviewer discipline — the next person to add a workflow cannot leak by
+ * default.
+ *
+ * Members name the USER'S SITUATION, not the system's fault, so client copy
+ * falls out of the code almost mechanically. The test: if a member's best copy
+ * is "something went wrong", it belongs in `internal_error`.
+ */
+export const generationFailureReasonSchema = z.enum([
+    /** The prompt tripped a safety filter. Actionable: reword it. */
+    'prompt_blocked',
+    /** The OUTPUT tripped a safety filter. Actionable: reword or retry. */
+    'content_blocked',
+    /** The model answered without an image. Actionable: retry or reword. */
+    'no_image',
+    /** The request itself was rejected as invalid. Rarely user-actionable. */
+    'invalid_request',
+    /** Provider down / rate-limited / unreachable. Actionable: just retry. */
+    'provider_unavailable',
+    /** A required source image (edit parent, panel master) could not be read. */
+    'source_missing',
+    /**
+     * A panel job carried no pinned geometry. Kept DISTINCT from internal_error
+     * because the user can act on it — re-run the LED map step — and telling
+     * someone "something went wrong" when the fix is one click away is precisely
+     * the failure this field exists to end.
+     */
+    'panel_geometry_missing',
+    /** Ours, and nothing the user can do. Misconfiguration, bugs, bad state. */
+    'internal_error',
+    /** Reaped for exceeding its budget without finishing. Actionable: retry. */
+    'timed_out',
+    /** Unmapped. The fallback that makes the set total; never leaks a raw value. */
+    'unknown'
+]);
 export const generationJobSchema = z.object({
     id: idSchema,
     workspaceId: idSchema,
@@ -180,7 +229,16 @@ export const generationJobSchema = z.object({
     runId: idSchema.nullable().default(null),
     sourceAssetIds: z.array(idSchema).default([]),
     parentJobId: idSchema.nullable().default(null),
-    variantGroupId: idSchema.nullable().default(null)
+    variantGroupId: idSchema.nullable().default(null),
+    /**
+     * Why this job failed. Null on every non-failed job, and null on a failed job
+     * whose reason could not be determined. Defaults so pre-0.30 payloads parse —
+     * which, per the `z.infer` note above, makes it a REQUIRED output field and so
+     * a compile error in `mapJob` and the fixtures until they are updated. That is
+     * the point: the alternative is another field silently emitting null for
+     * months, as `ledMapId` did.
+     */
+    failureReason: generationFailureReasonSchema.nullable().default(null)
 });
 export const createGenerationJobRequestSchema = imageGenerateParamsSchema;
 export const generationJobResponseSchema = apiSuccessSchema(generationJobSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuragpal02/zcl-contracts",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",