@fungi.computer/darkroom 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,507 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/darkroom**](README.md)
+
+---
+
+[@fungi.computer/darkroom](modules.md) / app-media-contracts
+
+# app-media-contracts
+
+## Variables
+
+### mediaModelsSchema
+
+```ts
+const mediaModelsSchema: ZodArray<ZodReadonly<ZodObject<{
+  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";
+  }>>>;
+  input: ZodReadonly<ZodObject<{
+     transport: ZodEnum<{
+        json: "json";
+        multipart: "multipart";
+     }>;
+     dimensions: ZodEnum<{
+        none: "none";
+        own: "own";
+     }>;
+     maxDimension: ZodNullable<ZodNumber>;
+     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<ZodReadonly<ZodObject<{
+     minSeconds: ZodNumber;
+     maxSeconds: ZodNumber;
+     defaultSeconds: ZodNumber;
+     durations: ZodReadonly<ZodArray<ZodNumber>>;
+     provider: ZodEnum<{
+        seedance: "seedance";
+        veo: "veo";
+     }>;
+     formats: ZodReadonly<ZodArray<ZodReadonly<...>>>;
+     defaultResolution: ZodEnum<{
+        p480: "480p";
+        p720: "720p";
+        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";
+     }>;
+     defaultGenerateAudio: ZodNullable<ZodBoolean>;
+     maxPromptLength: ZodNumber;
+     referenceRoles: ZodReadonly<ZodArray<ZodEnum<...>>>;
+     maxReferenceImages: ZodNumber;
+     referenceResolutions: ZodReadonly<ZodArray<ZodEnum<...>>>;
+     prices: ZodReadonly<ZodArray<ZodReadonly<...>>>;
+  }, $strict>>>;
+}, $strict>>>;
+```
+
+Bounded catalog decoded by the App media broker before host filtering.
+
+---
+
+### destinationSchema
+
+```ts
+const destinationSchema: ZodObject<
+  {
+    computerId: ZodString;
+    path: ZodString;
+  },
+  $strict
+>;
+```
+
+An absolute output path on the Computer admitted by the App host.
+
+---
+
+### appMediaGenerationResultSchema
+
+```ts
+const appMediaGenerationResultSchema: ZodObject<
+  {
+    destination: ZodObject<
+      {
+        computerId: ZodString;
+        path: ZodString;
+      },
+      $strict
+    >;
+    bytes: ZodNumber;
+    costMilliunits: ZodNumber;
+    format: ZodEnum<{
+      png: "png";
+      jpeg: "jpeg";
+      gif: "gif";
+      webp: "webp";
+      mp4: "mp4";
+    }>;
+    height: ZodNumber;
+    model: ZodString;
+    width: ZodNumber;
+  },
+  $strict
+>;
+```
+
+Completed App generation output, with its admitted Computer destination.
+
+---
+
+### appMediaAdmissionErrorSchema
+
+```ts
+const appMediaAdmissionErrorSchema: ZodObject<
+  {
+    error: ZodEnum<{
+      revoked: "revoked";
+      not_granted: "not_granted";
+      grantor_lost_authority: "grantor_lost_authority";
+      unavailable: "unavailable";
+    }>;
+  },
+  $strict
+>;
+```
+
+Authority refusals emitted by Media admission before a host call.
+
+---
+
+### appMediaBudgetRefusalSchema
+
+```ts
+const appMediaBudgetRefusalSchema: ZodObject<
+  {
+    error: ZodLiteral<"attachment_budget_exceeded">;
+    kind: ZodLiteral<"media">;
+    retryAfterMs: ZodNumber;
+  },
+  $strict
+>;
+```
+
+Attachment budget refusal emitted by the Media reservation owner.
+
+---
+
+### appMediaAdmissionRefusalSchema
+
+```ts
+const appMediaAdmissionRefusalSchema: ZodUnion<
+  readonly [
+    ZodObject<
+      {
+        error: ZodEnum<{
+          revoked: "revoked";
+          not_granted: "not_granted";
+          grantor_lost_authority: "grantor_lost_authority";
+          unavailable: "unavailable";
+        }>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        error: ZodLiteral<"attachment_budget_exceeded">;
+        kind: ZodLiteral<"media">;
+        retryAfterMs: ZodNumber;
+      },
+      $strict
+    >,
+  ]
+>;
+```
+
+Existing Media admission refusals, without an admitted selector or callable.
+
+---
+
+### appMediaBrokerErrorSchema
+
+```ts
+const appMediaBrokerErrorSchema: ZodObject<
+  {
+    error: ZodEnum<{
+      revoked: "revoked";
+      not_granted: "not_granted";
+      grantor_lost_authority: "grantor_lost_authority";
+      unavailable: "unavailable";
+      invalid: "invalid";
+      too_large: "too_large";
+    }>;
+  },
+  $strict
+>;
+```
+
+Admission errors plus invalid/oversized inputs emitted directly by the broker.
+
+---
+
+### agentAppMediaLibraryFailureSchema
+
+```ts
+const agentAppMediaLibraryFailureSchema: ZodObject<
+  {
+    error: ZodLiteral<"library_unavailable">;
+    message: ZodString;
+  },
+  $strict
+>;
+```
+
+Missing-library refusal decoded and returned by the App media broker.
+
+---
+
+### appMediaBrokerFailureSchema
+
+```ts
+const appMediaBrokerFailureSchema: ZodObject<{
+  error: ZodEnum<{
+     CAPABILITY_DENIED: "CAPABILITY_DENIED";
+     INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
+     HOST_FAILURE: "HOST_FAILURE";
+     INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
+  }>;
+  message: ZodString;
+  stage: ZodEnum<{
+     admission: "admission";
+     generation-authorization: "generation-authorization";
+     settings: "settings";
+     estimate: "estimate";
+     billing: "billing";
+     operation: "operation";
+     provider: "provider";
+     normalization: "normalization";
+     artifact: "artifact";
+     destination-authorization: "destination-authorization";
+     destination-write: "destination-write";
+  }>;
+  retryable: ZodBoolean;
+}, $strict>;
+```
+
+Broker projection of an HTTP failure: code becomes error and error becomes
+message.
+
+---
+
+### appMediaRefusalSchema
+
+```ts
+const appMediaRefusalSchema: ZodUnion<readonly [ZodObject<{
+  error: ZodEnum<{
+     revoked: "revoked";
+     not_granted: "not_granted";
+     grantor_lost_authority: "grantor_lost_authority";
+     unavailable: "unavailable";
+     invalid: "invalid";
+     too_large: "too_large";
+  }>;
+}, $strict>, ZodObject<{
+  error: ZodLiteral<"attachment_budget_exceeded">;
+  kind: ZodLiteral<"media">;
+  retryAfterMs: ZodNumber;
+}, $strict>, ZodObject<{
+  error: ZodLiteral<"library_unavailable">;
+  message: ZodString;
+}, $strict>, ZodObject<{
+  error: ZodEnum<{
+     CAPABILITY_DENIED: "CAPABILITY_DENIED";
+     INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
+     HOST_FAILURE: "HOST_FAILURE";
+     INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
+  }>;
+  message: ZodString;
+  stage: ZodEnum<{
+     admission: "admission";
+     generation-authorization: "generation-authorization";
+     settings: "settings";
+     estimate: "estimate";
+     billing: "billing";
+     operation: "operation";
+     provider: "provider";
+     normalization: "normalization";
+     artifact: "artifact";
+     destination-authorization: "destination-authorization";
+     destination-write: "destination-write";
+  }>;
+  retryable: ZodBoolean;
+}, $strict>]>;
+```
+
+Refusal payloads emitted by the App media broker, separate from transport
+errors.
+
+---
+
+### appMediaModelsOutcomeSchema
+
+```ts
+const appMediaModelsOutcomeSchema: ZodUnion<readonly [ZodArray<ZodReadonly<ZodObject<{
+  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";
+  }>>>;
+  input: ZodReadonly<ZodObject<{
+     transport: ZodEnum<{
+        json: ...;
+        multipart: ...;
+     }>;
+     dimensions: ZodEnum<{
+        none: ...;
+        own: ...;
+     }>;
+     maxDimension: ZodNullable<ZodNumber>;
+     defaultWidth: ZodNumber;
+     defaultHeight: ZodNumber;
+     steps: ZodEnum<{
+        steps: ...;
+        num_steps: ...;
+        fixed: ...;
+     }>;
+     maxSteps: ZodNullable<ZodNumber>;
+     defaultSteps: ZodNullable<ZodNumber>;
+     referenceField: ZodNullable<ZodString>;
+     maxReferences: ZodNumber;
+  }, $strict>>;
+  sizes: ZodNullable<ZodReadonly<ZodArray<ZodString>>>;
+  video: ZodNullable<ZodReadonly<ZodObject<{
+     minSeconds: ZodNumber;
+     maxSeconds: ZodNumber;
+     defaultSeconds: ZodNumber;
+     durations: ZodReadonly<...>;
+     provider: ZodEnum<...>;
+     formats: ZodReadonly<...>;
+     defaultResolution: ZodEnum<...>;
+     defaultAspectRatio: ZodEnum<...>;
+     defaultGenerateAudio: ZodNullable<...>;
+     maxPromptLength: ZodNumber;
+     referenceRoles: ZodReadonly<...>;
+     maxReferenceImages: ZodNumber;
+     referenceResolutions: ZodReadonly<...>;
+     prices: ZodReadonly<...>;
+  }, $strict>>>;
+}, $strict>>>, ZodUnion<readonly [ZodObject<{
+  error: ZodEnum<{
+     revoked: "revoked";
+     not_granted: "not_granted";
+     grantor_lost_authority: "grantor_lost_authority";
+     unavailable: "unavailable";
+     invalid: "invalid";
+     too_large: "too_large";
+  }>;
+}, $strict>, ZodObject<{
+  error: ZodLiteral<"attachment_budget_exceeded">;
+  kind: ZodLiteral<"media">;
+  retryAfterMs: ZodNumber;
+}, $strict>, ZodObject<{
+  error: ZodLiteral<"library_unavailable">;
+  message: ZodString;
+}, $strict>, ZodObject<{
+  error: ZodEnum<{
+     CAPABILITY_DENIED: "CAPABILITY_DENIED";
+     INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
+     HOST_FAILURE: "HOST_FAILURE";
+     INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
+  }>;
+  message: ZodString;
+  stage: ZodEnum<{
+     admission: "admission";
+     generation-authorization: "generation-authorization";
+     settings: "settings";
+     estimate: "estimate";
+     billing: "billing";
+     operation: "operation";
+     provider: "provider";
+     normalization: "normalization";
+     artifact: "artifact";
+     destination-authorization: "destination-authorization";
+     destination-write: "destination-write";
+  }>;
+  retryable: ZodBoolean;
+}, $strict>]>]>;
+```
+
+Model-list payload or an existing broker refusal.
+
+---
+
+### appMediaGenerationOutcomeSchema
+
+```ts
+const appMediaGenerationOutcomeSchema: ZodUnion<readonly [ZodObject<{
+  destination: ZodObject<{
+     computerId: ZodString;
+     path: ZodString;
+  }, $strict>;
+  bytes: ZodNumber;
+  costMilliunits: ZodNumber;
+  format: ZodEnum<{
+     png: "png";
+     jpeg: "jpeg";
+     gif: "gif";
+     webp: "webp";
+     mp4: "mp4";
+  }>;
+  height: ZodNumber;
+  model: ZodString;
+  width: ZodNumber;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"pending">;
+  retryAfterMs: ZodNumber;
+}, $strict>, ZodUnion<readonly [ZodObject<{
+  error: ZodEnum<{
+     revoked: "revoked";
+     not_granted: "not_granted";
+     grantor_lost_authority: "grantor_lost_authority";
+     unavailable: "unavailable";
+     invalid: "invalid";
+     too_large: "too_large";
+  }>;
+}, $strict>, ZodObject<{
+  error: ZodLiteral<"attachment_budget_exceeded">;
+  kind: ZodLiteral<"media">;
+  retryAfterMs: ZodNumber;
+}, $strict>, ZodObject<{
+  error: ZodLiteral<"library_unavailable">;
+  message: ZodString;
+}, $strict>, ZodObject<{
+  error: ZodEnum<{
+     CAPABILITY_DENIED: "CAPABILITY_DENIED";
+     INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
+     HOST_FAILURE: "HOST_FAILURE";
+     INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
+  }>;
+  message: ZodString;
+  stage: ZodEnum<{
+     admission: "admission";
+     generation-authorization: "generation-authorization";
+     settings: "settings";
+     estimate: "estimate";
+     billing: "billing";
+     operation: "operation";
+     provider: "provider";
+     normalization: "normalization";
+     artifact: "artifact";
+     destination-authorization: "destination-authorization";
+     destination-write: "destination-write";
+  }>;
+  retryable: ZodBoolean;
+}, $strict>]>]>;
+```
+
+Completed generation, Agar polling result, or an existing broker refusal.

