@fungi.computer/darkroom 0.0.0-stage → 0.0.1

package/dist/server.js

@@ -0,0 +1,207 @@
+import { mediaPendingSchema } from "./media-binding.js";
+export { mediaPendingSchema, mediaBindingCallSchema, mediaBindingGenerationSchema, mediaImageBindingInputSchema, mediaVideoBindingInputSchema, parseMediaBindingCall, mediaBindingRequest, readMediaBindingReply, } from "./media-binding.js";
+import { Hono } from "hono";
+import { z } from "zod";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import { runMediaGeneration } from "./media-generation.js";
+import { validateMediaGenerationSettings, listMediaModels, mediaGenerationSettingsSchema, mediaRequestedImageFormatSchema, MediaSettingsError, } from "./index.js";
+import { mediaResultSchema, } from "./media-operation-contract.js";
+import { MediaOutputFormatMismatch, MediaBillingRefusal, MediaExecutionError, MediaSafetyFilterRefusal, } from "./execution-error.js";
+export { MediaBillingRefusal, MediaExecutionError, } from "./execution-error.js";
+export { mediaUnits } from "./gateway-models.js";
+export { MediaOperationOwner, mediaOperationDestinationSchema, mediaOperationCoordinatesSchema, mediaOperationStateSchema, mediaImageSchema, mediaOperationResultSchema, } from "./media-operation-owner.js";
+const identifier = z.string().min(1).max(256);
+/** Decode relative service generation input. Identity comes from the host. */
+export const mediaRequestSchema = z.strictObject({
+    /** Fixed destination or reference file path. */
+    path: z
+        .string()
+        .min(1)
+        .max(1_024)
+        .refine((path) => !path.includes("\0")),
+    /** Requested model, dimensions, prompt and references. */
+    settings: mediaGenerationSettingsSchema,
+    /** Optional verified image encoding pin. */
+    outputFormat: mediaRequestedImageFormatSchema.optional(),
+});
+export { mediaResultSchema } from "./media-operation-contract.js";
+async function readJsonBody(request) {
+    try {
+        const value = await request.json();
+        return {
+            kind: "parsed",
+            value,
+        };
+    }
+    catch {
+        return {
+            kind: "invalid",
+        };
+    }
+}
+const headers = {
+    "Cache-Control": "private, no-store",
+    "X-Content-Type-Options": "nosniff",
+};
+function failure(error, refusalMessages) {
+    if (error instanceof MediaSafetyFilterRefusal)
+        return Response.json({
+            error: "The model's safety filter refused this prompt — try rewording.",
+            stage: "provider",
+            code: "SAFETY_FILTER_REFUSED",
+            retryable: false,
+        }, { status: 400, headers });
+    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.",
+            stage: error.stage,
+            code: "HOST_FAILURE",
+            retryable: false,
+        }, {
+            status: 503,
+            headers,
+        });
+    if (error instanceof MediaExecutionError &&
+        error.stage === "billing" &&
+        error.cause instanceof MediaBillingRefusal)
+        return Response.json({
+            error: refusalMessages?.[error.cause.code] ??
+                "Media generation was refused by the host.",
+            stage: "billing",
+            code: error.cause.code === "insufficient_credits"
+                ? "INSUFFICIENT_CREDIT"
+                : "CAPABILITY_DENIED",
+            retryable: false,
+        }, {
+            status: error.cause.code === "denied" ? 403 : 402,
+            headers,
+        });
+    if (error instanceof MediaSettingsError ||
+        (error.stage === "estimate" && error.cause instanceof MediaSettingsError))
+        return Response.json({
+            error: "Media generation settings are invalid; check the model, dimensions, steps, and destination.",
+            stage: "settings",
+            code: "INVALID_ARGUMENT",
+            retryable: false,
+        }, {
+            status: 400,
+            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.",
+    };
+    return Response.json({
+        error: messages[error.stage],
+        stage: error.stage,
+        code: "HOST_FAILURE",
+        retryable: error.stage !== "normalization" && error.stage !== "provider",
+    }, {
+        status: 503,
+        headers,
+    });
+}
+/** Generate through the Effect core with a Promise boundary preserving typed domain failures. */
+export async function generateMedia(host, request, signal) {
+    const result = await Effect.runPromise(Effect.result(runMediaGeneration(host, request, signal)));
+    return Result.getOrThrowWith(result, (error) => error);
+}
+function outcomeResponse(outcome) {
+    if (outcome.kind === "conflict")
+        return Response.json({
+            error: "This request ID already belongs to a different Media request.",
+            stage: "operation",
+            code: "INVALID_ARGUMENT",
+            retryable: false,
+        }, {
+            status: 409,
+            headers,
+        });
+    if (outcome.kind === "pending" && outcome.background)
+        // A video generation runs in the background; retry this request id.
+        return Response.json(mediaPendingSchema.parse({
+            status: "pending",
+            retryAfterSeconds: outcome.retryAfterSeconds,
+        }), {
+            status: 202,
+            headers: {
+                ...headers,
+                "Retry-After": String(outcome.retryAfterSeconds),
+            },
+        });
+    if (outcome.kind === "pending")
+        return Response.json({
+            error: "Media generation is still in progress; retry this request to check its durable result.",
+            stage: "operation",
+            code: "HOST_FAILURE",
+            retryable: true,
+        }, {
+            status: 409,
+            headers,
+        });
+    if (outcome.kind === "interrupted" || outcome.kind === "unavailable")
+        return Response.json({
+            error: "Media generation was interrupted before completion; start a new request.",
+            stage: "operation",
+            code: "HOST_FAILURE",
+            retryable: false,
+        }, {
+            status: 503,
+            headers,
+        });
+    return Response.json(mediaResultSchema.parse({
+        bytes: outcome.bytes,
+        costMilliunits: outcome.costMilliunits,
+        path: outcome.path,
+        format: outcome.format,
+        height: outcome.height,
+        model: outcome.model,
+        width: outcome.width,
+    }), { headers });
+}
+/** Relative HTTP routes; the caller admits identity and supplies destination access. */
+export function createMediaService(host) {
+    const app = new Hono();
+    app.get("/models", () => Response.json(listMediaModels().map((model) => host.destination.readReference !== undefined ||
+        model.input.maxReferences === 0
+        ? model
+        : {
+            ...model,
+            label: `${model.label} (reference images unavailable in this App host)`,
+            input: {
+                ...model.input,
+                maxReferences: 0,
+                referenceField: null,
+            },
+        }), { headers }));
+    app.post("/generate", async (context) => {
+        const body = await readJsonBody(context.req.raw);
+        const input = body.kind === "parsed"
+            ? mediaRequestSchema.safeParse(body.value)
+            : undefined;
+        const requestId = identifier.safeParse(context.req.header("X-Request-Id"));
+        if (input?.success !== true || !requestId.success)
+            return failure(new MediaSettingsError("invalid request"));
+        return Effect.runPromise(runMediaGeneration(host, {
+            requestId: requestId.data,
+            path: input.data.path,
+            settings: input.data.settings,
+            outputFormat: input.data.outputFormat,
+        }, context.req.raw.signal).pipe(Effect.match({
+            onSuccess: outcomeResponse,
+            onFailure: (error) => (error instanceof MediaExecutionError
+                ? host.onFailure?.(error)
+                : undefined) ?? failure(error, host.refusalMessages),
+        })));
+    });
+    return app;
+}

