hyperclip 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# hyperclip
+
+Official Node SDK for the [Hyperclip](https://hyperclip.co) API. Trigger flow runs, poll for completion, and pull the final video URL — without writing fetch boilerplate.
+
+## Install
+
+```sh
+npm install hyperclip
+```
+
+Requires Node 18+ (uses native `fetch`).
+
+## Quickstart
+
+```ts
+import { Hyperclip } from "hyperclip";
+
+const hc = new Hyperclip({
+  apiKey: process.env.HYPERCLIP_API_KEY,
+  baseUrl: "https://YOUR-PROJECT.supabase.co/functions/v1/api-v1",
+});
+
+const { id } = await hc.runs.create({
+  flow_id: "a3c7f1ea-1234-4abc-bb11-5faed63c7e90",
+  inputs: { prompts: { 0: "a lighthouse at dawn" } },
+  idempotency_key: crypto.randomUUID(),
+});
+
+const run = await hc.runs.wait(id, {
+  onUpdate: (r) => console.log(r.status, r.current_step),
+});
+
+if (run.status === "completed") {
+  console.log("Video:", run.video_url);
+} else {
+  console.error(run.error_code, run.error_message);
+}
+```
+
+## Configuration
+
+| Option | Env var | Required |
+|---|---|---|
+| `apiKey` | `HYPERCLIP_API_KEY` | yes |
+| `baseUrl` | `HYPERCLIP_BASE_URL` | yes |
+| `fetch` | — | no (defaults to global) |
+
+## API
+
+- `hc.runs.create(params)` — `POST /runs`
+- `hc.runs.get(id)` — `GET /runs/:id`
+- `hc.runs.list({ limit?, status? })` — `GET /runs`
+- `hc.runs.cancel(id)` — `POST /runs/:id/cancel`
+- `hc.runs.wait(id, { timeoutMs?, pollIntervalMs?, onUpdate?, signal? })` — polls until terminal
+- `hc.flows.list()` — `GET /flows`
+- `hc.flows.get(id)` — `GET /flows/:id`
+
+Errors throw `HyperclipError` with `.status` and `.code`. Timeouts throw `HyperclipTimeoutError`.

package/dist/index.d.mts

@@ -0,0 +1,149 @@
+type RunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+interface FlowSchemaNode {
+    id: string;
+    type: string;
+    label: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    config: Record<string, unknown>;
+}
+interface FlowSchemaEdge {
+    id: string;
+    source: string;
+    sourceHandle: string;
+    target: string;
+    targetHandle: string;
+}
+interface FlowSchema {
+    version: 1;
+    metadata?: {
+        title?: string;
+        category?: string;
+        description?: string;
+    };
+    nodes: FlowSchemaNode[];
+    edges: FlowSchemaEdge[];
+}
+interface MediaInput {
+    url: string;
+    type: "image" | "video" | "audio";
+}
+interface RunInputs {
+    prompts?: Record<number, string>;
+    media?: Record<number, MediaInput>;
+    model_overrides?: Record<number, Record<string, unknown>>;
+}
+interface CreateRunParams {
+    flow_id?: string;
+    flow_schema?: FlowSchema;
+    inputs?: RunInputs;
+    idempotency_key?: string;
+}
+interface RunRef {
+    id: string;
+    status: RunStatus;
+    created_at: string;
+}
+interface Run {
+    id: string;
+    status: RunStatus;
+    current_step: number | null;
+    video_url: string | null;
+    error_code: string | null;
+    error_message: string | null;
+    credits_charged: number;
+    api_markup_multiplier: string;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+}
+interface RunListItem {
+    id: string;
+    status: RunStatus;
+    current_step: number | null;
+    video_url: string | null;
+    error_code: string | null;
+    credits_charged: number;
+    created_at: string;
+    completed_at: string | null;
+}
+interface FlowListItem {
+    id: string;
+    title: string;
+    description: string | null;
+    updated_at: string;
+}
+interface FlowDetail {
+    id: string;
+    title: string;
+    description: string | null;
+    flow_schema: FlowSchema;
+    required_inputs: Array<{
+        step_order: number;
+        node_type: string;
+        field: "prompt" | "media";
+    }>;
+}
+interface ListRunsParams {
+    limit?: number;
+    status?: RunStatus;
+}
+interface WaitOptions {
+    /** Total wait timeout in milliseconds. Default: 10 minutes. */
+    timeoutMs?: number;
+    /** Initial poll interval in milliseconds. Default: 4000. */
+    pollIntervalMs?: number;
+    /** Called on every poll with the latest run state. */
+    onUpdate?: (run: Run) => void;
+    /** AbortSignal to cancel the wait early. */
+    signal?: AbortSignal;
+}
+
+interface HyperclipOptions {
+    /** API key (`hck_live_<prefix>.<secret>`). Falls back to `HYPERCLIP_API_KEY`. */
+    apiKey?: string;
+    /**
+     * Full base URL — e.g. `https://your-project.supabase.co/functions/v1/api-v1`.
+     * Falls back to `HYPERCLIP_BASE_URL`.
+     */
+    baseUrl?: string;
+    /** Override the global fetch (e.g. for testing). */
+    fetch?: typeof fetch;
+}
+declare class Hyperclip {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: HyperclipOptions);
+    readonly runs: {
+        create: (params: CreateRunParams) => Promise<RunRef>;
+        get: (id: string) => Promise<Run>;
+        list: (params?: ListRunsParams) => Promise<RunListItem[]>;
+        cancel: (id: string) => Promise<{
+            id: string;
+            status: "cancelled";
+        }>;
+        wait: (id: string, options?: WaitOptions) => Promise<Run>;
+    };
+    readonly flows: {
+        list: () => Promise<FlowListItem[]>;
+        get: (id: string) => Promise<FlowDetail>;
+    };
+    private createRun;
+    private listRuns;
+    private waitForRun;
+    private request;
+}
+
+declare class HyperclipError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class HyperclipTimeoutError extends Error {
+    constructor(message?: string);
+}
+
+export { type CreateRunParams, type FlowDetail, type FlowListItem, type FlowSchema, type FlowSchemaEdge, type FlowSchemaNode, Hyperclip, HyperclipError, type HyperclipOptions, HyperclipTimeoutError, type ListRunsParams, type MediaInput, type Run, type RunInputs, type RunListItem, type RunRef, type RunStatus, type WaitOptions };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+type RunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+interface FlowSchemaNode {
+    id: string;
+    type: string;
+    label: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    config: Record<string, unknown>;
+}
+interface FlowSchemaEdge {
+    id: string;
+    source: string;
+    sourceHandle: string;
+    target: string;
+    targetHandle: string;
+}
+interface FlowSchema {
+    version: 1;
+    metadata?: {
+        title?: string;
+        category?: string;
+        description?: string;
+    };
+    nodes: FlowSchemaNode[];
+    edges: FlowSchemaEdge[];
+}
+interface MediaInput {
+    url: string;
+    type: "image" | "video" | "audio";
+}
+interface RunInputs {
+    prompts?: Record<number, string>;
+    media?: Record<number, MediaInput>;
+    model_overrides?: Record<number, Record<string, unknown>>;
+}
+interface CreateRunParams {
+    flow_id?: string;
+    flow_schema?: FlowSchema;
+    inputs?: RunInputs;
+    idempotency_key?: string;
+}
+interface RunRef {
+    id: string;
+    status: RunStatus;
+    created_at: string;
+}
+interface Run {
+    id: string;
+    status: RunStatus;
+    current_step: number | null;
+    video_url: string | null;
+    error_code: string | null;
+    error_message: string | null;
+    credits_charged: number;
+    api_markup_multiplier: string;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+}
+interface RunListItem {
+    id: string;
+    status: RunStatus;
+    current_step: number | null;
+    video_url: string | null;
+    error_code: string | null;
+    credits_charged: number;
+    created_at: string;
+    completed_at: string | null;
+}
+interface FlowListItem {
+    id: string;
+    title: string;
+    description: string | null;
+    updated_at: string;
+}
+interface FlowDetail {
+    id: string;
+    title: string;
+    description: string | null;
+    flow_schema: FlowSchema;
+    required_inputs: Array<{
+        step_order: number;
+        node_type: string;
+        field: "prompt" | "media";
+    }>;
+}
+interface ListRunsParams {
+    limit?: number;
+    status?: RunStatus;
+}
+interface WaitOptions {
+    /** Total wait timeout in milliseconds. Default: 10 minutes. */
+    timeoutMs?: number;
+    /** Initial poll interval in milliseconds. Default: 4000. */
+    pollIntervalMs?: number;
+    /** Called on every poll with the latest run state. */
+    onUpdate?: (run: Run) => void;
+    /** AbortSignal to cancel the wait early. */
+    signal?: AbortSignal;
+}
+
+interface HyperclipOptions {
+    /** API key (`hck_live_<prefix>.<secret>`). Falls back to `HYPERCLIP_API_KEY`. */
+    apiKey?: string;
+    /**
+     * Full base URL — e.g. `https://your-project.supabase.co/functions/v1/api-v1`.
+     * Falls back to `HYPERCLIP_BASE_URL`.
+     */
+    baseUrl?: string;
+    /** Override the global fetch (e.g. for testing). */
+    fetch?: typeof fetch;
+}
+declare class Hyperclip {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: HyperclipOptions);
+    readonly runs: {
+        create: (params: CreateRunParams) => Promise<RunRef>;
+        get: (id: string) => Promise<Run>;
+        list: (params?: ListRunsParams) => Promise<RunListItem[]>;
+        cancel: (id: string) => Promise<{
+            id: string;
+            status: "cancelled";
+        }>;
+        wait: (id: string, options?: WaitOptions) => Promise<Run>;
+    };
+    readonly flows: {
+        list: () => Promise<FlowListItem[]>;
+        get: (id: string) => Promise<FlowDetail>;
+    };
+    private createRun;
+    private listRuns;
+    private waitForRun;
+    private request;
+}
+
+declare class HyperclipError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class HyperclipTimeoutError extends Error {
+    constructor(message?: string);
+}
+
+export { type CreateRunParams, type FlowDetail, type FlowListItem, type FlowSchema, type FlowSchemaEdge, type FlowSchemaNode, Hyperclip, HyperclipError, type HyperclipOptions, HyperclipTimeoutError, type ListRunsParams, type MediaInput, type Run, type RunInputs, type RunListItem, type RunRef, type RunStatus, type WaitOptions };