package/docs/api/browser.md

@@ -0,0 +1,126 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/darkroom**](README.md)
+
+---
+
+[@fungi.computer/darkroom](modules.md) / browser
+
+# browser
+
+## Type Aliases
+
+### MediaGenerationDiagnostic
+
+```ts
+type MediaGenerationDiagnostic = (operation, cause, details?) => void;
+```
+
+Host diagnostic sink; generation errors and retry truth remain transport-owned.
+
+#### Parameters
+
+| Parameter   | Type                                                                                |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `operation` | \| `"app_media_pending_response_unavailable"` \| `"media_failure_body_read_failed"` |
+| `cause`     | `unknown`                                                                           |
+| `details?`  | `Readonly`\<\{ `status`: `number`; \}\>                                             |
+
+#### Returns
+
+`void`
+
+---
+
+### MediaFailure
+
+```ts
+type MediaFailure = z.output<typeof mediaFailureSchema>;
+```
+
+Sanitized Media failure carried from the authenticated host to Agar.
+
+## Variables
+
+### mediaFailureSchema
+
+```ts
+const mediaFailureSchema: ZodObject<{
+  error: ZodString;
+  stage: ZodEnum<{
+     admission: "admission";
+     generation-authorization: "generation-authorization";
+     settings: "settings";
+     estimate: "estimate";
+     billing: "billing";
+     operation: "operation";
+     provider: "provider";
+     normalization: "normalization";
+     artifact: "artifact";
+     destination-authorization: "destination-authorization";
+     destination-write: "destination-write";
+  }>;
+  code: ZodEnum<{
+     CAPABILITY_DENIED: "CAPABILITY_DENIED";
+     INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
+     HOST_FAILURE: "HOST_FAILURE";
+     INVALID_ARGUMENT: "INVALID_ARGUMENT";
+     SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
+  }>;
+  retryable: ZodBoolean;
+}, $strict>;
+```
+
+Sanitized HTTP refusal emitted by a Media host and decoded at the browser
+boundary.
+
+## Functions
+
+### readMediaFailure()
+
+```ts
+function readMediaFailure(
+  response,
+  diagnostic?,
+): Promise<{
+  error: string;
+  stage:
+    | "provider"
+    | "admission"
+    | "generation-authorization"
+    | "settings"
+    | "estimate"
+    | "billing"
+    | "operation"
+    | "normalization"
+    | "artifact"
+    | "destination-authorization"
+    | "destination-write";
+  code:
+    | "CAPABILITY_DENIED"
+    | "INSUFFICIENT_CREDIT"
+    | "HOST_FAILURE"
+    | "INVALID_ARGUMENT"
+    | "SAFETY_FILTER_REFUSED";
+  retryable: boolean;
+} | null>;
+```
+
+Read and decode one Media host failure at the browser HTTP boundary.
+
+#### Parameters
+
+| Parameter    | Type                                                      | Default value        |
+| ------------ | --------------------------------------------------------- | -------------------- |
+| `response`   | `Response`                                                | `undefined`          |
+| `diagnostic` | [`MediaGenerationDiagnostic`](#mediagenerationdiagnostic) | `reportCatchFailure` |
+
+#### Returns
+
+`Promise`\< \| \{ `error`: `string`; `stage`: \| `"provider"` \| `"admission"`
+\| `"generation-authorization"` \| `"settings"` \| `"estimate"` \| `"billing"`
+\| `"operation"` \| `"normalization"` \| `"artifact"` \|
+`"destination-authorization"` \| `"destination-write"`; `code`: \|
+`"CAPABILITY_DENIED"` \| `"INSUFFICIENT_CREDIT"` \| `"HOST_FAILURE"` \|
+`"INVALID_ARGUMENT"` \| `"SAFETY_FILTER_REFUSED"`; `retryable`: `boolean`; \} \|
+`null`\>