@useknockout/node 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 useknockout
+
+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,180 @@
+# @useknockout/node
+
+> Official TypeScript / Node.js client for [useknockout](https://github.com/useknockout/api) — state-of-the-art background removal API.
+
+- **Zero runtime dependencies** — uses the native `fetch` built into Node 18+
+- **First-class TypeScript** — full types, no `any`s in the public API
+- **Works anywhere `fetch` works** — Node, Bun, Deno, Vercel/Cloudflare Workers, serverless
+- **MIT licensed**
+
+---
+
+## Install
+
+```bash
+npm install @useknockout/node
+# or
+pnpm add @useknockout/node
+# or
+yarn add @useknockout/node
+```
+
+Requires **Node 18+** (for global `fetch` and `FormData`).
+
+## Quick start
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { Knockout } from "@useknockout/node";
+
+const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });
+
+// 1. From a local file path
+const png = await client.remove({ file: "./input.jpg" });
+await writeFile("./output.png", png);
+
+// 2. From a Buffer (e.g. uploaded via multer)
+const buf = await fs.readFile("./input.jpg");
+const out = await client.remove({ file: buf, filename: "input.jpg" });
+
+// 3. From a remote URL
+const url = await client.removeUrl({ url: "https://example.com/cat.jpg" });
+```
+
+## API
+
+### `new Knockout(options?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `token` | `string` | — | Bearer token. Required unless self-hosting without auth. |
+| `baseUrl` | `string` | `https://useknockout--api.modal.run` | Override the API endpoint. |
+| `timeoutMs` | `number` | `60_000` | Per-request timeout. |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch (for edge runtimes or polyfills). |
+
+### `client.remove(input)`
+
+Remove the background from a local file or in-memory buffer.
+
+| Field | Type | Description |
+|---|---|---|
+| `file` | `string \| Buffer \| Blob \| ArrayBuffer \| Uint8Array` | File path or raw image bytes. |
+| `filename` | `string?` | Optional override — auto-inferred from path if omitted. |
+| `format` | `"png" \| "webp"` | Output format. Default `"png"`. |
+
+Returns: `Buffer` of the processed image (PNG or WebP with transparent alpha).
+
+### `client.removeUrl(input)`
+
+Remove the background from a remote image URL.
+
+| Field | Type | Description |
+|---|---|---|
+| `url` | `string` | Remote image URL. |
+| `format` | `"png" \| "webp"` | Output format. Default `"png"`. |
+
+Returns: `Buffer` of the processed image.
+
+### `client.health()`
+
+Returns: `Promise<{ status: string; model: string }>`. No auth required.
+
+### `KnockoutError`
+
+Thrown on any non-2xx response. Fields:
+
+- `status` — HTTP status code
+- `code` — `"auth" | "rate_limit" | "bad_request" | "payload_too_large" | "server" | "unknown"`
+- `body` — raw response body string
+
+```ts
+import { KnockoutError } from "@useknockout/node";
+
+try {
+  await client.remove({ file: "./huge.jpg" });
+} catch (err) {
+  if (err instanceof KnockoutError && err.code === "payload_too_large") {
+    // retry with a resized image
+  }
+  throw err;
+}
+```
+
+## Framework examples
+
+### Next.js App Router
+
+```ts
+// app/api/remove/route.ts
+import { Knockout } from "@useknockout/node";
+
+const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });
+
+export async function POST(req: Request) {
+  const form = await req.formData();
+  const file = form.get("file") as File;
+  const buf = Buffer.from(await file.arrayBuffer());
+
+  const png = await client.remove({ file: buf, filename: file.name });
+
+  return new Response(new Uint8Array(png), {
+    headers: { "Content-Type": "image/png" },
+  });
+}
+```
+
+### Express
+
+```ts
+import express from "express";
+import multer from "multer";
+import { Knockout } from "@useknockout/node";
+
+const app = express();
+const upload = multer();
+const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });
+
+app.post("/remove", upload.single("file"), async (req, res) => {
+  const png = await client.remove({
+    file: req.file!.buffer,
+    filename: req.file!.originalname,
+  });
+  res.type("image/png").send(png);
+});
+```
+
+### Cloudflare Workers / Vercel Edge
+
+```ts
+import { Knockout } from "@useknockout/node";
+
+const client = new Knockout({ token: env.KNOCKOUT_TOKEN });
+
+export default {
+  async fetch(req: Request) {
+    const { searchParams } = new URL(req.url);
+    const imageUrl = searchParams.get("url")!;
+    const png = await client.removeUrl({ url: imageUrl });
+    return new Response(new Uint8Array(png), {
+      headers: { "Content-Type": "image/png" },
+    });
+  },
+};
+```
+
+## Self-hosting
+
+Point the SDK at your own Modal deployment:
+
+```ts
+const client = new Knockout({
+  token: "your-self-hosted-token",
+  baseUrl: "https://YOUR_WORKSPACE--api.modal.run",
+});
+```
+
+See [useknockout/api](https://github.com/useknockout/api) for the Modal deployment.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -0,0 +1,144 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var promises = require('fs/promises');
+var path = require('path');
+
+// src/index.ts
+var DEFAULT_BASE_URL = "https://useknockout--api.modal.run";
+var SDK_VERSION = "0.0.1";
+var KnockoutError = class _KnockoutError extends Error {
+  status;
+  code;
+  body;
+  constructor(status, body) {
+    const code = _KnockoutError.classify(status);
+    super(`Knockout API error ${status} (${code}): ${body || "no body"}`);
+    this.name = "KnockoutError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+  static classify(status) {
+    if (status === 401 || status === 403) return "auth";
+    if (status === 429) return "rate_limit";
+    if (status === 413) return "payload_too_large";
+    if (status >= 400 && status < 500) return "bad_request";
+    if (status >= 500) return "server";
+    return "unknown";
+  }
+};
+var Knockout = class {
+  baseUrl;
+  token;
+  timeoutMs;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.token = options.token;
+    this.timeoutMs = options.timeoutMs ?? 6e4;
+    const fetchRef = options.fetch ?? globalThis.fetch;
+    if (!fetchRef) {
+      throw new Error(
+        "Global fetch is unavailable. Provide `options.fetch` or use Node 18+."
+      );
+    }
+    this.fetchImpl = fetchRef.bind(globalThis);
+  }
+  /** Hit GET /health — no auth required. */
+  async health() {
+    const res = await this.request("GET", "/health");
+    const body = await res.text();
+    if (!res.ok) throw new KnockoutError(res.status, body);
+    return JSON.parse(body);
+  }
+  /**
+   * Remove the background from an image, returning the cleaned PNG/WebP bytes.
+   *
+   * @example
+   *   const png = await client.remove({ file: "./input.jpg" });
+   */
+  async remove(input) {
+    const format = input.format ?? "png";
+    const { blob, filename } = await toBlob(input);
+    const form = new FormData();
+    form.append("file", blob, filename);
+    const res = await this.request("POST", `/remove?format=${format}`, {
+      body: form
+    });
+    if (!res.ok) throw new KnockoutError(res.status, await res.text());
+    return Buffer.from(await res.arrayBuffer());
+  }
+  /**
+   * Remove the background from a remote URL, returning the cleaned PNG/WebP bytes.
+   *
+   * @example
+   *   const png = await client.removeUrl({ url: "https://example.com/cat.jpg" });
+   */
+  async removeUrl(input) {
+    const format = input.format ?? "png";
+    const res = await this.request("POST", "/remove-url", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url: input.url, format })
+    });
+    if (!res.ok) throw new KnockoutError(res.status, await res.text());
+    return Buffer.from(await res.arrayBuffer());
+  }
+  async request(method, path, init = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "User-Agent": `useknockout-node/${SDK_VERSION}`,
+      ...init.headers ?? {}
+    };
+    if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(url, {
+        method,
+        headers,
+        body: init.body,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+async function toBlob(input) {
+  const { file } = input;
+  const filename = input.filename ?? inferFilename(file);
+  if (typeof file === "string") {
+    const data = await promises.readFile(file);
+    return { blob: new Blob([new Uint8Array(data)]), filename };
+  }
+  if (file instanceof Blob) {
+    return { blob: file, filename };
+  }
+  if (file instanceof ArrayBuffer) {
+    return { blob: new Blob([new Uint8Array(file)]), filename };
+  }
+  if (file instanceof Uint8Array) {
+    return { blob: new Blob([new Uint8Array(file)]), filename };
+  }
+  if (Buffer.isBuffer(file)) {
+    return {
+      blob: new Blob([new Uint8Array(file)]),
+      filename
+    };
+  }
+  throw new TypeError("Unsupported `file` input. Provide a path, Buffer, Blob, ArrayBuffer, or Uint8Array.");
+}
+function inferFilename(file) {
+  if (typeof file === "string") return path.basename(file) || "image";
+  return "image";
+}
+var index_default = Knockout;
+
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.Knockout = Knockout;
+exports.KnockoutError = KnockoutError;
+exports.default = index_default;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["readFile","basename"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @useknockout/node — official TypeScript / Node.js client for the useknockout API.\n *\n * Quick start:\n *\n *   import { Knockout } from \"@useknockout/node\";\n *\n *   const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });\n *   const png = await client.remove({ file: \"./input.jpg\" });   // Buffer of PNG bytes\n *   await writeFile(\"out.png\", png);\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { basename } from \"node:path\";\n\nexport const DEFAULT_BASE_URL = \"https://useknockout--api.modal.run\";\nconst SDK_VERSION = \"0.0.1\";\n\nexport type OutputFormat = \"png\" | \"webp\";\n\nexport interface KnockoutOptions {\n  /** API bearer token. Required unless your self-hosted instance has no auth. */\n  token?: string;\n  /** Override the API base URL. Defaults to the hosted endpoint. */\n  baseUrl?: string;\n  /** Per-request timeout in milliseconds. Default 60_000. */\n  timeoutMs?: number;\n  /** Custom fetch (useful for edge runtimes / polyfills). Defaults to global fetch. */\n  fetch?: typeof fetch;\n}\n\nexport interface RemoveInput {\n  /** Local file path, Buffer, Blob, or ArrayBuffer of the image. */\n  file: string | Buffer | Blob | ArrayBuffer | Uint8Array;\n  /** Optional filename — inferred from path when `file` is a string. */\n  filename?: string;\n  /** Output format. Default \"png\". */\n  format?: OutputFormat;\n}\n\nexport interface RemoveUrlInput {\n  /** Remote URL of the image to process. */\n  url: string;\n  /** Output format. Default \"png\". */\n  format?: OutputFormat;\n}\n\nexport interface HealthResponse {\n  status: string;\n  model: string;\n}\n\n/**\n * Error thrown when the API returns a non-2xx response.\n */\nexport class KnockoutError extends Error {\n  public readonly status: number;\n  public readonly code: \"auth\" | \"rate_limit\" | \"bad_request\" | \"payload_too_large\" | \"server\" | \"unknown\";\n  public readonly body: string;\n\n  constructor(status: number, body: string) {\n    const code = KnockoutError.classify(status);\n    super(`Knockout API error ${status} (${code}): ${body || \"no body\"}`);\n    this.name = \"KnockoutError\";\n    this.status = status;\n    this.code = code;\n    this.body = body;\n  }\n\n  private static classify(status: number): KnockoutError[\"code\"] {\n    if (status === 401 || status === 403) return \"auth\";\n    if (status === 429) return \"rate_limit\";\n    if (status === 413) return \"payload_too_large\";\n    if (status >= 400 && status < 500) return \"bad_request\";\n    if (status >= 500) return \"server\";\n    return \"unknown\";\n  }\n}\n\n/**\n * useknockout API client.\n *\n * All methods return a `Buffer` (Node) of the processed image bytes.\n * Use `.toString(\"base64\")` or `writeFile(path, buf)` to persist.\n */\nexport class Knockout {\n  private readonly baseUrl: string;\n  private readonly token: string | undefined;\n  private readonly timeoutMs: number;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(options: KnockoutOptions = {}) {\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n    this.token = options.token;\n    this.timeoutMs = options.timeoutMs ?? 60_000;\n    const fetchRef = options.fetch ?? globalThis.fetch;\n    if (!fetchRef) {\n      throw new Error(\n        \"Global fetch is unavailable. Provide `options.fetch` or use Node 18+.\"\n      );\n    }\n    this.fetchImpl = fetchRef.bind(globalThis);\n  }\n\n  /** Hit GET /health — no auth required. */\n  async health(): Promise<HealthResponse> {\n    const res = await this.request(\"GET\", \"/health\");\n    const body = await res.text();\n    if (!res.ok) throw new KnockoutError(res.status, body);\n    return JSON.parse(body) as HealthResponse;\n  }\n\n  /**\n   * Remove the background from an image, returning the cleaned PNG/WebP bytes.\n   *\n   * @example\n   *   const png = await client.remove({ file: \"./input.jpg\" });\n   */\n  async remove(input: RemoveInput): Promise<Buffer> {\n    const format: OutputFormat = input.format ?? \"png\";\n    const { blob, filename } = await toBlob(input);\n\n    const form = new FormData();\n    form.append(\"file\", blob, filename);\n\n    const res = await this.request(\"POST\", `/remove?format=${format}`, {\n      body: form,\n    });\n\n    if (!res.ok) throw new KnockoutError(res.status, await res.text());\n    return Buffer.from(await res.arrayBuffer());\n  }\n\n  /**\n   * Remove the background from a remote URL, returning the cleaned PNG/WebP bytes.\n   *\n   * @example\n   *   const png = await client.removeUrl({ url: \"https://example.com/cat.jpg\" });\n   */\n  async removeUrl(input: RemoveUrlInput): Promise<Buffer> {\n    const format: OutputFormat = input.format ?? \"png\";\n    const res = await this.request(\"POST\", \"/remove-url\", {\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ url: input.url, format }),\n    });\n    if (!res.ok) throw new KnockoutError(res.status, await res.text());\n    return Buffer.from(await res.arrayBuffer());\n  }\n\n  private async request(\n    method: \"GET\" | \"POST\",\n    path: string,\n    init: { headers?: Record<string, string>; body?: BodyInit } = {}\n  ): Promise<Response> {\n    const url = `${this.baseUrl}${path}`;\n    const headers: Record<string, string> = {\n      \"User-Agent\": `useknockout-node/${SDK_VERSION}`,\n      ...(init.headers ?? {}),\n    };\n    if (this.token) headers[\"Authorization\"] = `Bearer ${this.token}`;\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs);\n    try {\n      return await this.fetchImpl(url, {\n        method,\n        headers,\n        body: init.body,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\nasync function toBlob(\n  input: RemoveInput\n): Promise<{ blob: Blob; filename: string }> {\n  const { file } = input;\n  const filename = input.filename ?? inferFilename(file);\n\n  if (typeof file === \"string\") {\n    const data = await readFile(file);\n    return { blob: new Blob([new Uint8Array(data)]), filename };\n  }\n  if (file instanceof Blob) {\n    return { blob: file, filename };\n  }\n  if (file instanceof ArrayBuffer) {\n    return { blob: new Blob([new Uint8Array(file)]), filename };\n  }\n  if (file instanceof Uint8Array) {\n    return { blob: new Blob([new Uint8Array(file)]), filename };\n  }\n  if (Buffer.isBuffer(file)) {\n    return {\n      blob: new Blob([new Uint8Array(file)]),\n      filename,\n    };\n  }\n  throw new TypeError(\"Unsupported `file` input. Provide a path, Buffer, Blob, ArrayBuffer, or Uint8Array.\");\n}\n\nfunction inferFilename(file: RemoveInput[\"file\"]): string {\n  if (typeof file === \"string\") return basename(file) || \"image\";\n  return \"image\";\n}\n\nexport default Knockout;\n"]}

package/dist/index.d.cts

@@ -0,0 +1,83 @@
+/**
+ * @useknockout/node — official TypeScript / Node.js client for the useknockout API.
+ *
+ * Quick start:
+ *
+ *   import { Knockout } from "@useknockout/node";
+ *
+ *   const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });
+ *   const png = await client.remove({ file: "./input.jpg" });   // Buffer of PNG bytes
+ *   await writeFile("out.png", png);
+ */
+declare const DEFAULT_BASE_URL = "https://useknockout--api.modal.run";
+type OutputFormat = "png" | "webp";
+interface KnockoutOptions {
+    /** API bearer token. Required unless your self-hosted instance has no auth. */
+    token?: string;
+    /** Override the API base URL. Defaults to the hosted endpoint. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 60_000. */
+    timeoutMs?: number;
+    /** Custom fetch (useful for edge runtimes / polyfills). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+interface RemoveInput {
+    /** Local file path, Buffer, Blob, or ArrayBuffer of the image. */
+    file: string | Buffer | Blob | ArrayBuffer | Uint8Array;
+    /** Optional filename — inferred from path when `file` is a string. */
+    filename?: string;
+    /** Output format. Default "png". */
+    format?: OutputFormat;
+}
+interface RemoveUrlInput {
+    /** Remote URL of the image to process. */
+    url: string;
+    /** Output format. Default "png". */
+    format?: OutputFormat;
+}
+interface HealthResponse {
+    status: string;
+    model: string;
+}
+/**
+ * Error thrown when the API returns a non-2xx response.
+ */
+declare class KnockoutError extends Error {
+    readonly status: number;
+    readonly code: "auth" | "rate_limit" | "bad_request" | "payload_too_large" | "server" | "unknown";
+    readonly body: string;
+    constructor(status: number, body: string);
+    private static classify;
+}
+/**
+ * useknockout API client.
+ *
+ * All methods return a `Buffer` (Node) of the processed image bytes.
+ * Use `.toString("base64")` or `writeFile(path, buf)` to persist.
+ */
+declare class Knockout {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: KnockoutOptions);
+    /** Hit GET /health — no auth required. */
+    health(): Promise<HealthResponse>;
+    /**
+     * Remove the background from an image, returning the cleaned PNG/WebP bytes.
+     *
+     * @example
+     *   const png = await client.remove({ file: "./input.jpg" });
+     */
+    remove(input: RemoveInput): Promise<Buffer>;
+    /**
+     * Remove the background from a remote URL, returning the cleaned PNG/WebP bytes.
+     *
+     * @example
+     *   const png = await client.removeUrl({ url: "https://example.com/cat.jpg" });
+     */
+    removeUrl(input: RemoveUrlInput): Promise<Buffer>;
+    private request;
+}
+
+export { DEFAULT_BASE_URL, type HealthResponse, Knockout, KnockoutError, type KnockoutOptions, type OutputFormat, type RemoveInput, type RemoveUrlInput, Knockout as default };

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @useknockout/node — official TypeScript / Node.js client for the useknockout API.
+ *
+ * Quick start:
+ *
+ *   import { Knockout } from "@useknockout/node";
+ *
+ *   const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });
+ *   const png = await client.remove({ file: "./input.jpg" });   // Buffer of PNG bytes
+ *   await writeFile("out.png", png);
+ */
+declare const DEFAULT_BASE_URL = "https://useknockout--api.modal.run";
+type OutputFormat = "png" | "webp";
+interface KnockoutOptions {
+    /** API bearer token. Required unless your self-hosted instance has no auth. */
+    token?: string;
+    /** Override the API base URL. Defaults to the hosted endpoint. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 60_000. */
+    timeoutMs?: number;
+    /** Custom fetch (useful for edge runtimes / polyfills). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+interface RemoveInput {
+    /** Local file path, Buffer, Blob, or ArrayBuffer of the image. */
+    file: string | Buffer | Blob | ArrayBuffer | Uint8Array;
+    /** Optional filename — inferred from path when `file` is a string. */
+    filename?: string;
+    /** Output format. Default "png". */
+    format?: OutputFormat;
+}
+interface RemoveUrlInput {
+    /** Remote URL of the image to process. */
+    url: string;
+    /** Output format. Default "png". */
+    format?: OutputFormat;
+}
+interface HealthResponse {
+    status: string;
+    model: string;
+}
+/**
+ * Error thrown when the API returns a non-2xx response.
+ */
+declare class KnockoutError extends Error {
+    readonly status: number;
+    readonly code: "auth" | "rate_limit" | "bad_request" | "payload_too_large" | "server" | "unknown";
+    readonly body: string;
+    constructor(status: number, body: string);
+    private static classify;
+}
+/**
+ * useknockout API client.
+ *
+ * All methods return a `Buffer` (Node) of the processed image bytes.
+ * Use `.toString("base64")` or `writeFile(path, buf)` to persist.
+ */
+declare class Knockout {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: KnockoutOptions);
+    /** Hit GET /health — no auth required. */
+    health(): Promise<HealthResponse>;
+    /**
+     * Remove the background from an image, returning the cleaned PNG/WebP bytes.
+     *
+     * @example
+     *   const png = await client.remove({ file: "./input.jpg" });
+     */
+    remove(input: RemoveInput): Promise<Buffer>;
+    /**
+     * Remove the background from a remote URL, returning the cleaned PNG/WebP bytes.
+     *
+     * @example
+     *   const png = await client.removeUrl({ url: "https://example.com/cat.jpg" });
+     */
+    removeUrl(input: RemoveUrlInput): Promise<Buffer>;
+    private request;
+}
+
+export { DEFAULT_BASE_URL, type HealthResponse, Knockout, KnockoutError, type KnockoutOptions, type OutputFormat, type RemoveInput, type RemoveUrlInput, Knockout as default };