package/dist/index.js

@@ -0,0 +1,157 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Hyperclip: () => Hyperclip,
+  HyperclipError: () => HyperclipError,
+  HyperclipTimeoutError: () => HyperclipTimeoutError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var HyperclipError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = "HyperclipError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var HyperclipTimeoutError = class extends Error {
+  constructor(message = "Run polling timed out") {
+    super(message);
+    this.name = "HyperclipTimeoutError";
+  }
+};
+
+// src/client.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+var Hyperclip = class {
+  constructor(options = {}) {
+    this.runs = {
+      create: (params) => this.createRun(params),
+      get: (id) => this.request("GET", `/runs/${encodeURIComponent(id)}`),
+      list: (params = {}) => this.listRuns(params),
+      cancel: (id) => this.request("POST", `/runs/${encodeURIComponent(id)}/cancel`),
+      wait: (id, options) => this.waitForRun(id, options)
+    };
+    this.flows = {
+      list: async () => {
+        const res = await this.request("GET", "/flows");
+        return res.flows;
+      },
+      get: (id) => this.request("GET", `/flows/${encodeURIComponent(id)}`)
+    };
+    const apiKey = options.apiKey ?? process.env.HYPERCLIP_API_KEY;
+    const baseUrl = options.baseUrl ?? process.env.HYPERCLIP_BASE_URL;
+    if (!apiKey) {
+      throw new Error(
+        "Hyperclip: missing apiKey. Pass `apiKey` or set HYPERCLIP_API_KEY."
+      );
+    }
+    if (!baseUrl) {
+      throw new Error(
+        "Hyperclip: missing baseUrl. Pass `baseUrl` or set HYPERCLIP_BASE_URL (e.g. https://your-project.supabase.co/functions/v1/api-v1)."
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error("Hyperclip: no fetch implementation available. Use Node 18+ or pass `fetch`.");
+    }
+  }
+  async createRun(params) {
+    const headers = {};
+    if (params.idempotency_key) headers["Idempotency-Key"] = params.idempotency_key;
+    return this.request("POST", "/runs", params, headers);
+  }
+  async listRuns(params) {
+    const qs = new URLSearchParams();
+    if (params.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params.status) qs.set("status", params.status);
+    const path = qs.toString() ? `/runs?${qs}` : "/runs";
+    const res = await this.request("GET", path);
+    return res.runs;
+  }
+  async waitForRun(id, options = {}) {
+    const { timeoutMs = 10 * 6e4, pollIntervalMs = 4e3, onUpdate, signal } = options;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw new HyperclipTimeoutError("Wait aborted");
+      const run = await this.runs.get(id);
+      onUpdate?.(run);
+      if (TERMINAL_STATUSES.has(run.status)) return run;
+      await sleep(pollIntervalMs, signal);
+    }
+    throw new HyperclipTimeoutError();
+  }
+  async request(method, path, body, extraHeaders = {}) {
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...extraHeaders
+    };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    const text = await res.text();
+    const data = text ? safeJson(text) : void 0;
+    if (!res.ok) {
+      const err = data?.error;
+      throw new HyperclipError(
+        res.status,
+        err?.code ?? "unknown_error",
+        err?.message ?? `HTTP ${res.status}`
+      );
+    }
+    return data;
+  }
+};
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new HyperclipTimeoutError("Wait aborted"));
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new HyperclipTimeoutError("Wait aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Hyperclip,
+  HyperclipError,
+  HyperclipTimeoutError
+});

