@hypit/hypit 0.2.8 → 0.2.10

package/packages/pixverse/src/surface.ts

@@ -1,6 +1,6 @@
 import { artifactTypes } from "@hypit/artifact";
 import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@hypit/generation";
-import type { GenerationMediaPort, GenerationPortValue } from "@hypit/generation";
+import type { GenerationMediaPort, GenerationMediaRole, GenerationPortValue } from "@hypit/generation";
 import {
   createExactModelPrimaryGenerationFragment,
   exactModelMediaInputNames,
@@ -16,23 +16,31 @@ import type {
 import type { CanonicalValue, TypeRef } from "@hypit/protocol";
 import { textTypes, verifyText } from "@hypit/text";
 
-import { pixverseEndpoints } from "./index.js";
+import { pixverseEndpointsByModel } from "./index.js";
+import type { PixverseModel } from "./index.js";
+
+type MediaInput = {
+  readonly port: "firstFrame" | "lastFrame" | "referenceImage" | "referenceVideo";
+  readonly role: GenerationMediaRole;
+  readonly source: SurfaceResolvedReference;
+};
 
 function assert(condition: unknown, message: string): asserts condition {
   if (!condition) throw new Error(message);
 }
 
+function localName(name: string): string {
+  return name.includes(":") ? name.slice(name.lastIndexOf(":") + 1) : name;
+}
+
 function sameType(left: TypeRef, right: TypeRef): boolean {
   return left.name === right.name && left.module.name === right.module.name && left.module.version === right.module.version;
 }
 
-const attributes = ["id", "prompt", "first-frame", "last-frame", "duration", "quality",
-  "aspect-ratio", "generate-audio", "multi-clip", "seed"] as const;
-
-function exact(element: StructuredElement): void {
-  const unknown = Object.keys(element.attributes).filter((name) => !attributes.includes(name as typeof attributes[number]));
+function exact(element: StructuredElement, allowed: readonly string[], required: readonly string[]): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
   assert(unknown.length === 0, `${element.name} does not accept ${unknown[0]}`);
-  const missing = ["id", "prompt", "duration", "quality"].filter((name) => element.attributes[name] === undefined);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
   assert(missing.length === 0, `${element.name} requires ${missing.join(", ")}`);
 }
 
@@ -60,6 +68,10 @@ function integer(element: StructuredElement, name: string): readonly GenerationP
   return [Number(value)];
 }
 
+function optionalInteger(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+  return element.attributes[name] === undefined ? undefined : integer(element, name);
+}
+
 function ref(
   element: StructuredElement,
   name: string,
@@ -73,74 +85,171 @@ function ref(
   return result;
 }
 
-function frame(
+function media(
   element: StructuredElement,
   name: string,
+  role: GenerationMediaRole,
   resolve: (path: string) => SurfaceResolvedReference | undefined,
-): SurfaceResolvedReference | undefined {
-  if (element.attributes[name] === undefined) return undefined;
-  const image = ref(element, name, artifactTypes.blob, resolve);
-  if (image.record !== undefined) {
-    assert(image.record.value.kind === "blob" && image.record.value.mediaType.startsWith("image/"),
-      `${element.name}.${name} must reference image media`);
+): SurfaceResolvedReference {
+  const artifact = ref(element, name, artifactTypes.blob, resolve);
+  if (artifact.record !== undefined) {
+    assert(artifact.record.value.kind === "blob" && artifact.record.value.mediaType.startsWith(`${role}/`),
+      `${element.name}.${name} must reference ${role} media`);
   }
-  return image;
-}
-
-function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
-  return ({ element, resolveReference }) => {
-    exact(element);
-    assert(!element.children.some((item) => item.kind === "element" || item.value.trim()),
-      `${element.name} accepts no children`);
-    const id = text(element, "id");
-    const prompt = ref(element, "prompt", textTypes.text, resolveReference);
-    if (prompt.record !== undefined) {
-      assert(prompt.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
-      verifyText(prompt.record.value.value);
-    }
-    const frames = ([["firstFrame", "first-frame"], ["lastFrame", "last-frame"]] as const)
-      .flatMap(([port, attribute]) => {
-        const image = frame(element, attribute, resolveReference);
-        return image === undefined ? [] : [{ port, image }];
-      });
-    const stated: Record<string, readonly GenerationPortValue[] | undefined> = {
-      duration: integer(element, "duration"),
-      quality: [text(element, "quality")],
-      aspectRatio: optionalText(element, "aspect-ratio"),
-      generateAudio: optionalFlag(element, "generate-audio"),
-      multiClip: optionalFlag(element, "multi-clip"),
-      seed: element.attributes["seed"] === undefined ? undefined : integer(element, "seed"),
-    };
-    const draft = sealGenerationRequestDraft(endpoint.ports, Object.fromEntries(
-      Object.entries(stated).filter((entry): entry is [string, readonly GenerationPortValue[]] => entry[1] !== undefined),
-    ));
-    const records: Array<{ id: string; type: TypeRef; value: { kind: "inline"; value: CanonicalValue }; range: StructuredElement["range"] }> = [{
-      id: `${id}.draft`, type: endpoint.draftType,
-      value: { kind: "inline", value: draft as unknown as CanonicalValue }, range: element.range,
-    }];
-    const inputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
-      draft: { kind: "record", id: `${id}.draft` }, [exactModelTextInputName("prompt")]: prompt.ref,
-    };
-    const media = frames.map(({ port, image }, index) => {
-      const name = `media-${String(index + 1).padStart(4, "0")}`;
-      const bindingId = `${id}.${name}.binding`;
-      const mediaPort = generationPort(endpoint.ports, port);
-      assert(mediaPort.value.kind === "media", `PixVerse port ${port} is not media`);
-      records.push({
-        id: bindingId, type: endpoint.mediaBindings[port]!.type,
-        value: { kind: "inline", value: sealGenerationMediaBinding(mediaPort as GenerationMediaPort, { role: "image" }) as unknown as CanonicalValue },
-        range: element.range,
-      });
-      const names = exactModelMediaInputNames(name);
-      inputs[names.binding] = { kind: "record", id: bindingId };
-      inputs[names.artifact] = image.ref;
-      return { name, port } as const;
-    });
-    const fragment = createExactModelPrimaryGenerationFragment(endpoint, media, [{ name: "prompt", port: "prompt" }]);
-    return { records, fragments: [fragment], components: [{
-      id, fragment: fragment.id, inputs, outputs: { video: `${id}.video` }, range: element.range,
-    }] };
+  return artifact;
+}
+
+function empty(element: StructuredElement): void {
+  assert(!element.children.some((item) => item.kind === "element" || item.value.trim()),
+    `${element.name} accepts no children`);
+}
+
+function selectModel(element: StructuredElement): { endpoint: ExactModelEndpoint; model: PixverseModel } {
+  const requested = text(element, "model");
+  if (requested === "v6" || requested === "pixverse-v6") {
+    return { endpoint: pixverseEndpointsByModel["pixverse-v6"], model: "pixverse-v6" };
+  }
+  if (requested === "c1" || requested === "pixverse-c1") {
+    return { endpoint: pixverseEndpointsByModel["pixverse-c1"], model: "pixverse-c1" };
+  }
+  throw new Error(`${element.name}.model must be v6 or c1`);
+}
+
+/** A switch one model carries and the other does not is refused where it was authored. */
+function modelScoped(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  attribute: string,
+  port: string,
+  read: (element: StructuredElement, name: string) => readonly GenerationPortValue[] | undefined,
+): readonly GenerationPortValue[] | undefined {
+  if (element.attributes[attribute] === undefined) return undefined;
+  assert(endpoint.ports.ports.some((item) => item.name === port),
+    `${element.name}.${attribute} is not accepted by ${endpoint.ports.model}`);
+  return read(element, attribute);
+}
+
+function capacity(element: StructuredElement, endpoint: ExactModelEndpoint, port: string, used: number): void {
+  if (used === 0) return;
+  const declared = endpoint.ports.ports.find((item) => item.name === port);
+  assert(declared !== undefined, `${element.name} references are not accepted by ${endpoint.ports.model}`);
+  assert(used <= declared.maxItems,
+    `${element.name} accepts at most ${declared.maxItems} ${port === "referenceVideo" ? "video" : "image"} references on ${endpoint.ports.model}`);
+}
+
+function assemble(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  prompt: SurfaceResolvedReference,
+  inputs: readonly MediaInput[],
+  stated: Readonly<Record<string, readonly GenerationPortValue[] | undefined>>,
+) {
+  const id = text(element, "id");
+  const draft = sealGenerationRequestDraft(endpoint.ports, Object.fromEntries(
+    Object.entries(stated).filter((entry): entry is [string, readonly GenerationPortValue[]] => entry[1] !== undefined),
+  ));
+  const records: Array<{ id: string; type: TypeRef; value: { kind: "inline"; value: CanonicalValue }; range: StructuredElement["range"] }> = [{
+    id: `${id}.draft`, type: endpoint.draftType,
+    value: { kind: "inline", value: draft as unknown as CanonicalValue }, range: element.range,
+  }];
+  const componentInputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+    draft: { kind: "record", id: `${id}.draft` }, [exactModelTextInputName("prompt")]: prompt.ref,
   };
+  const attached = inputs.map(({ port, role, source }, index) => {
+    const name = `media-${String(index + 1).padStart(4, "0")}`;
+    const bindingId = `${id}.${name}.binding`;
+    const mediaPort = generationPort(endpoint.ports, port);
+    assert(mediaPort.value.kind === "media", `PixVerse port ${port} is not media`);
+    records.push({
+      id: bindingId, type: endpoint.mediaBindings[port]!.type,
+      value: { kind: "inline", value: sealGenerationMediaBinding(mediaPort as GenerationMediaPort, { role }) as unknown as CanonicalValue },
+      range: element.range,
+    });
+    const names = exactModelMediaInputNames(name);
+    componentInputs[names.binding] = { kind: "record", id: bindingId };
+    componentInputs[names.artifact] = source.ref;
+    return { name, port } as const;
+  });
+  const fragment = createExactModelPrimaryGenerationFragment(endpoint, attached, [{ name: "prompt", port: "prompt" }]);
+  return { records, fragments: [fragment], components: [{
+    id, fragment: fragment.id, inputs: componentInputs, outputs: { video: `${id}.video` }, range: element.range,
+  }] };
+}
+
+function promptReference(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const prompt = ref(element, "prompt", textTypes.text, resolveReference);
+  if (prompt.record !== undefined) {
+    assert(prompt.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
+    verifyText(prompt.record.value.value);
+  }
+  return prompt;
 }
 
-export const decodePixverseVideoSurface = decoder(pixverseEndpoints.video!);
+const VIDEO_ATTRIBUTES = ["id", "model", "prompt", "first-frame", "last-frame", "duration", "quality",
+  "aspect-ratio", "generate-audio", "multi-clip", "seed"] as const;
+
+export const decodePixverseVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, VIDEO_ATTRIBUTES, ["id", "model", "prompt", "duration", "quality"]);
+  empty(element);
+  const { endpoint } = selectModel(element);
+  const frames = ([["firstFrame", "first-frame"], ["lastFrame", "last-frame"]] as const)
+    .filter(([, attribute]) => element.attributes[attribute] !== undefined)
+    .map(([port, attribute]) => ({
+      port, role: "image" as const, source: media(element, attribute, "image", resolveReference),
+    }));
+  return assemble(element, endpoint, promptReference(element, resolveReference), frames, {
+    duration: integer(element, "duration"),
+    quality: [text(element, "quality")],
+    aspectRatio: optionalText(element, "aspect-ratio"),
+    generateAudio: optionalFlag(element, "generate-audio"),
+    multiClip: modelScoped(element, endpoint, "multi-clip", "multiClip", optionalFlag),
+    seed: modelScoped(element, endpoint, "seed", "seed", optionalInteger),
+  });
+};
+
+const REFERENCE_ATTRIBUTES = ["id", "model", "prompt", "duration", "quality",
+  "aspect-ratio", "generate-audio", "seed"] as const;
+
+export const decodePixverseReferenceVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, REFERENCE_ATTRIBUTES, ["id", "model", "prompt", "quality"]);
+  const { endpoint } = selectModel(element);
+  const references: MediaInput[] = [];
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      assert(child.value.trim().length === 0, `${element.name} accepts only Reference children`);
+      continue;
+    }
+    assert(localName(child.name) === "Reference", `${element.name} accepts only Reference children`);
+    empty(child);
+    const roles = (["image", "video"] as const).filter((role) => child.attributes[role] !== undefined);
+    exact(child, ["image", "video"], []);
+    assert(roles.length === 1, `${child.name} requires exactly one of image, video`);
+    const role = roles[0]!;
+    references.push({
+      port: role === "image" ? "referenceImage" : "referenceVideo",
+      role,
+      source: media(child, role, role, resolveReference),
+    });
+  }
+  assert(references.length > 0, `${element.name} requires at least one Reference`);
+  for (const port of ["referenceImage", "referenceVideo"] as const) {
+    capacity(element, endpoint, port, references.filter((item) => item.port === port).length);
+  }
+  const videos = references.some((item) => item.port === "referenceVideo");
+  if (videos) {
+    assert(element.attributes["duration"] === undefined,
+      `${element.name} takes no duration; its video references carry the length of the run`);
+  } else {
+    assert(element.attributes["duration"] !== undefined, `${element.name} requires duration`);
+  }
+  return assemble(element, endpoint, promptReference(element, resolveReference), references, {
+    duration: optionalInteger(element, "duration"),
+    quality: [text(element, "quality")],
+    aspectRatio: optionalText(element, "aspect-ratio"),
+    generateAudio: optionalFlag(element, "generate-audio"),
+    seed: modelScoped(element, endpoint, "seed", "seed", optionalInteger),
+  });
+};