package/dist/video-providers/index.d.ts

@@ -0,0 +1,14 @@
+import type { VideoProviderAdapter } from "./types.js";
+export type { CheckedVideoSettings } from "./types.js";
+/**
+ * One adapter per verified video provider family. Seedance and Veo share
+ * `unifiedVideoAdapter`; MiniMax's distinct `content[]` request and
+ * `{task: {...}}` answer get their own module. Adding a provider means
+ * writing one adapter module and one entry here — `gatewayInput` and
+ * `generateThroughGateway` never branch on the provider name themselves.
+ */
+export declare const videoProviderAdapters: {
+    seedance: VideoProviderAdapter;
+    veo: VideoProviderAdapter;
+    minimax: VideoProviderAdapter;
+};

package/dist/video-providers/index.js

@@ -0,0 +1,14 @@
+import { unifiedVideoAdapter } from "./unified.js";
+import { minimaxVideoAdapter } from "./minimax.js";
+/**
+ * One adapter per verified video provider family. Seedance and Veo share
+ * `unifiedVideoAdapter`; MiniMax's distinct `content[]` request and
+ * `{task: {...}}` answer get their own module. Adding a provider means
+ * writing one adapter module and one entry here — `gatewayInput` and
+ * `generateThroughGateway` never branch on the provider name themselves.
+ */
+export const videoProviderAdapters = {
+    seedance: unifiedVideoAdapter,
+    veo: unifiedVideoAdapter,
+    minimax: minimaxVideoAdapter,
+};

package/dist/video-providers/minimax.d.ts

