@fotovid/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fotovid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @fotovid/sdk
+
+Thin, typed TypeScript/Node client for the [Fotovid](https://fotovid.co) media API. POST a URL, await the finished file — no ffmpeg binary in your bundle.
+
+## Install
+
+```bash
+npm install @fotovid/sdk
+```
+
+## Usage
+
+```ts
+import Fotovid from "@fotovid/sdk";
+
+const fotovid = new Fotovid({ apiKey: process.env.FOTOVID_API_KEY });
+
+const res = await fotovid.video.watermark({
+	source_url: "https://cdn.example.com/clip.mp4",
+	watermark_type: "image",
+	watermark_image_url: "https://cdn.example.com/logo.png",
+	position: "bottom-right",
+	opacity: 0.8,
+});
+
+console.log(res.url); // URL to the finished file — hosted, time-limited, opaque; see expires_at, store your own copy
+```
+
+## Operations
+
+| Method | Endpoint |
+| --- | --- |
+| `fotovid.video.watermark(input)` | `POST /v1/video/watermark` |
+| `fotovid.image.watermark(input)` | `POST /v1/image/watermark` |
+| `fotovid.video.trim(input)` | `POST /v1/video/trim` |
+| `fotovid.video.extractAudio(input)` | `POST /v1/video/extract-audio` |
+| `fotovid.audio.trim(input)` | `POST /v1/audio/trim` |
+| `fotovid.video.thumbnail(input)` | `POST /v1/video/extract-cover` |
+| `fotovid.video.probe(input)` | `POST /v1/video/probe` |
+
+Parameter names match the API 1:1 (`source_url`, `watermark_image_url`, …). Every
+media operation returns `{ id, type, url, expires_at, duration? }`; `probe`
+returns video metadata.
+
+## Config
+
+```ts
+new Fotovid({
+	apiKey: "p6_<key_id>:<secret>", // or set FOTOVID_API_KEY
+	baseUrl: "https://api.fotovid.co", // optional
+	fetch: customFetch, // optional, defaults to global fetch (Node 18+)
+});
+```
+
+## Idempotency
+
+Every operation is billed, so the API requires an `Idempotency-Key` header. The
+SDK sends a fresh key per call automatically — you don't have to do anything. To
+safely retry a request without being charged twice, pass the same key both times:
+
+```ts
+const idempotencyKey = crypto.randomUUID();
+const opts = { idempotencyKey };
+
+await fotovid.video.watermark(input, opts);
+// A retry with the same key replays the original result instead of re-charging.
+await fotovid.video.watermark(input, opts);
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,121 @@
+"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, {
+  Fotovid: () => Fotovid,
+  FotovidError: () => FotovidError,
+  default: () => Fotovid
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/error.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+var FotovidError = class extends Error {
+  /** HTTP status code of the failed response. */
+  status;
+  /** Parsed error body, when the response carried one. */
+  detail;
+  /** Seconds to wait before retrying, from the `Retry-After` header (e.g. 429/503). */
+  retryAfter;
+  constructor(status, detail, retryAfter) {
+    let message;
+    if (isRecord(detail)) {
+      if (typeof detail.detail === "string") {
+        message = detail.detail;
+      } else if (typeof detail.message === "string") {
+        message = detail.message;
+      }
+    }
+    super(message ?? `Fotovid API request failed with status ${status}`);
+    this.name = "FotovidError";
+    this.status = status;
+    this.detail = detail;
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.fotovid.co";
+function resolveApiKey(explicit) {
+  const key = explicit ?? (typeof process !== "undefined" ? process.env?.FOTOVID_API_KEY : void 0);
+  if (!key) {
+    throw new Error(
+      "Fotovid: missing API key. Pass { apiKey } or set FOTOVID_API_KEY."
+    );
+  }
+  return key;
+}
+var Fotovid = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  constructor(options = {}) {
+    this.#apiKey = resolveApiKey(options.apiKey);
+    this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+  }
+  async #post(path, input, options) {
+    const { source_url, ...params } = input;
+    const response = await this.#fetch(new URL(path, this.#baseUrl), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.#apiKey}`,
+        // Billed endpoints require an idempotency key; default to a fresh
+        // UUID per call, overridable to make a retry replay (not re-charge).
+        "idempotency-key": options?.idempotencyKey ?? globalThis.crypto.randomUUID()
+      },
+      body: JSON.stringify({ source_url, params })
+    });
+    if (!response.ok) {
+      let detail;
+      try {
+        detail = await response.json();
+      } catch {
+      }
+      const ra = response.headers.get("retry-after");
+      const retryAfter = ra ? Number(ra) : void 0;
+      throw new FotovidError(response.status, detail, retryAfter);
+    }
+    return await response.json();
+  }
+  video = {
+    watermark: (input, options) => this.#post("/v1/video/watermark", input, options),
+    trim: (input, options) => this.#post("/v1/video/trim", input, options),
+    extractAudio: (input, options) => this.#post("/v1/video/extract-audio", input, options),
+    thumbnail: (input, options) => this.#post("/v1/video/extract-cover", input, options),
+    probe: (input, options) => this.#post("/v1/video/probe", input, options)
+  };
+  image = {
+    watermark: (input, options) => this.#post("/v1/image/watermark", input, options)
+  };
+  audio = {
+    trim: (input, options) => this.#post("/v1/audio/trim", input, options)
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Fotovid,
+  FotovidError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/error.ts","../src/client.ts"],"sourcesContent":["export { Fotovid, Fotovid as default } from \"./client.js\";\nexport { FotovidError } from \"./error.js\";\nexport type {\n\tExtractAudioInput,\n\tFotovidOptions,\n\tImageFormat,\n\tImageWatermarkInput,\n\tMediaResult,\n\tProbeInput,\n\tProbeResult,\n\tRequestOptions,\n\tThumbnailInput,\n\tTrimAudioInput,\n\tTrimInput,\n\tVideoWatermarkInput,\n\tWatermarkPosition,\n\tWatermarkType,\n\tX264Preset,\n} from \"./types.js\";\n","function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\n/** Thrown when the Fotovid API returns a non-2xx response. */\nexport class FotovidError extends Error {\n\t/** HTTP status code of the failed response. */\n\treadonly status: number;\n\t/** Parsed error body, when the response carried one. */\n\treadonly detail: unknown;\n\t/** Seconds to wait before retrying, from the `Retry-After` header (e.g. 429/503). */\n\treadonly retryAfter?: number;\n\n\tconstructor(status: number, detail: unknown, retryAfter?: number) {\n\t\tlet message: string | undefined;\n\t\tif (isRecord(detail)) {\n\t\t\tif (typeof detail.detail === \"string\") {\n\t\t\t\tmessage = detail.detail;\n\t\t\t} else if (typeof detail.message === \"string\") {\n\t\t\t\tmessage = detail.message;\n\t\t\t}\n\t\t}\n\t\tsuper(message ?? `Fotovid API request failed with status ${status}`);\n\t\tthis.name = \"FotovidError\";\n\t\tthis.status = status;\n\t\tthis.detail = detail;\n\t\tthis.retryAfter = retryAfter;\n\t}\n}\n","import { FotovidError } from \"./error.js\";\nimport type {\n\tExtractAudioInput,\n\tFotovidOptions,\n\tImageWatermarkInput,\n\tMediaResult,\n\tProbeInput,\n\tProbeResult,\n\tRequestOptions,\n\tThumbnailInput,\n\tTrimAudioInput,\n\tTrimInput,\n\tVideoWatermarkInput,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.fotovid.co\";\n\nfunction resolveApiKey(explicit: string | undefined): string {\n\tconst key =\n\t\texplicit ??\n\t\t(typeof process !== \"undefined\" ? process.env?.FOTOVID_API_KEY : undefined);\n\tif (!key) {\n\t\tthrow new Error(\n\t\t\t\"Fotovid: missing API key. Pass { apiKey } or set FOTOVID_API_KEY.\",\n\t\t);\n\t}\n\treturn key;\n}\n\n/**\n * Typed client for the Fotovid media API. Methods mirror the REST resources\n * (`client.video.*`, `client.image.*`, `client.audio.*`); parameter names\n * match the API 1:1 (`source_url`, `watermark_image_url`, …).\n */\nexport class Fotovid {\n\treadonly #apiKey: string;\n\treadonly #baseUrl: string;\n\treadonly #fetch: typeof globalThis.fetch;\n\n\tconstructor(options: FotovidOptions = {}) {\n\t\tthis.#apiKey = resolveApiKey(options.apiKey);\n\t\tthis.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;\n\t\tthis.#fetch = options.fetch ?? globalThis.fetch;\n\t}\n\n\tasync #post<T>(\n\t\tpath: string,\n\t\tinput: { source_url: string },\n\t\toptions?: RequestOptions,\n\t): Promise<T> {\n\t\tconst { source_url, ...params } = input;\n\t\tconst response = await this.#fetch(new URL(path, this.#baseUrl), {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: {\n\t\t\t\t\"content-type\": \"application/json\",\n\t\t\t\tauthorization: `Bearer ${this.#apiKey}`,\n\t\t\t\t// Billed endpoints require an idempotency key; default to a fresh\n\t\t\t\t// UUID per call, overridable to make a retry replay (not re-charge).\n\t\t\t\t\"idempotency-key\":\n\t\t\t\t\toptions?.idempotencyKey ?? globalThis.crypto.randomUUID(),\n\t\t\t},\n\t\t\tbody: JSON.stringify({ source_url, params }),\n\t\t});\n\t\tif (!response.ok) {\n\t\t\tlet detail: unknown;\n\t\t\ttry {\n\t\t\t\tdetail = await response.json();\n\t\t\t} catch {\n\t\t\t\t// non-JSON error body — leave detail undefined\n\t\t\t}\n\t\t\tconst ra = response.headers.get(\"retry-after\");\n\t\t\tconst retryAfter = ra ? Number(ra) : undefined;\n\t\t\tthrow new FotovidError(response.status, detail, retryAfter);\n\t\t}\n\t\treturn (await response.json()) as T;\n\t}\n\n\treadonly video = {\n\t\twatermark: (\n\t\t\tinput: VideoWatermarkInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/watermark\", input, options),\n\t\ttrim: (input: TrimInput, options?: RequestOptions): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/trim\", input, options),\n\t\textractAudio: (\n\t\t\tinput: ExtractAudioInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/extract-audio\", input, options),\n\t\tthumbnail: (\n\t\t\tinput: ThumbnailInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/extract-cover\", input, options),\n\t\tprobe: (\n\t\t\tinput: ProbeInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<ProbeResult> =>\n\t\t\tthis.#post<ProbeResult>(\"/v1/video/probe\", input, options),\n\t};\n\n\treadonly image = {\n\t\twatermark: (\n\t\t\tinput: ImageWatermarkInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/image/watermark\", input, options),\n\t};\n\n\treadonly audio = {\n\t\ttrim: (\n\t\t\tinput: TrimAudioInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/audio/trim\", input, options),\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,SAAS,SAAS,OAAkD;AACnE,SAAO,OAAO,UAAU,YAAY,UAAU;AAC/C;AAGO,IAAM,eAAN,cAA2B,MAAM;AAAA;AAAA,EAE9B;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA,EAET,YAAY,QAAgB,QAAiB,YAAqB;AACjE,QAAI;AACJ,QAAI,SAAS,MAAM,GAAG;AACrB,UAAI,OAAO,OAAO,WAAW,UAAU;AACtC,kBAAU,OAAO;AAAA,MAClB,WAAW,OAAO,OAAO,YAAY,UAAU;AAC9C,kBAAU,OAAO;AAAA,MAClB;AAAA,IACD;AACA,UAAM,WAAW,0CAA0C,MAAM,EAAE;AACnE,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,SAAS;AACd,SAAK,aAAa;AAAA,EACnB;AACD;;;ACbA,IAAM,mBAAmB;AAEzB,SAAS,cAAc,UAAsC;AAC5D,QAAM,MACL,aACC,OAAO,YAAY,cAAc,QAAQ,KAAK,kBAAkB;AAClE,MAAI,CAAC,KAAK;AACT,UAAM,IAAI;AAAA,MACT;AAAA,IACD;AAAA,EACD;AACA,SAAO;AACR;AAOO,IAAM,UAAN,MAAc;AAAA,EACX;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,UAA0B,CAAC,GAAG;AACzC,SAAK,UAAU,cAAc,QAAQ,MAAM;AAC3C,SAAK,WAAW,QAAQ,WAAW;AACnC,SAAK,SAAS,QAAQ,SAAS,WAAW;AAAA,EAC3C;AAAA,EAEA,MAAM,MACL,MACA,OACA,SACa;AACb,UAAM,EAAE,YAAY,GAAG,OAAO,IAAI;AAClC,UAAM,WAAW,MAAM,KAAK,OAAO,IAAI,IAAI,MAAM,KAAK,QAAQ,GAAG;AAAA,MAChE,QAAQ;AAAA,MACR,SAAS;AAAA,QACR,gBAAgB;AAAA,QAChB,eAAe,UAAU,KAAK,OAAO;AAAA;AAAA;AAAA,QAGrC,mBACC,SAAS,kBAAkB,WAAW,OAAO,WAAW;AAAA,MAC1D;AAAA,MACA,MAAM,KAAK,UAAU,EAAE,YAAY,OAAO,CAAC;AAAA,IAC5C,CAAC;AACD,QAAI,CAAC,SAAS,IAAI;AACjB,UAAI;AACJ,UAAI;AACH,iBAAS,MAAM,SAAS,KAAK;AAAA,MAC9B,QAAQ;AAAA,MAER;AACA,YAAM,KAAK,SAAS,QAAQ,IAAI,aAAa;AAC7C,YAAM,aAAa,KAAK,OAAO,EAAE,IAAI;AACrC,YAAM,IAAI,aAAa,SAAS,QAAQ,QAAQ,UAAU;AAAA,IAC3D;AACA,WAAQ,MAAM,SAAS,KAAK;AAAA,EAC7B;AAAA,EAES,QAAQ;AAAA,IAChB,WAAW,CACV,OACA,YAEA,KAAK,MAAmB,uBAAuB,OAAO,OAAO;AAAA,IAC9D,MAAM,CAAC,OAAkB,YACxB,KAAK,MAAmB,kBAAkB,OAAO,OAAO;AAAA,IACzD,cAAc,CACb,OACA,YAEA,KAAK,MAAmB,2BAA2B,OAAO,OAAO;AAAA,IAClE,WAAW,CACV,OACA,YAEA,KAAK,MAAmB,2BAA2B,OAAO,OAAO;AAAA,IAClE,OAAO,CACN,OACA,YAEA,KAAK,MAAmB,mBAAmB,OAAO,OAAO;AAAA,EAC3D;AAAA,EAES,QAAQ;AAAA,IAChB,WAAW,CACV,OACA,YAEA,KAAK,MAAmB,uBAAuB,OAAO,OAAO;AAAA,EAC/D;AAAA,EAES,QAAQ;AAAA,IAChB,MAAM,CACL,OACA,YAEA,KAAK,MAAmB,kBAAkB,OAAO,OAAO;AAAA,EAC1D;AACD;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,137 @@
+/** Anchor position for a watermark overlay. */
+type WatermarkPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center";
+/** Output image format for image-producing operations. */
+type ImageFormat = "webp" | "jpeg" | "jpg" | "png";
+/** Watermark variant. */
+type WatermarkType = "text" | "image" | "combo";
+/** x264 encode preset (video watermark only). */
+type X264Preset = "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" | "medium" | "slow" | "slower" | "veryslow" | "placebo";
+/** Every request carries the source media URL. */
+interface SourceInput {
+    /** Public http(s) URL of the source media. */
+    source_url: string;
+}
+interface VideoWatermarkInput extends SourceInput {
+    watermark_type?: WatermarkType;
+    /** Overlay text, ≤1000 chars (required for text/combo). */
+    text?: string;
+    /** Text size in px, 8–200 (text/combo). */
+    font_size?: number;
+    /** Text color: a name (letters only) or #RRGGBB[AA] (text/combo). */
+    font_color?: string;
+    /** Logo image URL (required for image/combo). */
+    watermark_image_url?: string;
+    /** Logo width as a fraction of source width, >0–1 (image/combo). */
+    scale?: number;
+    /** Watermark opacity, >0–1. */
+    opacity?: number;
+    position?: WatermarkPosition;
+    /** Edge padding in px, 0–500. */
+    padding?: number;
+    output_format?: ImageFormat;
+    /** Lossy quality 1–100 (png ignores it). */
+    quality?: number;
+    /** x264 encode preset — video only. */
+    preset?: X264Preset;
+}
+type ImageWatermarkInput = Omit<VideoWatermarkInput, "preset">;
+interface TrimInput extends SourceInput {
+    /** Window start in seconds (inclusive). Required by the API. */
+    start: number;
+    /** Window end in seconds (exclusive); must be greater than start. Required by the API. */
+    end: number;
+}
+type ExtractAudioInput = SourceInput;
+interface TrimAudioInput extends SourceInput {
+    /** Window start in seconds (inclusive). Required by the API. */
+    start: number;
+    /** Window end in seconds (exclusive); must be greater than start. Required by the API. */
+    end: number;
+}
+interface ThumbnailInput extends SourceInput {
+    /** Frame timestamp in seconds (default ~1s). */
+    at?: number;
+    output_format?: ImageFormat;
+    /** Lossy quality 1–100 (png ignores it). */
+    quality?: number;
+}
+type ProbeInput = SourceInput;
+/** Result of a media-producing operation. */
+interface MediaResult {
+    /** Result record id (echoed on idempotent replay). */
+    id: string;
+    /** Task type that produced this result. */
+    type: string;
+    /** Download URL — hosted, time-limited, opaque; don't parse it, see `expires_at`. Store your own copy. */
+    url: string;
+    /** RFC 3339 time the download URL expires. */
+    expires_at: string;
+    /** Result media duration in seconds, when known. */
+    duration?: number;
+}
+/** Result of a probe — metadata only, no artifact. */
+interface ProbeResult {
+    id: string;
+    type: string;
+    width: number;
+    height: number;
+    durationSec: number;
+    /** Frame rate as ffprobe reports r_frame_rate (e.g. "30/1"). */
+    fps: string;
+    /** First video stream codec (e.g. "h264"). */
+    codec: string;
+    hasAlpha: boolean;
+}
+interface FotovidOptions {
+    /** API key `p6_<key_id>:<secret>`. Falls back to `FOTOVID_API_KEY`. */
+    apiKey?: string;
+    /** API base URL. Defaults to https://api.fotovid.co */
+    baseUrl?: string;
+    /** Custom fetch implementation (defaults to the global fetch). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Per-request options. */
+interface RequestOptions {
+    /**
+     * Idempotency key (1–255 printable ASCII). Defaults to a fresh UUID per
+     * call. Reuse the same key with the same body to safely retry a billed
+     * request — the API replays the original result instead of charging again.
+     */
+    idempotencyKey?: string;
+}
+
+/**
+ * Typed client for the Fotovid media API. Methods mirror the REST resources
+ * (`client.video.*`, `client.image.*`, `client.audio.*`); parameter names
+ * match the API 1:1 (`source_url`, `watermark_image_url`, …).
+ */
+declare class Fotovid {
+    #private;
+    constructor(options?: FotovidOptions);
+    readonly video: {
+        watermark: (input: VideoWatermarkInput, options?: RequestOptions) => Promise<MediaResult>;
+        trim: (input: TrimInput, options?: RequestOptions) => Promise<MediaResult>;
+        extractAudio: (input: ExtractAudioInput, options?: RequestOptions) => Promise<MediaResult>;
+        thumbnail: (input: ThumbnailInput, options?: RequestOptions) => Promise<MediaResult>;
+        probe: (input: ProbeInput, options?: RequestOptions) => Promise<ProbeResult>;
+    };
+    readonly image: {
+        watermark: (input: ImageWatermarkInput, options?: RequestOptions) => Promise<MediaResult>;
+    };
+    readonly audio: {
+        trim: (input: TrimAudioInput, options?: RequestOptions) => Promise<MediaResult>;
+    };
+}
+
+/** Thrown when the Fotovid API returns a non-2xx response. */
+declare class FotovidError extends Error {
+    /** HTTP status code of the failed response. */
+    readonly status: number;
+    /** Parsed error body, when the response carried one. */
+    readonly detail: unknown;
+    /** Seconds to wait before retrying, from the `Retry-After` header (e.g. 429/503). */
+    readonly retryAfter?: number;
+    constructor(status: number, detail: unknown, retryAfter?: number);
+}
+
+export { type ExtractAudioInput, Fotovid, FotovidError, type FotovidOptions, type ImageFormat, type ImageWatermarkInput, type MediaResult, type ProbeInput, type ProbeResult, type RequestOptions, type ThumbnailInput, type TrimAudioInput, type TrimInput, type VideoWatermarkInput, type WatermarkPosition, type WatermarkType, type X264Preset, Fotovid as default };

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+/** Anchor position for a watermark overlay. */
+type WatermarkPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center";
+/** Output image format for image-producing operations. */
+type ImageFormat = "webp" | "jpeg" | "jpg" | "png";
+/** Watermark variant. */
+type WatermarkType = "text" | "image" | "combo";
+/** x264 encode preset (video watermark only). */
+type X264Preset = "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" | "medium" | "slow" | "slower" | "veryslow" | "placebo";
+/** Every request carries the source media URL. */
+interface SourceInput {
+    /** Public http(s) URL of the source media. */
+    source_url: string;
+}
+interface VideoWatermarkInput extends SourceInput {
+    watermark_type?: WatermarkType;
+    /** Overlay text, ≤1000 chars (required for text/combo). */
+    text?: string;
+    /** Text size in px, 8–200 (text/combo). */
+    font_size?: number;
+    /** Text color: a name (letters only) or #RRGGBB[AA] (text/combo). */
+    font_color?: string;
+    /** Logo image URL (required for image/combo). */
+    watermark_image_url?: string;
+    /** Logo width as a fraction of source width, >0–1 (image/combo). */
+    scale?: number;
+    /** Watermark opacity, >0–1. */
+    opacity?: number;
+    position?: WatermarkPosition;
+    /** Edge padding in px, 0–500. */
+    padding?: number;
+    output_format?: ImageFormat;
+    /** Lossy quality 1–100 (png ignores it). */
+    quality?: number;
+    /** x264 encode preset — video only. */
+    preset?: X264Preset;
+}
+type ImageWatermarkInput = Omit<VideoWatermarkInput, "preset">;
+interface TrimInput extends SourceInput {
+    /** Window start in seconds (inclusive). Required by the API. */
+    start: number;
+    /** Window end in seconds (exclusive); must be greater than start. Required by the API. */
+    end: number;
+}
+type ExtractAudioInput = SourceInput;
+interface TrimAudioInput extends SourceInput {
+    /** Window start in seconds (inclusive). Required by the API. */
+    start: number;
+    /** Window end in seconds (exclusive); must be greater than start. Required by the API. */
+    end: number;
+}
+interface ThumbnailInput extends SourceInput {
+    /** Frame timestamp in seconds (default ~1s). */
+    at?: number;
+    output_format?: ImageFormat;
+    /** Lossy quality 1–100 (png ignores it). */
+    quality?: number;
+}
+type ProbeInput = SourceInput;
+/** Result of a media-producing operation. */
+interface MediaResult {
+    /** Result record id (echoed on idempotent replay). */
+    id: string;
+    /** Task type that produced this result. */
+    type: string;
+    /** Download URL — hosted, time-limited, opaque; don't parse it, see `expires_at`. Store your own copy. */
+    url: string;
+    /** RFC 3339 time the download URL expires. */
+    expires_at: string;
+    /** Result media duration in seconds, when known. */
+    duration?: number;
+}
+/** Result of a probe — metadata only, no artifact. */
+interface ProbeResult {
+    id: string;
+    type: string;
+    width: number;
+    height: number;
+    durationSec: number;
+    /** Frame rate as ffprobe reports r_frame_rate (e.g. "30/1"). */
+    fps: string;
+    /** First video stream codec (e.g. "h264"). */
+    codec: string;
+    hasAlpha: boolean;
+}
+interface FotovidOptions {
+    /** API key `p6_<key_id>:<secret>`. Falls back to `FOTOVID_API_KEY`. */
+    apiKey?: string;
+    /** API base URL. Defaults to https://api.fotovid.co */
+    baseUrl?: string;
+    /** Custom fetch implementation (defaults to the global fetch). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Per-request options. */
+interface RequestOptions {
+    /**
+     * Idempotency key (1–255 printable ASCII). Defaults to a fresh UUID per
+     * call. Reuse the same key with the same body to safely retry a billed
+     * request — the API replays the original result instead of charging again.
+     */
+    idempotencyKey?: string;
+}
+
+/**
+ * Typed client for the Fotovid media API. Methods mirror the REST resources
+ * (`client.video.*`, `client.image.*`, `client.audio.*`); parameter names
+ * match the API 1:1 (`source_url`, `watermark_image_url`, …).
+ */
+declare class Fotovid {
+    #private;
+    constructor(options?: FotovidOptions);
+    readonly video: {
+        watermark: (input: VideoWatermarkInput, options?: RequestOptions) => Promise<MediaResult>;
+        trim: (input: TrimInput, options?: RequestOptions) => Promise<MediaResult>;
+        extractAudio: (input: ExtractAudioInput, options?: RequestOptions) => Promise<MediaResult>;
+        thumbnail: (input: ThumbnailInput, options?: RequestOptions) => Promise<MediaResult>;
+        probe: (input: ProbeInput, options?: RequestOptions) => Promise<ProbeResult>;
+    };
+    readonly image: {
+        watermark: (input: ImageWatermarkInput, options?: RequestOptions) => Promise<MediaResult>;
+    };
+    readonly audio: {
+        trim: (input: TrimAudioInput, options?: RequestOptions) => Promise<MediaResult>;
+    };
+}
+
+/** Thrown when the Fotovid API returns a non-2xx response. */
+declare class FotovidError extends Error {
+    /** HTTP status code of the failed response. */
+    readonly status: number;
+    /** Parsed error body, when the response carried one. */
+    readonly detail: unknown;
+    /** Seconds to wait before retrying, from the `Retry-After` header (e.g. 429/503). */
+    readonly retryAfter?: number;
+    constructor(status: number, detail: unknown, retryAfter?: number);
+}
+
+export { type ExtractAudioInput, Fotovid, FotovidError, type FotovidOptions, type ImageFormat, type ImageWatermarkInput, type MediaResult, type ProbeInput, type ProbeResult, type RequestOptions, type ThumbnailInput, type TrimAudioInput, type TrimInput, type VideoWatermarkInput, type WatermarkPosition, type WatermarkType, type X264Preset, Fotovid as default };

package/dist/index.js

@@ -0,0 +1,93 @@
+// src/error.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+var FotovidError = class extends Error {
+  /** HTTP status code of the failed response. */
+  status;
+  /** Parsed error body, when the response carried one. */
+  detail;
+  /** Seconds to wait before retrying, from the `Retry-After` header (e.g. 429/503). */
+  retryAfter;
+  constructor(status, detail, retryAfter) {
+    let message;
+    if (isRecord(detail)) {
+      if (typeof detail.detail === "string") {
+        message = detail.detail;
+      } else if (typeof detail.message === "string") {
+        message = detail.message;
+      }
+    }
+    super(message ?? `Fotovid API request failed with status ${status}`);
+    this.name = "FotovidError";
+    this.status = status;
+    this.detail = detail;
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.fotovid.co";
+function resolveApiKey(explicit) {
+  const key = explicit ?? (typeof process !== "undefined" ? process.env?.FOTOVID_API_KEY : void 0);
+  if (!key) {
+    throw new Error(
+      "Fotovid: missing API key. Pass { apiKey } or set FOTOVID_API_KEY."
+    );
+  }
+  return key;
+}
+var Fotovid = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  constructor(options = {}) {
+    this.#apiKey = resolveApiKey(options.apiKey);
+    this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+  }
+  async #post(path, input, options) {
+    const { source_url, ...params } = input;
+    const response = await this.#fetch(new URL(path, this.#baseUrl), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.#apiKey}`,
+        // Billed endpoints require an idempotency key; default to a fresh
+        // UUID per call, overridable to make a retry replay (not re-charge).
+        "idempotency-key": options?.idempotencyKey ?? globalThis.crypto.randomUUID()
+      },
+      body: JSON.stringify({ source_url, params })
+    });
+    if (!response.ok) {
+      let detail;
+      try {
+        detail = await response.json();
+      } catch {
+      }
+      const ra = response.headers.get("retry-after");
+      const retryAfter = ra ? Number(ra) : void 0;
+      throw new FotovidError(response.status, detail, retryAfter);
+    }
+    return await response.json();
+  }
+  video = {
+    watermark: (input, options) => this.#post("/v1/video/watermark", input, options),
+    trim: (input, options) => this.#post("/v1/video/trim", input, options),
+    extractAudio: (input, options) => this.#post("/v1/video/extract-audio", input, options),
+    thumbnail: (input, options) => this.#post("/v1/video/extract-cover", input, options),
+    probe: (input, options) => this.#post("/v1/video/probe", input, options)
+  };
+  image = {
+    watermark: (input, options) => this.#post("/v1/image/watermark", input, options)
+  };
+  audio = {
+    trim: (input, options) => this.#post("/v1/audio/trim", input, options)
+  };
+};
+export {
+  Fotovid,
+  FotovidError,
+  Fotovid as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/error.ts","../src/client.ts"],"sourcesContent":["function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\n/** Thrown when the Fotovid API returns a non-2xx response. */\nexport class FotovidError extends Error {\n\t/** HTTP status code of the failed response. */\n\treadonly status: number;\n\t/** Parsed error body, when the response carried one. */\n\treadonly detail: unknown;\n\t/** Seconds to wait before retrying, from the `Retry-After` header (e.g. 429/503). */\n\treadonly retryAfter?: number;\n\n\tconstructor(status: number, detail: unknown, retryAfter?: number) {\n\t\tlet message: string | undefined;\n\t\tif (isRecord(detail)) {\n\t\t\tif (typeof detail.detail === \"string\") {\n\t\t\t\tmessage = detail.detail;\n\t\t\t} else if (typeof detail.message === \"string\") {\n\t\t\t\tmessage = detail.message;\n\t\t\t}\n\t\t}\n\t\tsuper(message ?? `Fotovid API request failed with status ${status}`);\n\t\tthis.name = \"FotovidError\";\n\t\tthis.status = status;\n\t\tthis.detail = detail;\n\t\tthis.retryAfter = retryAfter;\n\t}\n}\n","import { FotovidError } from \"./error.js\";\nimport type {\n\tExtractAudioInput,\n\tFotovidOptions,\n\tImageWatermarkInput,\n\tMediaResult,\n\tProbeInput,\n\tProbeResult,\n\tRequestOptions,\n\tThumbnailInput,\n\tTrimAudioInput,\n\tTrimInput,\n\tVideoWatermarkInput,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.fotovid.co\";\n\nfunction resolveApiKey(explicit: string | undefined): string {\n\tconst key =\n\t\texplicit ??\n\t\t(typeof process !== \"undefined\" ? process.env?.FOTOVID_API_KEY : undefined);\n\tif (!key) {\n\t\tthrow new Error(\n\t\t\t\"Fotovid: missing API key. Pass { apiKey } or set FOTOVID_API_KEY.\",\n\t\t);\n\t}\n\treturn key;\n}\n\n/**\n * Typed client for the Fotovid media API. Methods mirror the REST resources\n * (`client.video.*`, `client.image.*`, `client.audio.*`); parameter names\n * match the API 1:1 (`source_url`, `watermark_image_url`, …).\n */\nexport class Fotovid {\n\treadonly #apiKey: string;\n\treadonly #baseUrl: string;\n\treadonly #fetch: typeof globalThis.fetch;\n\n\tconstructor(options: FotovidOptions = {}) {\n\t\tthis.#apiKey = resolveApiKey(options.apiKey);\n\t\tthis.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;\n\t\tthis.#fetch = options.fetch ?? globalThis.fetch;\n\t}\n\n\tasync #post<T>(\n\t\tpath: string,\n\t\tinput: { source_url: string },\n\t\toptions?: RequestOptions,\n\t): Promise<T> {\n\t\tconst { source_url, ...params } = input;\n\t\tconst response = await this.#fetch(new URL(path, this.#baseUrl), {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: {\n\t\t\t\t\"content-type\": \"application/json\",\n\t\t\t\tauthorization: `Bearer ${this.#apiKey}`,\n\t\t\t\t// Billed endpoints require an idempotency key; default to a fresh\n\t\t\t\t// UUID per call, overridable to make a retry replay (not re-charge).\n\t\t\t\t\"idempotency-key\":\n\t\t\t\t\toptions?.idempotencyKey ?? globalThis.crypto.randomUUID(),\n\t\t\t},\n\t\t\tbody: JSON.stringify({ source_url, params }),\n\t\t});\n\t\tif (!response.ok) {\n\t\t\tlet detail: unknown;\n\t\t\ttry {\n\t\t\t\tdetail = await response.json();\n\t\t\t} catch {\n\t\t\t\t// non-JSON error body — leave detail undefined\n\t\t\t}\n\t\t\tconst ra = response.headers.get(\"retry-after\");\n\t\t\tconst retryAfter = ra ? Number(ra) : undefined;\n\t\t\tthrow new FotovidError(response.status, detail, retryAfter);\n\t\t}\n\t\treturn (await response.json()) as T;\n\t}\n\n\treadonly video = {\n\t\twatermark: (\n\t\t\tinput: VideoWatermarkInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/watermark\", input, options),\n\t\ttrim: (input: TrimInput, options?: RequestOptions): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/trim\", input, options),\n\t\textractAudio: (\n\t\t\tinput: ExtractAudioInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/extract-audio\", input, options),\n\t\tthumbnail: (\n\t\t\tinput: ThumbnailInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/video/extract-cover\", input, options),\n\t\tprobe: (\n\t\t\tinput: ProbeInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<ProbeResult> =>\n\t\t\tthis.#post<ProbeResult>(\"/v1/video/probe\", input, options),\n\t};\n\n\treadonly image = {\n\t\twatermark: (\n\t\t\tinput: ImageWatermarkInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/image/watermark\", input, options),\n\t};\n\n\treadonly audio = {\n\t\ttrim: (\n\t\t\tinput: TrimAudioInput,\n\t\t\toptions?: RequestOptions,\n\t\t): Promise<MediaResult> =>\n\t\t\tthis.#post<MediaResult>(\"/v1/audio/trim\", input, options),\n\t};\n}\n"],"mappings":";AAAA,SAAS,SAAS,OAAkD;AACnE,SAAO,OAAO,UAAU,YAAY,UAAU;AAC/C;AAGO,IAAM,eAAN,cAA2B,MAAM;AAAA;AAAA,EAE9B;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA,EAET,YAAY,QAAgB,QAAiB,YAAqB;AACjE,QAAI;AACJ,QAAI,SAAS,MAAM,GAAG;AACrB,UAAI,OAAO,OAAO,WAAW,UAAU;AACtC,kBAAU,OAAO;AAAA,MAClB,WAAW,OAAO,OAAO,YAAY,UAAU;AAC9C,kBAAU,OAAO;AAAA,MAClB;AAAA,IACD;AACA,UAAM,WAAW,0CAA0C,MAAM,EAAE;AACnE,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,SAAS;AACd,SAAK,aAAa;AAAA,EACnB;AACD;;;ACbA,IAAM,mBAAmB;AAEzB,SAAS,cAAc,UAAsC;AAC5D,QAAM,MACL,aACC,OAAO,YAAY,cAAc,QAAQ,KAAK,kBAAkB;AAClE,MAAI,CAAC,KAAK;AACT,UAAM,IAAI;AAAA,MACT;AAAA,IACD;AAAA,EACD;AACA,SAAO;AACR;AAOO,IAAM,UAAN,MAAc;AAAA,EACX;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,UAA0B,CAAC,GAAG;AACzC,SAAK,UAAU,cAAc,QAAQ,MAAM;AAC3C,SAAK,WAAW,QAAQ,WAAW;AACnC,SAAK,SAAS,QAAQ,SAAS,WAAW;AAAA,EAC3C;AAAA,EAEA,MAAM,MACL,MACA,OACA,SACa;AACb,UAAM,EAAE,YAAY,GAAG,OAAO,IAAI;AAClC,UAAM,WAAW,MAAM,KAAK,OAAO,IAAI,IAAI,MAAM,KAAK,QAAQ,GAAG;AAAA,MAChE,QAAQ;AAAA,MACR,SAAS;AAAA,QACR,gBAAgB;AAAA,QAChB,eAAe,UAAU,KAAK,OAAO;AAAA;AAAA;AAAA,QAGrC,mBACC,SAAS,kBAAkB,WAAW,OAAO,WAAW;AAAA,MAC1D;AAAA,MACA,MAAM,KAAK,UAAU,EAAE,YAAY,OAAO,CAAC;AAAA,IAC5C,CAAC;AACD,QAAI,CAAC,SAAS,IAAI;AACjB,UAAI;AACJ,UAAI;AACH,iBAAS,MAAM,SAAS,KAAK;AAAA,MAC9B,QAAQ;AAAA,MAER;AACA,YAAM,KAAK,SAAS,QAAQ,IAAI,aAAa;AAC7C,YAAM,aAAa,KAAK,OAAO,EAAE,IAAI;AACrC,YAAM,IAAI,aAAa,SAAS,QAAQ,QAAQ,UAAU;AAAA,IAC3D;AACA,WAAQ,MAAM,SAAS,KAAK;AAAA,EAC7B;AAAA,EAES,QAAQ;AAAA,IAChB,WAAW,CACV,OACA,YAEA,KAAK,MAAmB,uBAAuB,OAAO,OAAO;AAAA,IAC9D,MAAM,CAAC,OAAkB,YACxB,KAAK,MAAmB,kBAAkB,OAAO,OAAO;AAAA,IACzD,cAAc,CACb,OACA,YAEA,KAAK,MAAmB,2BAA2B,OAAO,OAAO;AAAA,IAClE,WAAW,CACV,OACA,YAEA,KAAK,MAAmB,2BAA2B,OAAO,OAAO;AAAA,IAClE,OAAO,CACN,OACA,YAEA,KAAK,MAAmB,mBAAmB,OAAO,OAAO;AAAA,EAC3D;AAAA,EAES,QAAQ;AAAA,IAChB,WAAW,CACV,OACA,YAEA,KAAK,MAAmB,uBAAuB,OAAO,OAAO;AAAA,EAC/D;AAAA,EAES,QAAQ;AAAA,IAChB,MAAM,CACL,OACA,YAEA,KAAK,MAAmB,kBAAkB,OAAO,OAAO;AAAA,EAC1D;AACD;","names":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fotovid/sdk",
+  "version": "0.1.0",
+  "description": "Typed TypeScript/Node client for the Fotovid media API",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "fotovid",
+    "ffmpeg",
+    "watermark",
+    "video",
+    "media",
+    "serverless",
+    "api",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/twinrise/fotovid-js.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/twinrise/fotovid-js/tree/main/packages/sdk",
+  "bugs": "https://github.com/twinrise/fotovid-js/issues",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}