package/packages/pixverse/src/validation.ts

@@ -0,0 +1,13 @@
+import type { GenerationRequest } from "@hypit/generation";
+import type { PixverseModel } from "./index.js";
+
+/**
+ * Reference videos carry the length of the run, so that mode states no duration.
+ * Every other mode states its own.
+ */
+export function pixverseRequestValidator(model: PixverseModel): (request: GenerationRequest) => void {
+  return (request) => {
+    if (request.ports.referenceVideo !== undefined || request.ports.duration !== undefined) return;
+    throw new Error(`${model} requires duration`);
+  };
+}

package/packages/provider-beatapi/README.md

@@ -0,0 +1,84 @@
+# `@hypit/provider-beatapi`
+
+Hypit Runtime Provider for a [BeatAPI](https://docs.beatapi.io/quick-guide) account. Each capability
+posts one task to `https://api.beatapi.io` with a `Bearer` API key, polls `GET /v1/tasks/{task_id}`
+until it reaches `succeeded`, downloads every entry of `output.media` and stores the files in the
+current Build.
+
+| Capability | BeatAPI model | Task path |
+| --- | --- | --- |
+| `@hypit/seedance@1#seedance-2` | `seedance-2` | `/v1/videos/tasks` |
+| `@hypit/seedance@1#seedance-2-fast` | `seedance-2-fast` | `/v1/videos/tasks` |
+| `@hypit/seedance@1#seedance-2-mini` | `seedance-2-mini` | `/v1/videos/tasks` |
+| `@hypit/seedance@1#seedance-2.5` | `seedance-2.5` | `/v1/videos/tasks` |
+| `@hypit/minimax-h3@1#minimax-h3` | `minimax-h3` | `/v1/videos/tasks` |
+| `@hypit/grok-imagine@1#grok-imagine-video-1.5-preview` | `grok-imagine-video-1.5` | `/v1/videos/tasks` |
+| `@hypit/gpt-image@1#gpt-image-2` | `gpt-image-2` | `/v1/images/tasks` |
+| `@hypit/nano-banana@1#nano-banana-2` | `nano-banana-2` | `/v1/images/tasks` |
+| `@hypit/nano-banana@1#nano-banana-pro` | `nano-banana-pro` | `/v1/images/tasks` |
+
+BeatAPI documents further models, including Veo, Kling, Wan 3.0 and HappyHorse; this Provider maps
+only the models the Distribution already describes.
+
+One BeatAPI alias serves every input mode, so the request shape alone decides which arrays travel:
+`reference_images`, `reference_videos` and `reference_audios` carry subject references, while the
+opening and closing frames travel as one ordered `images` array. `duration`, `aspect_ratio`,
+`resolution` and Seedance's `generate_audio` keep their authored values. Nano Banana 2 spells its
+JPEG output `jpeg`, so an authored `output-format="jpg"` is sent as that.
+
+Service limits this Provider reports as unsupported before uploading any reference:
+
+- Seedance has no `web_search` field, and `seedance-2-mini` renders no generated audio. An authored
+  `false` is dropped; an authored `true` is refused.
+- Seedance 2 does not render 1080p together with reference images.
+- Seedance 2.5 takes 4 to 30 seconds, so `duration="-1"` for an automatic length is refused.
+- MiniMax H3 orders its two frames first then last, so a last frame needs a first frame.
+- Grok Imagine 1.5 accepts at most one image at 1080p.
+- GPT Image 2 has no `background` field.
+- Nano Banana 2 accepts up to ten reference images and does not render `1:4`, `4:1`, `1:8` or `8:1`.
+
+Seedance visual references carry `person-reference`; the Provider accepts the declaration and
+transmits nothing for it, since BeatAPI's task body has no field for it.
+
+Referenced Resources are uploaded to `POST /v1/files` with `purpose=input`, and the returned HTTPS
+URL travels in the task body. The service accepts PNG, JPEG and WebP images and MP3, WAV, AAC and
+M4A audio up to 50 MB each, and MP4 and MOV video up to 100 MB; a reference outside those types or
+sizes is reported before submission. One Resource is uploaded once per Runtime operation. Embedded
+callers may replace that transport with `publicAssetUrl(artifact, resources, fields)`, which must
+return a URL BeatAPI can fetch.
+
+Runtime Profile example:
+
+```json
+{
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
+  "endpoints": {
+    "beatapi.default": {
+      "use": "@hypit/provider-beatapi",
+      "pool": "beatapi.default",
+      "config": {
+        "apiKey": { "store": "platform", "key": "beatapi.api-key" },
+        "defaultConcurrency": 3,
+        "pollIntervalMs": 10000
+      }
+    }
+  },
+  "bindings": {}
+}
+```
+
+`baseUrl` defaults to `https://api.beatapi.io`. Store the API key with
+`hypit auth login beatapi.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action
+concurrency. Each submission sends the Runtime operation as its `Idempotency-Key`, so a retried
+submission of the same body resolves to the same task.
+
+HTTP failures keep BeatAPI's `error.code`, message, `request_id` and any `retry_after_seconds`; a
+`failed` task keeps its `error_code` and `error_message`. Any URL inside a surfaced reason is
+redacted, since a hosted result URL is an access capability rather than diagnostic content.

package/packages/provider-beatapi/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hypit/provider-beatapi",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": { ".": "./src/index.ts" },
+  "hypit": { "activation": "./src/activation.ts" },
+  "dependencies": {
+    "@hypit/endpoint-kit": "workspace:*",
+    "@hypit/generation": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/gpt-image": "workspace:*",
+    "@hypit/grok-imagine": "workspace:*",
+    "@hypit/minimax-h3": "workspace:*",
+    "@hypit/nano-banana": "workspace:*",
+    "@hypit/seedance": "workspace:*"
+  }
+}

package/packages/provider-beatapi/src/activation.ts

@@ -0,0 +1,62 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigCredentialRef,
+  runtimeConfigActionLimits,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createBeatApiProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-beatapi",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("BeatAPI Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "BeatAPI");
+    runtimeConfigExact(config, [
+      "baseUrl",
+      "apiKey",
+      "defaultConcurrency",
+      "actionLimits",
+      "pollIntervalMs",
+      "requestTimeoutMs",
+      "operationTimeoutMs",
+    ], "BeatAPI");
+    const baseUrl = runtimeConfigString(config.baseUrl, "BeatAPI baseUrl");
+    if (baseUrl !== undefined) {
+      const url = new URL(baseUrl);
+      if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+        throw new Error("BeatAPI baseUrl must use HTTPS or loopback");
+      }
+    }
+    const apiKey = runtimeConfigCredentialRef(config.apiKey, "BeatAPI apiKey");
+    if (apiKey === undefined) throw new Error("BeatAPI apiKey CredentialRef is required");
+    const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "BeatAPI defaultConcurrency");
+    const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "BeatAPI pollIntervalMs");
+    const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "BeatAPI requestTimeoutMs");
+    const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "BeatAPI operationTimeoutMs");
+    return {
+      endpoint: createBeatApiProvider({
+        instance: context.instance,
+        pool: context.pool,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        apiKey,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(actionLimits === undefined ? {} : { actionLimits }),
+        ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+        ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+        ...(operationTimeoutMs === undefined ? {} : { operationTimeoutMs }),
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [adapter],
+};
+
+export default hypitPackage;

package/packages/provider-beatapi/src/errors.ts

@@ -0,0 +1,46 @@
+/** BeatAPI's `{ error: { code, message, request_id, retry_after_seconds } }` envelope and terminal task errors. */
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a hosted result URL. Keep the reason, not its access capability.
+export function safeBeatApiReason(value: string): string {
+  return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class BeatApiServiceError extends Error {
+  constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class BeatApiHttpError extends BeatApiServiceError {
+  constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,
+    request: { readonly method: string; readonly path: string; readonly model?: string }) {
+    let body: Record<string, unknown> | undefined;
+    try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+    const error = record(body?.error);
+    const code = text(error?.code) ?? "BEATAPI_HTTP_ERROR";
+    const reason = text(error?.message) ?? (error === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+    const requestId = text(error?.request_id) ?? text(response.headers.get("x-request-id"));
+    const retryAfter = typeof error?.retry_after_seconds === "number" ? error.retry_after_seconds : undefined;
+    const facts = [
+      `BeatAPI HTTP ${status}`, code, `${request.method} ${request.path}`,
+      ...(request.model === undefined ? [] : [`model=${request.model}`]),
+      ...(requestId === undefined ? [] : [`request=${requestId}`]),
+      ...(retryAfter === undefined ? [] : [`retry-after=${retryAfter}s`]),
+    ];
+    super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safeBeatApiReason(reason)}`}`);
+  }
+}
+
+/** A terminal `failed` task; `undefined` otherwise. */
+export function beatApiTaskFailure(task: Record<string, unknown>, id: string): BeatApiServiceError | undefined {
+  if (task.status !== "failed") return undefined;
+  const code = text(task.error_code) ?? "BEATAPI_TASK_FAILED";
+  const reason = text(task.error_message);
+  return new BeatApiServiceError(code,
+    `BeatAPI task ${id} failed; ${code}${reason === undefined ? "" : `: ${safeBeatApiReason(reason)}`}`);
+}

package/packages/provider-beatapi/src/index.ts

@@ -0,0 +1,2 @@
+export { createBeatApiProvider, beatApiProviderModuleRef } from "./provider.js";
+export type { CreateBeatApiProviderOptions } from "./provider.js";

package/packages/provider-beatapi/src/mapping.ts

@@ -0,0 +1,89 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };
+const GPT_IMAGE: ModuleRef = { name: "@hypit/gpt-image", version: "1" };
+const NANO_BANANA: ModuleRef = { name: "@hypit/nano-banana", version: "1" };
+
+/**
+ * BeatAPI model aliases and the body fields each one documents. One alias serves every input mode,
+ * so each Capability has a single route and the request shape alone decides which arrays travel.
+ *
+ * BeatAPI carries the opening and closing frames as one ordered `images` array rather than two
+ * fields. The mapping writes them to `first_frame` and `last_frame`, which routes.ts folds into
+ * that array; a mapping cannot write one wire field from two ports.
+ */
+const seedanceFields = {
+  prompt: { as: "value", field: "prompt" },
+  firstFrame: { as: "url", field: "first_frame", resourceFields: ["personReference"] },
+  lastFrame: { as: "url", field: "last_frame", resourceFields: ["personReference"] },
+  referenceImage: { as: "urlArray", field: "reference_images", resourceFields: ["personReference"] },
+  referenceVideo: { as: "urlArray", field: "reference_videos", resourceFields: ["personReference"] },
+  referenceAudio: { as: "urlArray", field: "reference_audios" },
+  duration: { as: "value", field: "duration" },
+  aspectRatio: { as: "value", field: "aspect_ratio" },
+  resolution: { as: "value", field: "resolution" },
+  generateAudio: { as: "value", field: "generate_audio" },
+  webSearch: { as: "value", field: "web_search" },
+} as const satisfies GenerationWireMapping["fields"];
+
+const seedance = (name: string): GenerationWireMapping => ({
+  capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: name }], fields: seedanceFields,
+});
+
+export const beatApiMappings: readonly GenerationWireMapping[] = [
+  seedance("seedance-2"),
+  seedance("seedance-2-fast"),
+  seedance("seedance-2-mini"),
+  seedance("seedance-2.5"),
+  {
+    capability: { module: MINIMAX, name: "minimax-h3" }, result: "video",
+    routes: [{ model: "minimax-h3" }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      firstFrame: { as: "url", field: "first_frame" },
+      lastFrame: { as: "url", field: "last_frame" },
+      referenceImage: { as: "urlArray", field: "reference_images" },
+      referenceVideo: { as: "urlArray", field: "reference_videos" },
+      referenceAudio: { as: "urlArray", field: "reference_audios" },
+      duration: { as: "value", field: "duration" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      resolution: { as: "value", field: "resolution" },
+    },
+  },
+  {
+    capability: { module: GROK, name: "grok-imagine-video-1.5-preview" }, result: "video",
+    routes: [{ model: "grok-imagine-video-1.5" }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      images: { as: "urlArray", field: "reference_images" },
+      duration: { as: "value", field: "duration" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      resolution: { as: "value", field: "resolution" },
+    },
+  },
+  {
+    capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image",
+    routes: [{ model: "gpt-image-2" }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      images: { as: "urlArray", field: "images" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      resolution: { as: "value", field: "resolution" },
+      background: { as: "value", field: "background" },
+    },
+  },
+  ...(["nano-banana-2", "nano-banana-pro"] as const).map((model) => ({
+    capability: { module: NANO_BANANA, name: model }, result: "image" as const,
+    routes: [{ model }],
+    fields: {
+      prompt: { as: "value" as const, field: "prompt" },
+      images: { as: "urlArray" as const, field: "images" },
+      aspectRatio: { as: "value" as const, field: "aspect_ratio" },
+      resolution: { as: "value" as const, field: "resolution" },
+      outputFormat: { as: "value" as const, field: "output_format" },
+    },
+  })),
+];