@hypit/provider-sume 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+# Open Source License
+
+Hypit is licensed under a modified version of the Apache License 2.0, with the following additional conditions:
+
+1. Hypit may be utilized commercially for your own organization's purposes, including as a rendering or generation backend for applications your organization operates for itself, and as internal tooling within an enterprise. Should any of the conditions below be met, a commercial license must be obtained from the producer:
+
+a. Multi-tenant service: Unless explicitly authorized by Hypit.AI in writing, you may not use the Hypit source code, or any derivative work of it, to operate a multi-tenant environment, or to offer Hypit's functionality to third parties as a hosted, managed, or software-as-a-service offering.
+    - Tenant Definition: Within the context of Hypit, one tenant corresponds to one workspace — the isolated set of projects, artifacts, credentials, and configuration belonging to a single party. Operating an environment in which two or more parties outside your own organization hold separate workspaces constitutes a multi-tenant service, whether or not a fee is charged.
+
+b. Commercial redistribution: Unless explicitly authorized by Hypit.AI in writing, you may not sell, license for a fee, or otherwise supply for commercial gain Hypit or any derivative work of it, whether standalone or as a component of, or bundled with, any product, application, package, or device provided to third parties.
+    - Forking, modifying, and publishing the source code of Hypit or a derivative work is permitted, provided the result is made available under the terms of this same license and is not supplied for commercial gain.
+
+    - Permitted without a commercial license under clauses (a) and (b): obtaining Hypit and running it yourself on your own infrastructure; using it for your own organization's work, including commercial work and work performed for your clients; and single-tenant deployments operated by and for one organization.
+
+c. LOGO and copyright information: In the process of using Hypit, you may not remove or modify the name, LOGO, or copyright information presented in the Hypit command-line interface, its generated run reports and manifests, or any user-facing surface derived from them. This restriction is inapplicable to uses of Hypit that do not surface these components to a user.
+
+2. As a contributor, you should agree that:
+
+a. The producer can adjust the open-source agreement to be more strict or relaxed as deemed necessary.
+b. Your contributed code may be used for commercial purposes, including but not limited to its cloud business operations.
+
+3. Ownership of output: The producer claims no rights in the content you create with Hypit. Videos, audio, images, manifests, and any other artifacts produced through your use of Hypit belong to you, and this license imposes no conditions on their use — including commercial use. Note that content generated by way of third-party model or service providers may additionally be subject to the terms of those providers.
+
+Apart from the specific conditions mentioned above, all other rights and restrictions follow the Apache License 2.0. Detailed information about the Apache License 2.0 can be found at http://www.apache.org/licenses/LICENSE-2.0.
+
+© 2026 Hypit.AI

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# `@hypit/provider-sume`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional Provider, not installed with Hypit. Install in the video project:
+
+```bash
+npm install @hypit/provider-sume
+```
+
+Hypit Runtime Provider for a [Sume](https://docs.sume.com/public-api) API key. Each capability
+submits one asynchronous job to `https://api.sume.com` with a `Bearer` API key, polls
+`GET /v1/jobs/{id}/status` until the job is terminal, reads the generated files from
+`GET /v1/jobs/{id}/result` and stores them in the current Build.
+
+| Capability | Sume model | Submit path |
+| --- | --- | --- |
+| `@hypit/seedance@1#seedance-2` | `seedance-2` | `/v1/video-router/generate` |
+| `@hypit/seedance@1#seedance-2-fast` | `seedance-2-fast` | `/v1/video-router/generate` |
+| `@hypit/seedance@1#seedance-2-mini` | `seedance-2-mini` | `/v1/video-router/generate` |
+| `@hypit/seedance@1#seedance-2.5` | `seedance-2.5` | `/v1/video-router/generate` |
+| `@hypit/minimax-h3@1#minimax-h3` | `minimax-h3` | `/v1/video-router/generate` |
+| `@hypit/grok-imagine@1#grok-imagine-video-1.5-preview` | `grok-imagine-video-1.5` | `/v1/video-router/generate` |
+| `@hypit/pixverse@1#pixverse-v6` | `pixverse-v6` | `/v1/video-router/generate` |
+| `@hypit/pixverse@1#pixverse-c1` | `pixverse-c1` | `/v1/video-router/generate` |
+| `@hypit/gpt-image@1#gpt-image-2` | `openai/gpt-image-2` | `/v1/images` |
+| `@hypit/nano-banana@1#nano-banana-2` | `google/nano-banana-2.1` | `/v1/images` |
+| `@hypit/nano-banana@1#nano-banana-pro` | `google/nano-banana-pro` | `/v1/images` |
+| `@hypit/seedream@1#seedream-5-lite` | `bytedance-seed/seedream-5-lite` | `/v1/images` |
+
+Sume's [video](https://docs.sume.com/models/videos.md) and [image](https://docs.sume.com/models/images.md)
+catalogs list further models; this Provider maps only the models the Distribution already describes.
+Sume serves Nano Banana 2 as its successor, Nano Banana 2.1, so a `nano-banana-2` request renders on
+`google/nano-banana-2.1`.
+
+Video jobs carry the opening and closing frames as `image_url` and `end_image_url`, and references as
+`reference_image_urls`, `reference_video_urls` and `reference_audio_urls`. Image jobs carry their
+references as `input_references`. Every submission uses `mode: "async"`. `duration`, `aspect_ratio`,
+`resolution` and `generate_audio` keep their authored values, except that MiniMax H3's `768P` is sent
+as `768p`, PixVerse's `quality` travels as `resolution`, and Nano Banana's `jpg` output format is sent
+as `jpeg`. A Grok Imagine 1.5 image travels as the first frame, and the first frame then sets the
+shape, so the authored aspect ratio is not sent with it.
+
+Service limits this Provider reports as unsupported before uploading any reference:
+
+- Seedance has no `web_search` field. An authored `false` is dropped; an authored `true` is refused.
+- Seedance 2.5 takes 4 to 30 seconds, so `duration="-1"` for an automatic length is refused.
+- MiniMax H3 takes 5 to 15 seconds.
+- Grok Imagine 1.5 takes a prompt alone or one first-frame image, does not render `2:3` or `3:2`, and
+  needs an explicit aspect ratio without an image.
+- PixVerse V6 and C1 take a prompt or reference images, without frames, reference videos, a seed or
+  multi-clip, for 2 to 15 seconds, and do not render `2:3`, `3:2` or `auto`.
+- GPT Image 2 has no `background` field, accepts up to ten reference images and does not render
+  `3:2`, `2:3`, `2:1`, `1:2`, `3:1`, `1:3`, `21:9` or `9:21`.
+- Nano Banana 2.1 accepts up to ten reference images.
+- Seedream 5.0 lite renders at 2K, which is `quality="basic"`; accepts up to ten reference images;
+  does not render `21:9`; and has no switch to turn its content check off, so `nsfw-check="false"` is
+  refused.
+
+Seedance visual references carry `person-reference`; the Provider accepts the declaration and
+transmits nothing for it, since Sume's request body has no field for it.
+
+Referenced Resources are uploaded through `POST /v1/files/generate-upload-url`: the Provider PUTs the
+bytes to the returned presigned URL and sends the returned public `media.sume.com` URL in the job. One
+Resource is uploaded once per Runtime operation. Embedded callers may replace that transport with
+`publicAssetUrl(artifact, resources, fields)`, which must return a public HTTPS URL Sume can fetch.
+
+Runtime Profile example:
+
+```json
+{
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "local": {
+      "use": "@hypit/credential-store-local"
+    }
+  },
+  "endpoints": {
+    "sume.default": {
+      "use": "@hypit/provider-sume",
+      "pool": "sume.default",
+      "config": {
+        "apiKey": { "store": "local", "key": "sume.api-key" },
+        "defaultConcurrency": 2,
+        "pollIntervalMs": 5000
+      }
+    }
+  },
+  "bindings": {}
+}
+```
+
+`baseUrl` defaults to `https://api.sume.com`. Store the API key with
+`hypit auth login sume.default --runtime hypit.runtime.json`. `defaultConcurrency` defaults to 2,
+which is the number of jobs Sume's free plan runs at once; raise it to the workspace's plan limit.
+Optional `requestTimeoutMs`, `operationTimeoutMs` and `actionLimits` bound single HTTP calls, the
+whole remote job 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 job and is charged
+once.
+
+HTTP failures keep Sume's `error.code`, message, `details`, `request_id` and any
+`retry_after_seconds`; a failed or canceled job keeps its error code, message and the upstream
+provider's message. Any URL inside a surfaced reason is redacted, since an upload or result URL is an
+access capability rather than diagnostic content. Polling transport failures and HTTP 429/5xx
+preserve the same job. Sume's `retry_after_seconds` takes precedence over the standard `Retry-After`
+header; either wait is capped at the original operation deadline, where the next poll concludes
+timeout without querying early.

package/dist/activation.d.ts

@@ -0,0 +1,5 @@
+export declare const hypitPackage: {
+    format: "hypit.package@1";
+    facets: import("@hypit/runtime-local/extension").RuntimeAdapterFacet[];
+};
+export default hypitPackage;

package/dist/activation.js

@@ -0,0 +1,52 @@
+import { createRuntimeEndpointAdapterFacet, runtimeConfigCredentialRef, runtimeConfigActionLimits, runtimeConfigExact, runtimeConfigObject, runtimeConfigPositiveInteger, runtimeConfigString, } from "@hypit/runtime-local/extension";
+import { createSumeProvider } from "./provider.js";
+const adapter = createRuntimeEndpointAdapterFacet({
+    use: "@hypit/provider-sume",
+    activate(context) {
+        if (context.pool === undefined)
+            throw new Error("Sume Provider Pool is required");
+        const config = runtimeConfigObject(context.config, "Sume");
+        runtimeConfigExact(config, [
+            "baseUrl",
+            "apiKey",
+            "defaultConcurrency",
+            "actionLimits",
+            "pollIntervalMs",
+            "requestTimeoutMs",
+            "operationTimeoutMs",
+        ], "Sume");
+        const baseUrl = runtimeConfigString(config.baseUrl, "Sume 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("Sume baseUrl must use HTTPS or loopback");
+            }
+        }
+        const apiKey = runtimeConfigCredentialRef(config.apiKey, "Sume apiKey");
+        if (apiKey === undefined)
+            throw new Error("Sume apiKey CredentialRef is required");
+        const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+        const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "Sume defaultConcurrency");
+        const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "Sume pollIntervalMs");
+        const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "Sume requestTimeoutMs");
+        const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "Sume operationTimeoutMs");
+        return {
+            endpoint: createSumeProvider({
+                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.package@1",
+    facets: [adapter],
+};
+export default hypitPackage;

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+import { EndpointServiceError } from "@hypit/hypit/endpoint";
+import { EndpointHttpError } from "@hypit/hypit/endpoint/http";
+export declare function safeSumeReason(value: string): string;
+export declare class SumeServiceError extends EndpointServiceError {
+}
+export declare class SumeHttpError extends EndpointHttpError {
+    constructor(status: number, response: {
+        readonly headers: Headers;
+    }, bodyText: string, request: {
+        readonly method: string;
+        readonly path: string;
+        readonly model?: string;
+    });
+}
+/** A terminal `failed` or `canceled` job; `undefined` otherwise. */
+export declare function sumeJobFailure(status: string, job: Record<string, unknown> | undefined, id: string): SumeServiceError | undefined;

package/dist/errors.js

@@ -0,0 +1,50 @@
+import { EndpointServiceError } from "@hypit/hypit/endpoint";
+import { EndpointHttpError, retryAfterMs } from "@hypit/hypit/endpoint/http";
+/** Sume's `{ error: { code, message, request_id, retry_after_seconds, details } }` envelope and failed jobs. */
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
+}
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+// Responses may carry a signed upload or result URL. Keep the reason, not its access capability.
+export function safeSumeReason(value) {
+    return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+export class SumeServiceError extends EndpointServiceError {
+}
+export class SumeHttpError extends EndpointHttpError {
+    constructor(status, response, bodyText, request) {
+        let body;
+        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) ?? "SUME_HTTP_ERROR";
+        const reason = text(error?.message) ?? (error === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+        const details = error?.details === undefined ? undefined : JSON.stringify(error.details).slice(0, 1000);
+        const requestId = text(error?.request_id) ?? text(response.headers.get("x-sume-request-id"));
+        const serviceRetryAfter = typeof error?.retry_after_seconds === "number" ? Math.round(error.retry_after_seconds * 1000) : undefined;
+        const retryAfter = serviceRetryAfter ?? retryAfterMs(response.headers);
+        const facts = [
+            `Sume HTTP ${status}`, code, `${request.method} ${request.path}`,
+            ...(request.model === undefined ? [] : [`model=${request.model}`]),
+            ...(requestId === undefined ? [] : [`request=${requestId}`]),
+            ...(retryAfter === undefined ? [] : [`retry-after=${retryAfter}ms`]),
+        ];
+        const message = [reason, details].filter((item) => item !== undefined).join(" ");
+        super(code, `${facts.join("; ")}${message.length === 0 ? "" : `: ${safeSumeReason(message)}`}`, status, retryAfter);
+    }
+}
+/** A terminal `failed` or `canceled` job; `undefined` otherwise. */
+export function sumeJobFailure(status, job, id) {
+    if (status !== "failed" && status !== "canceled")
+        return undefined;
+    const error = record(job?.error);
+    const code = text(error?.code) ?? text(error?.public_reason) ?? (status === "canceled" ? "SUME_JOB_CANCELED" : "SUME_JOB_FAILED");
+    const upstream = text(record(error?.details)?.provider_error_message);
+    const reason = [text(error?.message) ?? text(job?.error), upstream].filter((item) => item !== undefined).join(" ") || undefined;
+    return new SumeServiceError(code, `Sume job ${id} ${status}; ${code}${reason === undefined ? "" : `: ${safeSumeReason(reason)}`}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createSumeProvider, sumeProviderModuleRef } from "./provider.js";
+export type { CreateSumeProviderOptions } from "./provider.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { createSumeProvider, sumeProviderModuleRef } from "./provider.js";

package/dist/mapping.d.ts

@@ -0,0 +1,2 @@
+import type { GenerationWireMapping } from "@hypit/generation";
+export declare const sumeMappings: readonly GenerationWireMapping[];

package/dist/mapping.js

@@ -0,0 +1,120 @@
+const SEEDANCE = { name: "@hypit/seedance", version: "1" };
+const MINIMAX = { name: "@hypit/minimax-h3", version: "1" };
+const GROK = { name: "@hypit/grok-imagine", version: "1" };
+const PIXVERSE = { name: "@hypit/pixverse", version: "1" };
+const GPT_IMAGE = { name: "@hypit/gpt-image", version: "1" };
+const NANO_BANANA = { name: "@hypit/nano-banana", version: "1" };
+const SEEDREAM = { name: "@hypit/seedream", version: "1" };
+/**
+ * Sume catalog ids and the body fields each one documents.
+ *
+ * Video models post to `POST /v1/video-router/generate`, whose body carries every reference as a
+ * flat URL field. Image models post to `POST /v1/images`; its `input_references` array of
+ * `{ type, image_url: { url } }` objects is built in routes.ts from the `images` URLs written here.
+ * Ports the service has no field for are written under their own names so routes.ts can drop an
+ * authored "off" value and refuse an authored "on" value before anything is uploaded.
+ */
+const seedanceFields = {
+    prompt: { as: "value", field: "prompt" },
+    firstFrame: { as: "url", field: "image_url", resourceFields: ["personReference"] },
+    lastFrame: { as: "url", field: "end_image_url", resourceFields: ["personReference"] },
+    referenceImage: { as: "urlArray", field: "reference_image_urls", resourceFields: ["personReference"] },
+    referenceVideo: { as: "urlArray", field: "reference_video_urls", resourceFields: ["personReference"] },
+    referenceAudio: { as: "urlArray", field: "reference_audio_urls" },
+    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" },
+};
+const seedance = (name) => ({
+    capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: name }], fields: seedanceFields,
+});
+const pixverse = (name) => ({
+    capability: { module: PIXVERSE, name }, result: "video", routes: [{ model: name }],
+    fields: {
+        prompt: { as: "value", field: "prompt" },
+        firstFrame: { as: "url", field: "image_url" },
+        lastFrame: { as: "url", field: "end_image_url" },
+        referenceImage: { as: "urlArray", field: "reference_image_urls" },
+        ...(name === "pixverse-v6" ? {
+            referenceVideo: { as: "urlArray", field: "reference_video_urls" },
+            multiClip: { as: "value", field: "multi_clip" },
+            seed: { as: "value", field: "seed" },
+        } : {}),
+        duration: { as: "value", field: "duration" },
+        // PixVerse's quality band is Sume's resolution.
+        quality: { as: "value", field: "resolution" },
+        aspectRatio: { as: "value", field: "aspect_ratio" },
+        generateAudio: { as: "value", field: "generate_audio" },
+    },
+});
+export const sumeMappings = [
+    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: "image_url" },
+            lastFrame: { as: "url", field: "end_image_url" },
+            referenceImage: { as: "urlArray", field: "reference_image_urls" },
+            referenceVideo: { as: "urlArray", field: "reference_video_urls" },
+            referenceAudio: { as: "urlArray", field: "reference_audio_urls" },
+            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: "images" },
+            duration: { as: "value", field: "duration" },
+            aspectRatio: { as: "value", field: "aspect_ratio" },
+            resolution: { as: "value", field: "resolution" },
+        },
+    },
+    pixverse("pixverse-v6"),
+    pixverse("pixverse-c1"),
+    {
+        capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image",
+        routes: [{ model: "openai/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" },
+        },
+    },
+    // Sume serves Nano Banana 2 as its successor, Nano Banana 2.1.
+    ...[["nano-banana-2", "google/nano-banana-2.1"], ["nano-banana-pro", "google/nano-banana-pro"]].map(([name, model]) => ({
+        capability: { module: NANO_BANANA, name }, result: "image",
+        routes: [{ model }],
+        fields: {
+            prompt: { as: "value", field: "prompt" },
+            images: { as: "urlArray", field: "images" },
+            aspectRatio: { as: "value", field: "aspect_ratio" },
+            resolution: { as: "value", field: "resolution" },
+            outputFormat: { as: "value", field: "output_format" },
+        },
+    })),
+    {
+        capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image",
+        routes: [{ model: "bytedance-seed/seedream-5-lite" }],
+        fields: {
+            prompt: { as: "value", field: "prompt" },
+            images: { as: "urlArray", field: "images" },
+            aspectRatio: { as: "value", field: "aspect_ratio" },
+            quality: { as: "value", field: "quality" },
+            outputFormat: { as: "value", field: "output_format" },
+            nsfwCheck: { as: "value", field: "nsfw_check" },
+        },
+    },
+];

package/dist/provider.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialRef, EndpointActionLimits, ResourceStore } from "@hypit/hypit/endpoint";
+import type { BlobRef } from "@hypit/hypit/protocol";
+export declare const sumeProviderModuleRef: {
+    readonly name: "@hypit/provider-sume";
+    readonly version: "1";
+};
+export type CreateSumeProviderOptions = {
+    readonly instance?: string;
+    readonly pool?: string;
+    readonly baseUrl?: string;
+    readonly apiKey?: CredentialRef;
+    readonly defaultConcurrency?: number;
+    readonly actionLimits?: EndpointActionLimits;
+    readonly pollIntervalMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly operationTimeoutMs?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    /** Publish a referenced Resource at a URL the service can fetch; replaces Sume's upload URL. */
+    readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
+};
+export declare function createSumeProvider(options?: CreateSumeProviderOptions): import("@hypit/hypit/endpoint").EndpointInstance;

package/dist/provider.js

@@ -0,0 +1,252 @@
+import { EndpointServiceError, credentialRef, defineEndpoint, wakeAfter } from "@hypit/hypit/endpoint";
+import { EndpointHttpError, EndpointResponseError, EndpointTransportError, withRequestDeadline } from "@hypit/hypit/endpoint/http";
+import { canonicalize } from "@hypit/hypit/protocol";
+import { sumeRouteForCapability, sumeRoutes } from "./routes.js";
+import { SumeHttpError, SumeServiceError, sumeJobFailure } from "./errors.js";
+export const sumeProviderModuleRef = { name: "@hypit/provider-sume", version: "1" };
+const extensions = {
+    "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp",
+    "audio/mpeg": "mp3", "audio/wav": "wav", "audio/x-wav": "wav", "audio/aac": "aac", "audio/mp4": "m4a",
+    "video/mp4": "mp4", "video/quicktime": "mov", "video/webm": "webm",
+};
+function assert(condition, message) { if (!condition)
+    throw new Error(message); }
+function object(value, subject) {
+    assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+    return value;
+}
+function apiBaseUrl(value) {
+    let trimmed = value.trim();
+    while (trimmed.endsWith("/"))
+        trimmed = trimmed.slice(0, -1);
+    assert(trimmed.length > 0, "Sume base URL is empty");
+    return trimmed;
+}
+function apiKey(credentials) {
+    const value = credentials.apiKey?.secret;
+    if (typeof value !== "string" || value.length === 0) {
+        throw new SumeServiceError("SUME_CREDENTIAL_UNAVAILABLE", "Sume apiKey credential is unavailable; store a Sume API key for this Endpoint");
+    }
+    return value;
+}
+function httpsUrl(value, subject) {
+    assert(typeof value === "string" && /^https:\/\//u.test(value), `${subject} has no HTTPS URL`);
+    return value;
+}
+function failure(error) {
+    if (!(error instanceof EndpointServiceError || error instanceof EndpointHttpError
+        || error instanceof EndpointTransportError || error instanceof EndpointResponseError))
+        throw error;
+    const code = error instanceof EndpointServiceError || error instanceof EndpointHttpError ? error.code : "SUME_ERROR";
+    return { status: "failed", failure: { code, message: error.message } };
+}
+function retrying(error, handle, pollIntervalMs, deadlineAt) {
+    const delay = error instanceof EndpointTransportError ? pollIntervalMs
+        : error instanceof EndpointHttpError && (error.status === 429 || error.status >= 500)
+            ? error.retryAfterMs ?? pollIntervalMs : undefined;
+    if (delay === undefined)
+        return undefined;
+    return { status: "pending", handle, wakeAt: Math.min(Date.now() + delay, deadlineAt ?? Number.MAX_SAFE_INTEGER), progress: { phase: "retrying" } };
+}
+function unknownSubmission(error) {
+    return error instanceof EndpointTransportError ? { status: "failed", failure: {
+            code: "SUME_SUBMISSION_UNKNOWN",
+            message: `Sume submission transport failed; remote outcome is unknown: ${error.message}`,
+        } } : undefined;
+}
+class SumeClient {
+    baseUrl;
+    timeout;
+    fetcher;
+    constructor(baseUrl, timeout, fetcher) {
+        this.baseUrl = baseUrl;
+        this.timeout = timeout;
+        this.fetcher = fetcher;
+    }
+    /** One authenticated call; returns the `data` member of Sume's envelope. */
+    async json(path, key, init = {}) {
+        return await withRequestDeadline(this.timeout, async ({ signal, wait }) => {
+            const response = await wait(this.fetcher(`${this.baseUrl}${path}`, {
+                ...init, signal, headers: { authorization: `Bearer ${key}`, ...(init.headers ?? {}) },
+            }));
+            const text = await wait(response.text());
+            if (!response.ok) {
+                const input = typeof init.body === "string" ? JSON.parse(init.body) : undefined;
+                throw new SumeHttpError(response.status, response, text, {
+                    method: init.method ?? "GET", path, ...(typeof input?.model === "string" ? { model: input.model } : {}),
+                });
+            }
+            let body;
+            try {
+                body = text.length === 0 ? {} : JSON.parse(text);
+            }
+            catch {
+                throw new EndpointResponseError(`Sume returned invalid JSON (${response.status})`);
+            }
+            return object(object(body, "Sume response").data, "Sume response data");
+        }, () => new EndpointTransportError("Sume request timed out", { timeout: true }));
+    }
+    /** Ask for an upload URL, PUT the Resource there and return the public HTTPS URL a job reads. */
+    async upload(artifact, resources, key) {
+        const kind = artifact.mediaType.split("/", 1)[0] ?? "";
+        assert(kind === "image" || kind === "video" || kind === "audio", `Sume accepts image, audio and video references, not ${artifact.mediaType}`);
+        const bytes = await resources.get(artifact.resource);
+        assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);
+        const slot = await this.json("/v1/files/generate-upload-url", key, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                content_type: artifact.mediaType,
+                size_bytes: artifact.size,
+                filename: `${artifact.resource}.${extensions[artifact.mediaType] ?? "bin"}`,
+            }),
+        });
+        const uploadUrl = httpsUrl(slot.upload_url, "Sume upload slot");
+        const headers = slot.upload_headers === undefined ? {} : object(slot.upload_headers, "Sume upload headers");
+        await withRequestDeadline(this.timeout, async ({ signal, wait }) => {
+            const response = await wait(this.fetcher(uploadUrl, {
+                method: "PUT", signal, headers: { "content-type": artifact.mediaType, ...headers }, body: new Uint8Array(bytes),
+            }));
+            // The upload URL is presigned; its path is a credential and stays out of the error.
+            if (!response.ok)
+                throw new SumeHttpError(response.status, response, "", { method: "PUT", path: "[upload-url]" });
+            await wait(response.arrayBuffer());
+        }, () => new EndpointTransportError("Sume upload timed out", { timeout: true }));
+        return httpsUrl(slot.public_url, "Sume upload slot");
+    }
+    async download(url) {
+        return await withRequestDeadline(this.timeout, async ({ signal, wait }) => {
+            const response = await wait(this.fetcher(url, { signal }));
+            if (!response.ok)
+                throw new SumeHttpError(response.status, response, "", { method: "GET", path: "[result-url]" });
+            return { bytes: new Uint8Array(await wait(response.arrayBuffer())), mediaType: response.headers.get("content-type")?.split(";", 1)[0] ?? "application/octet-stream" };
+        }, () => new EndpointTransportError("Sume download timed out", { timeout: true }));
+    }
+}
+function resolverFor(client, context, publicAssetUrl) {
+    const resolved = new Map();
+    return (artifact, fields) => {
+        const existing = resolved.get(artifact.resource);
+        if (existing !== undefined)
+            return existing;
+        const promise = publicAssetUrl === undefined
+            ? client.upload(artifact, context.resources, apiKey(context.credentials))
+            : publicAssetUrl(artifact, context.resources, fields);
+        resolved.set(artifact.resource, promise);
+        return promise;
+    };
+}
+/** Job statuses before a terminal one. */
+const pendingStatuses = ["queued", "processing"];
+function endpoint(client, pollIntervalMs, maxOperationMs, publicAssetUrl) {
+    return {
+        async start(context) {
+            try {
+                const route = sumeRouteForCapability(context.need.capability);
+                assert(route !== undefined, "Sume does not implement this exact capability");
+                const request = route.prepare(context.need.constraints);
+                await context.reportProgress?.({ phase: `Preparing Sume request: ${request.model}` });
+                const body = await request.compile(resolverFor(client, context, publicAssetUrl));
+                await context.reportProgress?.({ phase: `Submitting Sume request: ${request.model}` });
+                let response;
+                try {
+                    response = await client.json(request.media === "image" ? "/v1/images" : "/v1/video-router/generate", apiKey(context.credentials), {
+                        method: "POST",
+                        headers: { "content-type": "application/json", "idempotency-key": context.operation },
+                        body: JSON.stringify(body),
+                    });
+                }
+                catch (error) {
+                    const unknown = unknownSubmission(error);
+                    if (unknown !== undefined)
+                        return unknown;
+                    throw error;
+                }
+                const job = response.job === undefined ? undefined : object(response.job, "Sume job");
+                const jobId = job?.id ?? response.request_id;
+                if (typeof jobId !== "string" || jobId.length === 0)
+                    throw new EndpointResponseError("Sume response has no job id");
+                const handle = { contract: "hypit.sume-operation@1", jobId, route: route.key, startedAt: Date.now() };
+                const receipt = { id: jobId };
+                await context.checkpoint?.({ handle: canonicalize(handle), receipt });
+                return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: "submitted" }), receipt };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+        async poll(context) {
+            let operationDeadlineAt;
+            try {
+                const handle = object(context.handle, "Sume handle");
+                const route = sumeRouteForCapability(context.need.capability);
+                assert(route !== undefined && handle.contract === "hypit.sume-operation@1" && handle.route === route.key, "Sume handle is invalid");
+                const receipt = { id: handle.jobId };
+                operationDeadlineAt = handle.startedAt + maxOperationMs;
+                if (Date.now() >= operationDeadlineAt) {
+                    return { status: "failed", receipt, failure: { code: "SUME_OPERATION_TIMEOUT", message: `Sume job ${handle.jobId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };
+                }
+                const key = apiKey(context.credentials);
+                const id = encodeURIComponent(handle.jobId);
+                const state = await client.json(`/v1/jobs/${id}/status`, key);
+                const status = String(state.sume_status);
+                if (pendingStatuses.includes(status)) {
+                    return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };
+                }
+                const job = state.job === undefined || state.job === null ? undefined : object(state.job, "Sume job");
+                const rejected = sumeJobFailure(status, job, handle.jobId);
+                if (rejected !== undefined)
+                    return { ...failure(rejected), receipt };
+                if (status !== "completed")
+                    throw new EndpointResponseError(`Sume returned unknown job status ${status}`);
+                const result = object((await client.json(`/v1/jobs/${id}/result`, key)).result, "Sume job result");
+                const artifacts = Array.isArray(result.artifacts) ? result.artifacts.map((item, index) => object(item, `Sume artifact ${index + 1}`)) : [];
+                const media = artifacts.filter((item) => item.type === route.result);
+                if (media.length === 0)
+                    throw new EndpointResponseError(`Sume job completed without ${route.result} artifacts`);
+                const urls = media.map((item, index) => httpsUrl(item.url, `Sume ${route.result} artifact ${index + 1}`));
+                return { status: "ready", handle: canonicalize({ ...handle, urls }), receipt };
+            }
+            catch (error) {
+                return retrying(error, context.handle, pollIntervalMs, operationDeadlineAt) ?? failure(error);
+            }
+        },
+        async collect(context) {
+            try {
+                const handle = object(context.handle, "Sume handle");
+                const route = sumeRouteForCapability(context.need.capability);
+                assert(route !== undefined && handle.route === route.key && Array.isArray(handle.urls), "Sume collection route differs");
+                await context.reportProgress?.({ phase: "Receiving generated files" });
+                const blobs = [];
+                for (const url of handle.urls) {
+                    const downloaded = await client.download(url);
+                    blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));
+                }
+                return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.jobId } };
+            }
+            catch (error) {
+                return retrying(error, context.handle, pollIntervalMs) ?? failure(error);
+            }
+        },
+    };
+}
+export function createSumeProvider(options = {}) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? 300_000;
+    const operationTimeoutMs = options.operationTimeoutMs ?? 30 * 60_000;
+    for (const [name, value] of Object.entries({ requestTimeoutMs, operationTimeoutMs })) {
+        assert(Number.isSafeInteger(value) && value > 0, `Sume ${name} must be a positive integer`);
+    }
+    const client = new SumeClient(apiBaseUrl(options.baseUrl ?? "https://api.sume.com"), requestTimeoutMs, options.fetch ?? globalThis.fetch);
+    const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 5_000, operationTimeoutMs, options.publicAssetUrl);
+    return defineEndpoint({
+        instance: options.instance ?? "sume.default", pool: options.pool ?? options.instance ?? "sume.default",
+        pricing: { kind: "page", url: "https://www.sume.com/pricing/api" },
+        credentials: { apiKey: options.apiKey ?? credentialRef("local", "sume.api-key") },
+        credentialInputs: { apiKey: { label: "Sume API key" } },
+        defaultConcurrency: options.defaultConcurrency ?? 2,
+        ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),
+        capabilities: sumeRoutes.map((route) => ({
+            capability: route.capability, returns: route.returns, lifecycle: "asynchronous", endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,
+        })),
+    });
+}