package/dist/index.mjs

@@ -0,0 +1,128 @@
+// src/errors.ts
+var HyperclipError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = "HyperclipError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var HyperclipTimeoutError = class extends Error {
+  constructor(message = "Run polling timed out") {
+    super(message);
+    this.name = "HyperclipTimeoutError";
+  }
+};
+
+// src/client.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+var Hyperclip = class {
+  constructor(options = {}) {
+    this.runs = {
+      create: (params) => this.createRun(params),
+      get: (id) => this.request("GET", `/runs/${encodeURIComponent(id)}`),
+      list: (params = {}) => this.listRuns(params),
+      cancel: (id) => this.request("POST", `/runs/${encodeURIComponent(id)}/cancel`),
+      wait: (id, options) => this.waitForRun(id, options)
+    };
+    this.flows = {
+      list: async () => {
+        const res = await this.request("GET", "/flows");
+        return res.flows;
+      },
+      get: (id) => this.request("GET", `/flows/${encodeURIComponent(id)}`)
+    };
+    const apiKey = options.apiKey ?? process.env.HYPERCLIP_API_KEY;
+    const baseUrl = options.baseUrl ?? process.env.HYPERCLIP_BASE_URL;
+    if (!apiKey) {
+      throw new Error(
+        "Hyperclip: missing apiKey. Pass `apiKey` or set HYPERCLIP_API_KEY."
+      );
+    }
+    if (!baseUrl) {
+      throw new Error(
+        "Hyperclip: missing baseUrl. Pass `baseUrl` or set HYPERCLIP_BASE_URL (e.g. https://your-project.supabase.co/functions/v1/api-v1)."
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error("Hyperclip: no fetch implementation available. Use Node 18+ or pass `fetch`.");
+    }
+  }
+  async createRun(params) {
+    const headers = {};
+    if (params.idempotency_key) headers["Idempotency-Key"] = params.idempotency_key;
+    return this.request("POST", "/runs", params, headers);
+  }
+  async listRuns(params) {
+    const qs = new URLSearchParams();
+    if (params.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params.status) qs.set("status", params.status);
+    const path = qs.toString() ? `/runs?${qs}` : "/runs";
+    const res = await this.request("GET", path);
+    return res.runs;
+  }
+  async waitForRun(id, options = {}) {
+    const { timeoutMs = 10 * 6e4, pollIntervalMs = 4e3, onUpdate, signal } = options;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw new HyperclipTimeoutError("Wait aborted");
+      const run = await this.runs.get(id);
+      onUpdate?.(run);
+      if (TERMINAL_STATUSES.has(run.status)) return run;
+      await sleep(pollIntervalMs, signal);
+    }
+    throw new HyperclipTimeoutError();
+  }
+  async request(method, path, body, extraHeaders = {}) {
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...extraHeaders
+    };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    const text = await res.text();
+    const data = text ? safeJson(text) : void 0;
+    if (!res.ok) {
+      const err = data?.error;
+      throw new HyperclipError(
+        res.status,
+        err?.code ?? "unknown_error",
+        err?.message ?? `HTTP ${res.status}`
+      );
+    }
+    return data;
+  }
+};
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new HyperclipTimeoutError("Wait aborted"));
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new HyperclipTimeoutError("Wait aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+export {
+  Hyperclip,
+  HyperclipError,
+  HyperclipTimeoutError
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "hyperclip",
+  "version": "0.1.0",
+  "description": "Official Node SDK for the Hyperclip API — create, poll, and manage flow runs.",
+  "license": "MIT",
+  "homepage": "https://hyperclip.co",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyperclip/hyperclip-sdks.git",
+    "directory": "node"
+  },
+  "bugs": "https://github.com/hyperclip/hyperclip-sdks/issues",
+  "keywords": [
+    "hyperclip",
+    "video",
+    "ai-video",
+    "sdk",
+    "api"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}