@fungi.computer/darkroom 0.3.1 → 0.4.0

package/dist/server.js

@@ -1,7 +1,9 @@
 import { mediaPendingSchema } from "./media-binding.js";
+export { estimateMediaModel } from "./cloudflare/provider.js";
 export { mediaPendingSchema, mediaBindingCallSchema, mediaBindingGenerationSchema, mediaImageBindingInputSchema, mediaVideoBindingInputSchema, parseMediaBindingCall, mediaBindingRequest, readMediaBindingReply, } from "./media-binding.js";
 import { Hono } from "hono";
 import { z } from "zod";
+import { AppError, describeAppError } from "@fungi.computer/agar/errors";
 import * as Effect from "effect/Effect";
 import * as Result from "effect/Result";
 import { runMediaGeneration } from "./media-generation.js";
@@ -47,7 +49,10 @@ const headers = {
 function failure(error, refusalMessages) {
     if (error instanceof MediaSafetyFilterRefusal)
         return Response.json({
-            error: "The model's safety filter refused this prompt — try rewording.",
+            error: describeAppError(new AppError(error.message, {
+                code: "SAFETY_FILTER_REFUSED",
+                retryable: false,
+            })).message,
             stage: "provider",
             code: "SAFETY_FILTER_REFUSED",
             retryable: false,
@@ -56,7 +61,7 @@ function failure(error, refusalMessages) {
     if (error instanceof MediaExecutionError &&
         error.cause instanceof MediaOutputFormatMismatch)
         return Response.json({
-            error: "Media provider did not return the requested image format; nothing was saved or charged. Start a new request.",
+            error: "Media provider did not return the requested image format; nothing was saved. Start a new request.",
             stage: error.stage,
             code: "HOST_FAILURE",
             retryable: false,
@@ -90,13 +95,27 @@ function failure(error, refusalMessages) {
             status: 400,
             headers,
         });
+    if (error.stage === "provider") {
+        const code = error.customerCharge === "none"
+            ? "MEDIA_PROVIDER_FAILURE_UNCHARGED"
+            : "MEDIA_PROVIDER_FAILURE";
+        return Response.json({
+            error: describeAppError(new AppError(error.message, {
+                code,
+                retryable: false,
+            })).message,
+            stage: error.stage,
+            code,
+            retryable: false,
+            provider: error.provider,
+        }, { status: 503, headers });
+    }
     const messages = {
         "generation-authorization": "Media generation permission could not be checked; try again.",
         "destination-authorization": "Media destination permission could not be checked; try again.",
         "destination-write": "Media generated an image but could not save it; retry this request to save the retained result.",
         estimate: "Media could not prepare the image inputs or estimate their cost; check the reference files and retry.",
         billing: "Media billing is unavailable; retry this request.",
-        provider: "Media provider failed; nothing was charged. Start a new request.",
         normalization: "Media provider returned an unusable image; start a new request only after checking provider status.",
         artifact: "Media generated output could not be retained or read; try again.",
         operation: "Media operation is unresolved; try again.",
@@ -105,7 +124,7 @@ function failure(error, refusalMessages) {
         error: messages[error.stage],
         stage: error.stage,
         code: "HOST_FAILURE",
-        retryable: error.stage !== "normalization" && error.stage !== "provider",
+        retryable: error.stage !== "normalization",
         provider: error instanceof MediaExecutionError ? error.provider : undefined,
     }, {
         status: 503,

package/docs/api/app-media-contracts.md

@@ -10,10 +10,202 @@
 
 ## Variables
 
+### mediaModelPriceEstimateSchema
+
+```ts
+const mediaModelPriceEstimateSchema: ZodObject<{
+  kind: ZodLiteral<"estimate">;
+  basis: ZodEnum<{
+     provider-cost: "provider-cost";
+     team-price: "team-price";
+  }>;
+  costMilliunits: ZodNumber;
+  settings: ZodObject<{
+     model: ZodString;
+     prompt: ZodString;
+     width: ZodNumber;
+     height: ZodNumber;
+     steps: ZodOptional<ZodNumber>;
+     durationSeconds: ZodOptional<ZodNumber>;
+     resolution: ZodOptional<ZodEnum<{
+        p480: "480p";
+        p720: "720p";
+        p768: "768p";
+        p1080: "1080p";
+        p4k: "4k";
+     }>>;
+     aspectRatio: ZodOptional<ZodEnum<{
+        wide: "16:9";
+        landscape: "4:3";
+        square: "1:1";
+        portrait: "3:4";
+        tall: "9:16";
+        ultrawide: "21:9";
+        ultratall: "9:21";
+     }>>;
+     generateAudio: ZodOptional<ZodBoolean>;
+     references: ZodOptional<ZodArray<ZodObject<{
+        computerId: ZodString;
+        path: ZodString;
+        role: ZodOptional<ZodEnum<{
+           first: ...;
+           last: ...;
+           reference: ...;
+        }>>;
+     }, $strict>>>;
+  }, $strict>;
+}, $strict>;
+```
+
+A labelled estimate for one explicitly described generation, never a receipt.
+
+---
+
+### mediaCatalogModelSchema
+
+```ts
+const mediaCatalogModelSchema: ZodReadonly<ZodObject<{
+  priceEstimate: ZodOptional<ZodObject<{
+     kind: ZodLiteral<"estimate">;
+     basis: ZodEnum<{
+        provider-cost: "provider-cost";
+        team-price: "team-price";
+     }>;
+     costMilliunits: ZodNumber;
+     settings: ZodObject<{
+        model: ZodString;
+        prompt: ZodString;
+        width: ZodNumber;
+        height: ZodNumber;
+        steps: ZodOptional<ZodNumber>;
+        durationSeconds: ZodOptional<ZodNumber>;
+        resolution: ZodOptional<ZodEnum<{
+           p480: ...;
+           p720: ...;
+           p768: ...;
+           p1080: ...;
+           p4k: ...;
+        }>>;
+        aspectRatio: ZodOptional<ZodEnum<{
+           wide: ...;
+           landscape: ...;
+           square: ...;
+           portrait: ...;
+           tall: ...;
+           ultrawide: ...;
+           ultratall: ...;
+        }>>;
+        generateAudio: ZodOptional<ZodBoolean>;
+        references: ZodOptional<ZodArray<ZodObject<..., ...>>>;
+     }, $strict>;
+  }, $strict>>;
+  id: ZodString;
+  label: ZodString;
+  kind: ZodEnum<{
+     image: "image";
+     video: "video";
+  }>;
+  tier: ZodEnum<{
+     draft: "draft";
+     balanced: "balanced";
+     premium: "premium";
+     max: "max";
+  }>;
+  outputFormats: ZodReadonly<ZodArray<ZodEnum<{
+     png: "png";
+     jpeg: "jpeg";
+     webp: "webp";
+  }>>>;
+  maxPromptLength: ZodNumber;
+  input: ZodLazy<ZodReadonly<ZodObject<{
+     transport: ZodEnum<{
+        json: "json";
+        multipart: "multipart";
+     }>;
+     dimensions: ZodEnum<{
+        none: "none";
+        own: "own";
+     }>;
+     maxDimension: ZodNullable<ZodNumber>;
+     maxDimensionDocumented: ZodBoolean;
+     defaultWidth: ZodNumber;
+     defaultHeight: ZodNumber;
+     steps: ZodEnum<{
+        steps: "steps";
+        num_steps: "num_steps";
+        fixed: "fixed";
+     }>;
+     maxSteps: ZodNullable<ZodNumber>;
+     defaultSteps: ZodNullable<ZodNumber>;
+     referenceField: ZodNullable<ZodString>;
+     maxReferences: ZodNumber;
+  }, $strict>>>;
+  sizes: ZodNullable<ZodReadonly<ZodArray<ZodString>>>;
+  video: ZodNullable<ZodLazy<ZodReadonly<ZodObject<{
+     minSeconds: ZodNumber;
+     maxSeconds: ZodNumber;
+     defaultSeconds: ZodNumber;
+     durations: ZodReadonly<ZodArray<ZodNumber>>;
+     provider: ZodEnum<{
+        seedance: "seedance";
+        veo: "veo";
+        minimax: "minimax";
+     }>;
+     formats: ZodReadonly<ZodArray<ZodLazy<...>>>;
+     defaultResolution: ZodEnum<{
+        p480: "480p";
+        p720: "720p";
+        p768: "768p";
+        p1080: "1080p";
+        p4k: "4k";
+     }>;
+     defaultAspectRatio: ZodEnum<{
+        wide: "16:9";
+        landscape: "4:3";
+        square: "1:1";
+        portrait: "3:4";
+        tall: "9:16";
+        ultrawide: "21:9";
+        ultratall: "9:21";
+     }>;
+     supportsAudio: ZodBoolean;
+     defaultGenerateAudio: ZodNullable<ZodBoolean>;
+     referenceRoles: ZodReadonly<ZodArray<ZodEnum<...>>>;
+     maxReferenceImages: ZodNumber;
+     referenceResolutions: ZodReadonly<ZodArray<ZodEnum<...>>>;
+     prices: ZodReadonly<ZodArray<ZodReadonly<...>>>;
+  }, $strict>>>>;
+}, $strict>>;
+```
+
+Host catalog projection; provider metadata remains owned by the sole catalog.
+
+---
+
 ### mediaModelsSchema
 
 ```ts
 const mediaModelsSchema: ZodLazy<ZodArray<ZodReadonly<ZodObject<{
+  priceEstimate: ZodOptional<ZodObject<{
+     kind: ZodLiteral<"estimate">;
+     basis: ZodEnum<{
+        provider-cost: "provider-cost";
+        team-price: "team-price";
+     }>;
+     costMilliunits: ZodNumber;
+     settings: ZodObject<{
+        model: ZodString;
+        prompt: ZodString;
+        width: ZodNumber;
+        height: ZodNumber;
+        steps: ZodOptional<...>;
+        durationSeconds: ZodOptional<...>;
+        resolution: ZodOptional<...>;
+        aspectRatio: ZodOptional<...>;
+        generateAudio: ZodOptional<...>;
+        references: ZodOptional<...>;
+     }, $strict>;
+  }, $strict>>;
   id: ZodString;
   label: ZodString;
   kind: ZodEnum<{
@@ -42,6 +234,7 @@ const mediaModelsSchema: ZodLazy<ZodArray<ZodReadonly<ZodObject<{
         own: ...;
      }>;
      maxDimension: ZodNullable<ZodNumber>;
+     maxDimensionDocumented: ZodBoolean;
      defaultWidth: ZodNumber;
      defaultHeight: ZodNumber;
      steps: ZodEnum<{
@@ -64,6 +257,7 @@ const mediaModelsSchema: ZodLazy<ZodArray<ZodReadonly<ZodObject<{
      formats: ZodReadonly<...>;
      defaultResolution: ZodEnum<...>;
      defaultAspectRatio: ZodEnum<...>;
+     supportsAudio: ZodBoolean;
      defaultGenerateAudio: ZodNullable<...>;
      referenceRoles: ZodReadonly<...>;
      maxReferenceImages: ZodNumber;
@@ -248,6 +442,8 @@ const appMediaBrokerFailureSchema: ZodObject<{
      INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
      HOST_FAILURE: "HOST_FAILURE";
      INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+     MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
      SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
   }>;
   message: ZodString;
@@ -265,20 +461,7 @@ const appMediaBrokerFailureSchema: ZodObject<{
      destination-write: "destination-write";
   }>;
   retryable: ZodBoolean;
-  provider: ZodOptional<ZodPipe<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodTransform<
-     | Readonly<{
-     category:   | "InferenceUpstreamError"
-        | "AiInternalError"
-        | "TypeError"
-        | "AbortError"
-        | "TimeoutError"
-        | "Error";
-     code: number | null;
-   }>
-     | Readonly<{
-     category: "result_download";
-     status: number;
-  }>, unknown>>>;
+  provider: ZodOptional<ZodType<MediaProviderDiagnostic, unknown, $ZodTypeInternals<MediaProviderDiagnostic, unknown>>>;
 }, $strict>;
 ```
 
@@ -312,6 +495,8 @@ const appMediaRefusalSchema: ZodUnion<readonly [ZodObject<{
      INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
      HOST_FAILURE: "HOST_FAILURE";
      INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+     MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
      SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
   }>;
   message: ZodString;
@@ -329,15 +514,7 @@ const appMediaRefusalSchema: ZodUnion<readonly [ZodObject<{
      destination-write: "destination-write";
   }>;
   retryable: ZodBoolean;
-  provider: ZodOptional<ZodPipe<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodTransform<
-     | Readonly<{
-     category: ... | ... | ... | ... | ... | ...;
-     code: ... | ...;
-   }>
-     | Readonly<{
-     category: "result_download";
-     status: number;
-  }>, unknown>>>;
+  provider: ZodOptional<ZodType<MediaProviderDiagnostic, unknown, $ZodTypeInternals<MediaProviderDiagnostic, unknown>>>;
 }, $strict>]>;
 ```
 
@@ -350,6 +527,12 @@ errors.
 
 ```ts
 const appMediaModelsOutcomeSchema: ZodUnion<readonly [ZodLazy<ZodArray<ZodReadonly<ZodObject<{
+  priceEstimate: ZodOptional<ZodObject<{
+     kind: ZodLiteral<...>;
+     basis: ZodEnum<...>;
+     costMilliunits: ZodNumber;
+     settings: ZodObject<..., ...>;
+  }, $strict>>;
   id: ZodString;
   label: ZodString;
   kind: ZodEnum<{
@@ -372,6 +555,7 @@ const appMediaModelsOutcomeSchema: ZodUnion<readonly [ZodLazy<ZodArray<ZodReadon
      transport: ...;
      dimensions: ...;
      maxDimension: ...;
+     maxDimensionDocumented: ...;
      defaultWidth: ...;
      defaultHeight: ...;
      steps: ...;
@@ -404,6 +588,8 @@ const appMediaModelsOutcomeSchema: ZodUnion<readonly [ZodLazy<ZodArray<ZodReadon
      INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
      HOST_FAILURE: "HOST_FAILURE";
      INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+     MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
      SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
   }>;
   message: ZodString;
@@ -421,7 +607,7 @@ const appMediaModelsOutcomeSchema: ZodUnion<readonly [ZodLazy<ZodArray<ZodReadon
      destination-write: "destination-write";
   }>;
   retryable: ZodBoolean;
-  provider: ZodOptional<ZodPipe<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodTransform<Readonly<...> | Readonly<...>, unknown>>>;
+  provider: ZodOptional<ZodType<MediaProviderDiagnostic, unknown, $ZodTypeInternals<MediaProviderDiagnostic, unknown>>>;
 }, $strict>]>]>;
 ```
 
@@ -474,6 +660,8 @@ const appMediaGenerationOutcomeSchema: ZodUnion<readonly [ZodObject<{
      INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
      HOST_FAILURE: "HOST_FAILURE";
      INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+     MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
      SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
   }>;
   message: ZodString;
@@ -491,7 +679,7 @@ const appMediaGenerationOutcomeSchema: ZodUnion<readonly [ZodObject<{
      destination-write: "destination-write";
   }>;
   retryable: ZodBoolean;
-  provider: ZodOptional<ZodPipe<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodTransform<Readonly<...> | Readonly<...>, unknown>>>;
+  provider: ZodOptional<ZodType<MediaProviderDiagnostic, unknown, $ZodTypeInternals<MediaProviderDiagnostic, unknown>>>;
 }, $strict>]>]>;
 ```
 

package/docs/api/browser.md

@@ -65,23 +65,12 @@ const mediaFailureSchema: ZodObject<{
      INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
      HOST_FAILURE: "HOST_FAILURE";
      INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+     MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
      SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
   }>;
   retryable: ZodBoolean;
-  provider: ZodOptional<ZodPipe<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodTransform<
-     | Readonly<{
-     category:   | "InferenceUpstreamError"
-        | "AiInternalError"
-        | "TypeError"
-        | "AbortError"
-        | "TimeoutError"
-        | "Error";
-     code: number | null;
-   }>
-     | Readonly<{
-     category: "result_download";
-     status: number;
-  }>, unknown>>>;
+  provider: ZodOptional<ZodType<MediaProviderDiagnostic, unknown, $ZodTypeInternals<MediaProviderDiagnostic, unknown>>>;
 }, $strict>;
 ```
 
@@ -115,23 +104,11 @@ function readMediaFailure(
     | "INSUFFICIENT_CREDIT"
     | "HOST_FAILURE"
     | "INVALID_ARGUMENT"
+    | "MEDIA_PROVIDER_FAILURE"
+    | "MEDIA_PROVIDER_FAILURE_UNCHARGED"
     | "SAFETY_FILTER_REFUSED";
   retryable: boolean;
-  provider?:
-    | Readonly<{
-        category:
-          | "InferenceUpstreamError"
-          | "AiInternalError"
-          | "TypeError"
-          | "AbortError"
-          | "TimeoutError"
-          | "Error";
-        code: number | null;
-      }>
-    | Readonly<{
-        category: "result_download";
-        status: number;
-      }>;
+  provider?: MediaProviderDiagnostic;
 } | null>;
 ```
 
@@ -151,11 +128,9 @@ Read and decode one Media host failure at the browser HTTP boundary.
 \| `"operation"` \| `"normalization"` \| `"artifact"` \|
 `"destination-authorization"` \| `"destination-write"`; `code`: \|
 `"CAPABILITY_DENIED"` \| `"INSUFFICIENT_CREDIT"` \| `"HOST_FAILURE"` \|
-`"INVALID_ARGUMENT"` \| `"SAFETY_FILTER_REFUSED"`; `retryable`: `boolean`;
-`provider?`: \| `Readonly`\<\{ `category`: \| `"InferenceUpstreamError"` \|
-`"AiInternalError"` \| `"TypeError"` \| `"AbortError"` \| `"TimeoutError"` \|
-`"Error"`; `code`: `number` \| `null`; \}\> \| `Readonly`\<\{ `category`:
-`"result_download"`; `status`: `number`; \}\>; \} \| `null`\>
+`"INVALID_ARGUMENT"` \| `"MEDIA_PROVIDER_FAILURE"` \|
+`"MEDIA_PROVIDER_FAILURE_UNCHARGED"` \| `"SAFETY_FILTER_REFUSED"`; `retryable`:
+`boolean`; `provider?`: `MediaProviderDiagnostic`; \} \| `null`\>
 
 ## References
 

package/docs/api/cloudflare.md

@@ -554,9 +554,9 @@ Start the native resize and encode chain.
 
 ###### Returns
 
-| Name          | Type                    | Description                            |
-| ------------- | ----------------------- | -------------------------------------- |
-| `transform()` | (`options`) => `object` | Apply the native scale-down transform. |
+| Name          | Type                    | Description                                |
+| ------------- | ----------------------- | ------------------------------------------ |
+| `transform()` | (`options`) => `object` | Apply the native aspect-preserving resize. |
 
 ---
 
@@ -602,9 +602,9 @@ AI Gateway route.
 function createImagesReferenceFitter(images): ReferenceImageFitter;
 ```
 
-Media's reference preparation on the Images binding: decode the real bytes,
-scale an oversized image down to MAX_REFERENCE_DIMENSION as PNG, then decode the
-output so its metadata describes the bytes actually sent.
+Media's reference preparation on the Images binding: decode the real bytes, fit
+the selected model's reference size as PNG, then decode the output so its
+metadata describes the bytes actually sent.
 
 #### Parameters