package/dist/routes.d.ts

@@ -0,0 +1,17 @@
+import type { GenerationArtifactUrlResolver, GenerationWireMapping } from "@hypit/generation";
+import type { BlobRef, CanonicalValue, CapabilityRef, StoredValue, TypeRef } from "@hypit/hypit/protocol";
+import type { EndpointRequest, EndpointSupport } from "@hypit/hypit/endpoint";
+export type SumePreparedRequest = {
+    readonly model: string;
+    readonly media: "image" | "video";
+    readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+export type SumeRoute = GenerationWireMapping & {
+    readonly key: string;
+    readonly returns: TypeRef;
+    readonly supports: (request: EndpointRequest) => EndpointSupport;
+    readonly prepare: (constraints: CanonicalValue) => SumePreparedRequest;
+    readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+export declare const sumeRoutes: readonly SumeRoute[];
+export declare function sumeRouteForCapability(capability: CapabilityRef): SumeRoute | undefined;

package/dist/routes.js

@@ -0,0 +1,149 @@
+import { compileWireRequest, generationTypes, sealGeneratedImageSet, sealGeneratedVideoSet, selectWireModelForRequest, } from "@hypit/generation";
+import { canonicalize } from "@hypit/hypit/protocol";
+import { sumeMappings } from "./mapping.js";
+function scalar(request, port) {
+    const value = request.ports[port]?.[0];
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+function count(request, port) {
+    return request.ports[port]?.length ?? 0;
+}
+/** Ratios the model packages offer that the Sume catalog row for the model does not list. */
+const UNLISTED_RATIOS = {
+    "grok-imagine-video-1.5-preview": ["2:3", "3:2"],
+    "pixverse-v6": ["2:3", "3:2", "auto"],
+    "pixverse-c1": ["2:3", "3:2"],
+    "gpt-image-2": ["3:2", "2:3", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"],
+    "seedream-5-lite": ["21:9"],
+};
+/** Sume's per-model input ranges, checked before any reference is uploaded. */
+function rejection(mapping, request) {
+    const { name } = mapping.capability;
+    const model = selectWireModelForRequest(mapping, request);
+    const ratio = scalar(request, "aspectRatio");
+    if (ratio !== undefined && UNLISTED_RATIOS[name]?.includes(String(ratio)) === true) {
+        return `Sume ${model} does not render aspect ratio ${String(ratio)}`;
+    }
+    if (mapping.capability.module.name === "@hypit/seedance") {
+        if (scalar(request, "webSearch") === true)
+            return `Sume ${model} has no web_search field`;
+        if (name === "seedance-2.5" && scalar(request, "duration") === -1) {
+            return "Sume seedance-2.5 takes a duration of 4 to 30 seconds, not automatic";
+        }
+    }
+    if (name === "minimax-h3" && scalar(request, "duration") === 4) {
+        return "Sume minimax-h3 takes a duration of 5 to 15 seconds";
+    }
+    if (name === "grok-imagine-video-1.5-preview") {
+        if (count(request, "images") > 1)
+            return "Sume grok-imagine-video-1.5 takes a prompt alone or one first-frame image";
+        if (ratio === "auto" && count(request, "images") === 0) {
+            return "Sume grok-imagine-video-1.5 needs an explicit aspect ratio without a first frame";
+        }
+    }
+    if (name === "pixverse-v6" || name === "pixverse-c1") {
+        if (count(request, "firstFrame") > 0 || count(request, "lastFrame") > 0) {
+            return `Sume ${model} takes a prompt or reference images, not frames`;
+        }
+        if (count(request, "referenceVideo") > 0)
+            return `Sume ${model} takes no reference videos`;
+        if (scalar(request, "multiClip") === true)
+            return `Sume ${model} has no multi-clip field`;
+        if (scalar(request, "seed") !== undefined)
+            return `Sume ${model} takes no seed`;
+        if (scalar(request, "duration") === 1)
+            return `Sume ${model} takes a duration of 2 to 15 seconds`;
+    }
+    if (name === "gpt-image-2") {
+        if (scalar(request, "background") !== undefined)
+            return "Sume openai/gpt-image-2 has no background field";
+        if (count(request, "images") > 10)
+            return "Sume openai/gpt-image-2 accepts up to ten reference images";
+    }
+    if (name === "nano-banana-2" && count(request, "images") > 10) {
+        return "Sume google/nano-banana-2.1 accepts up to ten reference images";
+    }
+    if (name === "seedream-5-lite") {
+        if (scalar(request, "quality") !== "basic") {
+            return "Sume bytedance-seed/seedream-5-lite renders at 2K only, which is quality basic";
+        }
+        if (scalar(request, "nsfwCheck") === false) {
+            return "Sume bytedance-seed/seedream-5-lite has no switch to turn its content check off";
+        }
+        if (count(request, "images") > 10)
+            return "Sume bytedance-seed/seedream-5-lite accepts up to ten reference images";
+    }
+    return undefined;
+}
+/** Fields the model package states that Sume names differently, spells differently or omits. */
+function normalize(mapping, input) {
+    const { name } = mapping.capability;
+    if (input.web_search === false)
+        delete input.web_search;
+    // MiniMax spells its native tier 768P; Sume's catalog lists 768p.
+    if (name === "minimax-h3" && input.resolution === "768P")
+        input.resolution = "768p";
+    if (name === "grok-imagine-video-1.5-preview") {
+        const images = input.images;
+        delete input.images;
+        // A first frame keeps its own shape, and Sume applies aspect_ratio to text-to-video only.
+        if (images !== undefined && images.length > 0) {
+            input.image_url = images[0];
+            delete input.aspect_ratio;
+        }
+    }
+    if (name === "pixverse-v6" && input.multi_clip === false)
+        delete input.multi_clip;
+    if (mapping.result === "image") {
+        const images = input.images;
+        delete input.images;
+        if (images !== undefined && images.length > 0) {
+            input.input_references = images.map((url) => ({ type: "image_url", image_url: { url } }));
+        }
+    }
+    if (mapping.capability.module.name === "@hypit/nano-banana" && input.output_format === "jpg")
+        input.output_format = "jpeg";
+    if (name === "seedream-5-lite") {
+        delete input.quality;
+        delete input.nsfw_check;
+    }
+    return input;
+}
+function capabilityKey(capability) {
+    return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+export const sumeRoutes = sumeMappings.map((mapping) => ({
+    ...mapping,
+    key: capabilityKey(mapping.capability),
+    returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+    supports: (request) => {
+        const reason = rejection(mapping, request.constraints);
+        return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+    },
+    prepare: (constraints) => {
+        const request = constraints;
+        const reason = rejection(mapping, request);
+        if (reason !== undefined)
+            throw new Error(reason);
+        const model = selectWireModelForRequest(mapping, request);
+        return {
+            model,
+            media: mapping.result === "image" ? "image" : "video",
+            compile: async (resolve) => ({
+                model,
+                ...normalize(mapping, (await compileWireRequest(mapping, request, resolve)).input),
+                mode: "async",
+            }),
+        };
+    },
+    packageResult: (artifacts) => ({
+        kind: "inline",
+        value: canonicalize(mapping.result === "image"
+            ? sealGeneratedImageSet({ images: artifacts })
+            : sealGeneratedVideoSet({ videos: artifacts })),
+    }),
+}));
+const byCapability = new Map(sumeRoutes.map((route) => [route.key, route]));
+export function sumeRouteForCapability(capability) {
+    return byCapability.get(capabilityKey(capability));
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@hypit/provider-sume",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "hypit": {
+    "activation": "./dist/activation.js"
+  },
+  "peerDependencies": {
+    "@hypit/hypit": "^0.3.1",
+    "@hypit/runtime-local": "^0.1.1"
+  },
+  "dependencies": {
+    "@hypit/generation": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hypit-ai/hypit.git"
+  }
+}