package/dist/index.js

@@ -0,0 +1,137 @@
+import { readFile } from 'fs/promises';
+import { basename } from 'path';
+
+// src/index.ts
+var DEFAULT_BASE_URL = "https://useknockout--api.modal.run";
+var SDK_VERSION = "0.0.1";
+var KnockoutError = class _KnockoutError extends Error {
+  status;
+  code;
+  body;
+  constructor(status, body) {
+    const code = _KnockoutError.classify(status);
+    super(`Knockout API error ${status} (${code}): ${body || "no body"}`);
+    this.name = "KnockoutError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+  static classify(status) {
+    if (status === 401 || status === 403) return "auth";
+    if (status === 429) return "rate_limit";
+    if (status === 413) return "payload_too_large";
+    if (status >= 400 && status < 500) return "bad_request";
+    if (status >= 500) return "server";
+    return "unknown";
+  }
+};
+var Knockout = class {
+  baseUrl;
+  token;
+  timeoutMs;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.token = options.token;
+    this.timeoutMs = options.timeoutMs ?? 6e4;
+    const fetchRef = options.fetch ?? globalThis.fetch;
+    if (!fetchRef) {
+      throw new Error(
+        "Global fetch is unavailable. Provide `options.fetch` or use Node 18+."
+      );
+    }
+    this.fetchImpl = fetchRef.bind(globalThis);
+  }
+  /** Hit GET /health — no auth required. */
+  async health() {
+    const res = await this.request("GET", "/health");
+    const body = await res.text();
+    if (!res.ok) throw new KnockoutError(res.status, body);
+    return JSON.parse(body);
+  }
+  /**
+   * Remove the background from an image, returning the cleaned PNG/WebP bytes.
+   *
+   * @example
+   *   const png = await client.remove({ file: "./input.jpg" });
+   */
+  async remove(input) {
+    const format = input.format ?? "png";
+    const { blob, filename } = await toBlob(input);
+    const form = new FormData();
+    form.append("file", blob, filename);
+    const res = await this.request("POST", `/remove?format=${format}`, {
+      body: form
+    });
+    if (!res.ok) throw new KnockoutError(res.status, await res.text());
+    return Buffer.from(await res.arrayBuffer());
+  }
+  /**
+   * Remove the background from a remote URL, returning the cleaned PNG/WebP bytes.
+   *
+   * @example
+   *   const png = await client.removeUrl({ url: "https://example.com/cat.jpg" });
+   */
+  async removeUrl(input) {
+    const format = input.format ?? "png";
+    const res = await this.request("POST", "/remove-url", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url: input.url, format })
+    });
+    if (!res.ok) throw new KnockoutError(res.status, await res.text());
+    return Buffer.from(await res.arrayBuffer());
+  }
+  async request(method, path, init = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "User-Agent": `useknockout-node/${SDK_VERSION}`,
+      ...init.headers ?? {}
+    };
+    if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(url, {
+        method,
+        headers,
+        body: init.body,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+async function toBlob(input) {
+  const { file } = input;
+  const filename = input.filename ?? inferFilename(file);
+  if (typeof file === "string") {
+    const data = await readFile(file);
+    return { blob: new Blob([new Uint8Array(data)]), filename };
+  }
+  if (file instanceof Blob) {
+    return { blob: file, filename };
+  }
+  if (file instanceof ArrayBuffer) {
+    return { blob: new Blob([new Uint8Array(file)]), filename };
+  }
+  if (file instanceof Uint8Array) {
+    return { blob: new Blob([new Uint8Array(file)]), filename };
+  }
+  if (Buffer.isBuffer(file)) {
+    return {
+      blob: new Blob([new Uint8Array(file)]),
+      filename
+    };
+  }
+  throw new TypeError("Unsupported `file` input. Provide a path, Buffer, Blob, ArrayBuffer, or Uint8Array.");
+}
+function inferFilename(file) {
+  if (typeof file === "string") return basename(file) || "image";
+  return "image";
+}
+var index_default = Knockout;
+
+export { DEFAULT_BASE_URL, Knockout, KnockoutError, index_default as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @useknockout/node — official TypeScript / Node.js client for the useknockout API.\n *\n * Quick start:\n *\n *   import { Knockout } from \"@useknockout/node\";\n *\n *   const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });\n *   const png = await client.remove({ file: \"./input.jpg\" });   // Buffer of PNG bytes\n *   await writeFile(\"out.png\", png);\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { basename } from \"node:path\";\n\nexport const DEFAULT_BASE_URL = \"https://useknockout--api.modal.run\";\nconst SDK_VERSION = \"0.0.1\";\n\nexport type OutputFormat = \"png\" | \"webp\";\n\nexport interface KnockoutOptions {\n  /** API bearer token. Required unless your self-hosted instance has no auth. */\n  token?: string;\n  /** Override the API base URL. Defaults to the hosted endpoint. */\n  baseUrl?: string;\n  /** Per-request timeout in milliseconds. Default 60_000. */\n  timeoutMs?: number;\n  /** Custom fetch (useful for edge runtimes / polyfills). Defaults to global fetch. */\n  fetch?: typeof fetch;\n}\n\nexport interface RemoveInput {\n  /** Local file path, Buffer, Blob, or ArrayBuffer of the image. */\n  file: string | Buffer | Blob | ArrayBuffer | Uint8Array;\n  /** Optional filename — inferred from path when `file` is a string. */\n  filename?: string;\n  /** Output format. Default \"png\". */\n  format?: OutputFormat;\n}\n\nexport interface RemoveUrlInput {\n  /** Remote URL of the image to process. */\n  url: string;\n  /** Output format. Default \"png\". */\n  format?: OutputFormat;\n}\n\nexport interface HealthResponse {\n  status: string;\n  model: string;\n}\n\n/**\n * Error thrown when the API returns a non-2xx response.\n */\nexport class KnockoutError extends Error {\n  public readonly status: number;\n  public readonly code: \"auth\" | \"rate_limit\" | \"bad_request\" | \"payload_too_large\" | \"server\" | \"unknown\";\n  public readonly body: string;\n\n  constructor(status: number, body: string) {\n    const code = KnockoutError.classify(status);\n    super(`Knockout API error ${status} (${code}): ${body || \"no body\"}`);\n    this.name = \"KnockoutError\";\n    this.status = status;\n    this.code = code;\n    this.body = body;\n  }\n\n  private static classify(status: number): KnockoutError[\"code\"] {\n    if (status === 401 || status === 403) return \"auth\";\n    if (status === 429) return \"rate_limit\";\n    if (status === 413) return \"payload_too_large\";\n    if (status >= 400 && status < 500) return \"bad_request\";\n    if (status >= 500) return \"server\";\n    return \"unknown\";\n  }\n}\n\n/**\n * useknockout API client.\n *\n * All methods return a `Buffer` (Node) of the processed image bytes.\n * Use `.toString(\"base64\")` or `writeFile(path, buf)` to persist.\n */\nexport class Knockout {\n  private readonly baseUrl: string;\n  private readonly token: string | undefined;\n  private readonly timeoutMs: number;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(options: KnockoutOptions = {}) {\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n    this.token = options.token;\n    this.timeoutMs = options.timeoutMs ?? 60_000;\n    const fetchRef = options.fetch ?? globalThis.fetch;\n    if (!fetchRef) {\n      throw new Error(\n        \"Global fetch is unavailable. Provide `options.fetch` or use Node 18+.\"\n      );\n    }\n    this.fetchImpl = fetchRef.bind(globalThis);\n  }\n\n  /** Hit GET /health — no auth required. */\n  async health(): Promise<HealthResponse> {\n    const res = await this.request(\"GET\", \"/health\");\n    const body = await res.text();\n    if (!res.ok) throw new KnockoutError(res.status, body);\n    return JSON.parse(body) as HealthResponse;\n  }\n\n  /**\n   * Remove the background from an image, returning the cleaned PNG/WebP bytes.\n   *\n   * @example\n   *   const png = await client.remove({ file: \"./input.jpg\" });\n   */\n  async remove(input: RemoveInput): Promise<Buffer> {\n    const format: OutputFormat = input.format ?? \"png\";\n    const { blob, filename } = await toBlob(input);\n\n    const form = new FormData();\n    form.append(\"file\", blob, filename);\n\n    const res = await this.request(\"POST\", `/remove?format=${format}`, {\n      body: form,\n    });\n\n    if (!res.ok) throw new KnockoutError(res.status, await res.text());\n    return Buffer.from(await res.arrayBuffer());\n  }\n\n  /**\n   * Remove the background from a remote URL, returning the cleaned PNG/WebP bytes.\n   *\n   * @example\n   *   const png = await client.removeUrl({ url: \"https://example.com/cat.jpg\" });\n   */\n  async removeUrl(input: RemoveUrlInput): Promise<Buffer> {\n    const format: OutputFormat = input.format ?? \"png\";\n    const res = await this.request(\"POST\", \"/remove-url\", {\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ url: input.url, format }),\n    });\n    if (!res.ok) throw new KnockoutError(res.status, await res.text());\n    return Buffer.from(await res.arrayBuffer());\n  }\n\n  private async request(\n    method: \"GET\" | \"POST\",\n    path: string,\n    init: { headers?: Record<string, string>; body?: BodyInit } = {}\n  ): Promise<Response> {\n    const url = `${this.baseUrl}${path}`;\n    const headers: Record<string, string> = {\n      \"User-Agent\": `useknockout-node/${SDK_VERSION}`,\n      ...(init.headers ?? {}),\n    };\n    if (this.token) headers[\"Authorization\"] = `Bearer ${this.token}`;\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs);\n    try {\n      return await this.fetchImpl(url, {\n        method,\n        headers,\n        body: init.body,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\nasync function toBlob(\n  input: RemoveInput\n): Promise<{ blob: Blob; filename: string }> {\n  const { file } = input;\n  const filename = input.filename ?? inferFilename(file);\n\n  if (typeof file === \"string\") {\n    const data = await readFile(file);\n    return { blob: new Blob([new Uint8Array(data)]), filename };\n  }\n  if (file instanceof Blob) {\n    return { blob: file, filename };\n  }\n  if (file instanceof ArrayBuffer) {\n    return { blob: new Blob([new Uint8Array(file)]), filename };\n  }\n  if (file instanceof Uint8Array) {\n    return { blob: new Blob([new Uint8Array(file)]), filename };\n  }\n  if (Buffer.isBuffer(file)) {\n    return {\n      blob: new Blob([new Uint8Array(file)]),\n      filename,\n    };\n  }\n  throw new TypeError(\"Unsupported `file` input. Provide a path, Buffer, Blob, ArrayBuffer, or Uint8Array.\");\n}\n\nfunction inferFilename(file: RemoveInput[\"file\"]): string {\n  if (typeof file === \"string\") return basename(file) || \"image\";\n  return \"image\";\n}\n\nexport default Knockout;\n"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@useknockout/node",
+  "version": "0.0.1",
+  "description": "Official Node.js client for useknockout — state-of-the-art background removal API.",
+  "keywords": [
+    "background-removal",
+    "remove-background",
+    "birefnet",
+    "image-processing",
+    "computer-vision",
+    "ai",
+    "segmentation",
+    "useknockout"
+  ],
+  "homepage": "https://github.com/useknockout/api",
+  "bugs": {
+    "url": "https://github.com/useknockout/node/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/useknockout/node.git"
+  },
+  "license": "MIT",
+  "author": "useknockout",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}