@@ -0,0 +1,25 @@
+import type { VideoProviderAdapter } from "./types.js";
+/** MiniMax's documented `content[]` image role, distinct from our neutral one. */
+export type MinimaxReferenceRole = "first_frame" | "last_frame" | "reference_image";
+/** One MiniMax `content[]` entry, exactly as its schema documents it. */
+export type MinimaxContentItem = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+    role: MinimaxReferenceRole;
+};
+/** MiniMax's documented uppercase resolution literal. */
+export type MinimaxResolution = "480P" | "720P" | "768P" | "1080P" | "4K";
+/** MiniMax H3 Max's documented provider body: multimodal `content[]`, not a
+ * flat prompt/image/duration object. */
+export type MinimaxGatewayInput = {
+    content: MinimaxContentItem[];
+    duration: number;
+    resolution: MinimaxResolution;
+    ratio: string;
+};
+export declare const minimaxVideoAdapter: VideoProviderAdapter;

package/dist/video-providers/minimax.js

@@ -0,0 +1,63 @@
+import * as z from "zod";
+import { MediaSettingsError } from "../model-catalog.js";
+import { resultUrl } from "../gateway-wire.js";
+import { imageDataUri } from "./reference-encoding.js";
+/** Our lowercase selector to MiniMax's documented uppercase wire literal. */
+const minimaxResolutionWire = {
+    "480p": "480P",
+    "720p": "720P",
+    "768p": "768P",
+    "1080p": "1080P",
+    "4k": "4K",
+};
+/** Our neutral reference role to MiniMax's documented `content[]` role. */
+const minimaxRoleWire = {
+    "first-frame": "first_frame",
+    "last-frame": "last_frame",
+    reference: "reference_image",
+};
+/** MiniMax's documented task wrapper: `{task: {status, content: {url}}}`,
+ * distinct from the Unified gateway's `{state, result}` shape Seedance and
+ * Veo normalize into. https://developers.cloudflare.com/ai/models/minimax/h3-max/ */
+const minimaxTaskOutputSchema = z.looseObject({
+    task: z.looseObject({
+        status: z.enum(["queued", "running", "succeeded", "failed", "cancelled"]),
+        content: z.looseObject({ url: resultUrl.optional() }).optional(),
+    }),
+});
+export const minimaxVideoAdapter = {
+    buildInput(checked, references, model) {
+        if (checked.generateAudio !== undefined)
+            throw new MediaSettingsError(`${model.id} does not support an audio choice`);
+        const content = [
+            { type: "text", text: checked.prompt },
+        ];
+        references.forEach((image, index) => {
+            const role = checked.references?.[index]?.role;
+            const wireRole = role === undefined ? undefined : minimaxRoleWire[role];
+            if (wireRole === undefined)
+                throw new MediaSettingsError("video reference role was not admitted");
+            content.push({
+                type: "image_url",
+                image_url: { url: imageDataUri(image) },
+                role: wireRole,
+            });
+        });
+        const input = {
+            content,
+            duration: checked.durationSeconds,
+            resolution: minimaxResolutionWire[checked.resolution],
+            ratio: checked.aspectRatio,
+        };
+        return input;
+    },
+    decodeResultUrl(providerValue) {
+        const parsed = minimaxTaskOutputSchema.parse(providerValue);
+        if (parsed.task.status !== "succeeded")
+            throw new Error(`minimax video task ${parsed.task.status}`);
+        const url = parsed.task.content?.url;
+        if (url === undefined)
+            throw new Error("minimax video task has no URL");
+        return url;
+    },
+};

package/dist/video-providers/reference-encoding.d.ts

@@ -0,0 +1,4 @@
+import type { MediaReferenceBytes } from "../index.js";
+/** Encode in multiples of three so only the final chunk needs base64 padding. */
+export declare function imageBase64(image: MediaReferenceBytes): string;
+export declare function imageDataUri(image: MediaReferenceBytes): string;

package/dist/video-providers/reference-encoding.js

@@ -0,0 +1,11 @@
+/** Encode in multiples of three so only the final chunk needs base64 padding. */
+export function imageBase64(image) {
+    const chunks = [];
+    for (let offset = 0; offset < image.bytes.length; offset += 32_766)
+        chunks.push(btoa(String.fromCharCode(...image.bytes.subarray(offset, offset + 32_766))));
+    return chunks.join("");
+}
+export function imageDataUri(image) {
+    const mime = image.format === "jpeg" ? "image/jpeg" : `image/${image.format}`;
+    return `data:${mime};base64,${imageBase64(image)}`;
+}

package/dist/video-providers/types.d.ts

@@ -0,0 +1,28 @@
+import type { MediaAiResult, MediaGenerationSettings, MediaReferenceBytes } from "../index.js";
+import type { MediaModel, MediaVideoAspectRatio, MediaVideoModel, MediaVideoResolution } from "../model-catalog.js";
+import type { UnifiedGatewayInput } from "./unified.js";
+import type { MinimaxGatewayInput } from "./minimax.js";
+/** One verified video provider family, as the catalog names it. */
+export type VideoProvider = MediaVideoModel["provider"];
+/** Validated video settings with every video-only field guaranteed present;
+ * `gatewayInput` narrows to this before handing settings to an adapter. */
+export type CheckedVideoSettings = MediaGenerationSettings & {
+    resolution: MediaVideoResolution;
+    aspectRatio: MediaVideoAspectRatio;
+    durationSeconds: number;
+};
+/** Every documented provider request body this catalog can produce. */
+export type VideoProviderInput = UnifiedGatewayInput | MinimaxGatewayInput;
+/**
+ * One provider family's wire translation: the exact request body its
+ * documented schema expects, and how to pull a validated result URL out of
+ * its answer. Adding a provider means writing one adapter and one table
+ * entry; `gatewayInput` and `generateThroughGateway` never branch on the
+ * provider name themselves.
+ */
+export type VideoProviderAdapter = {
+    /** Build the provider JSON body for one validated video generation. */
+    buildInput(checked: CheckedVideoSettings, references: readonly MediaReferenceBytes[], model: MediaModel): VideoProviderInput;
+    /** Extract and validate the HTTPS result URL from the raw provider answer. */
+    decodeResultUrl(providerValue: MediaAiResult): string;
+};

package/dist/video-providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/video-providers/unified.d.ts

@@ -0,0 +1,18 @@
+import type { VideoProviderAdapter } from "./types.js";
+export type UnifiedGatewayInput = {
+    prompt: string;
+    duration: string | number;
+    resolution: string;
+    aspect_ratio: string;
+    generate_audio?: boolean;
+    image?: string;
+    last_frame_image?: string;
+    reference_images?: string[];
+    image_input?: string;
+};
+/**
+ * Seedance and Veo share the Unified AI gateway's `{state, result}` answer
+ * and a flat prompt/image request body; only a few fields differ by
+ * provider, handled inline below.
+ */
+export declare const unifiedVideoAdapter: VideoProviderAdapter;

package/dist/video-providers/unified.js

@@ -0,0 +1,52 @@
+import { MediaSettingsError } from "../model-catalog.js";
+import { gatewayOutputSchema } from "../gateway-wire.js";
+import { imageBase64, imageDataUri } from "./reference-encoding.js";
+/**
+ * Seedance and Veo share the Unified AI gateway's `{state, result}` answer
+ * and a flat prompt/image request body; only a few fields differ by
+ * provider, handled inline below.
+ */
+export const unifiedVideoAdapter = {
+    buildInput(checked, references, model) {
+        const veo = model.video?.provider === "veo";
+        const input = {
+            prompt: checked.prompt,
+            duration: veo
+                ? `${String(checked.durationSeconds)}s`
+                : checked.durationSeconds,
+            resolution: checked.resolution,
+            aspect_ratio: checked.aspectRatio,
+        };
+        if (checked.generateAudio !== undefined)
+            input.generate_audio = checked.generateAudio;
+        const referenceImages = [];
+        references.forEach((image, index) => {
+            const role = checked.references?.[index]?.role;
+            if (veo) {
+                input.image_input = imageBase64(image);
+            }
+            else if (role === "first-frame") {
+                input.image = imageDataUri(image);
+            }
+            else if (role === "last-frame") {
+                input.last_frame_image = imageDataUri(image);
+            }
+            else if (role === "reference") {
+                referenceImages.push(imageDataUri(image));
+            }
+            else
+                throw new MediaSettingsError("video reference role was not admitted");
+        });
+        if (referenceImages.length > 0)
+            input.reference_images = referenceImages;
+        return input;
+    },
+    decodeResultUrl(providerValue) {
+        const parsed = gatewayOutputSchema.parse(providerValue);
+        if (parsed.state !== "Completed")
+            throw new Error("gateway video result is not completed");
+        if (parsed.result.video === undefined)
+            throw new Error("gateway video result has no URL");
+        return parsed.result.video;
+    },
+};

package/docs/api/README.md

@@ -0,0 +1,16 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/darkroom**
+
+---
+
+# Darkroom
+
+Generate media through a host-supplied provider, retain its exact output, and
+retry saving without repeating inference. Your host owns identity, permission,
+billing and destination access.
+
+Use the root entry for the model catalog and settings. `server` composes the
+service and portable SQL owner. `cloudflare` binds that owner to a SQLite
+Durable Object and supplies Workers AI and Images adapters. `provenance` strips
+private image metadata for downloads.