@tapcolorapp/api 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# @tapcolorapp/api
+
+Official TypeScript/JavaScript client for the [TapColor Developer API](https://developer.tapcolor.app) —
+browse coloring **categories** and **collections** over a simple REST API.
+
+Zero dependencies. Works in Node 18+, Deno, Bun and modern browsers.
+
+- 📚 Docs & live explorer: <https://developer.tapcolor.app>
+- 🔑 Request an API key: <https://tapcolor.app/contact/>
+- 🧩 OpenAPI spec: <https://api.tapcolor.app/openapi.json>
+
+## Install
+
+```bash
+# npm
+npm install @tapcolorapp/api
+
+# JSR (Deno / Node / Bun)
+deno add jsr:@tapcolorapp/api
+npx jsr add @tapcolorapp/api
+```
+
+## Quickstart
+
+```ts
+import { TapColor } from "@tapcolorapp/api";
+
+const tc = new TapColor({ apiKey: "YOUR_API_KEY" });
+
+// List categories
+const cats = await tc.categories();
+console.log(cats.total, "categories");
+
+// List collections (filter + search + pagination)
+const page = await tc.coloringPages({ category: "animals", limit: 20 });
+page.items.forEach((c) => console.log(c.subtopic, "->", c.url));
+
+// Iterate EVERY collection, auto-paginated
+for await (const c of tc.allColoringPages({ category: "animals" })) {
+  console.log(c.subtopicSlug);
+}
+```
+
+## API
+
+### `new TapColor(options)`
+
+| Option    | Type               | Default                       | Notes                               |
+| --------- | ------------------ | ----------------------------- | ----------------------------------- |
+| `apiKey`  | `string`           | —                             | Required. Sent as the `api-key` header. |
+| `baseUrl` | `string`           | `https://api.tapcolor.app`    | Override for testing/staging.       |
+| `fetch`   | `typeof fetch`     | global `fetch`                | Custom fetch for Node <18 / tests.  |
+
+### `tc.categories(): Promise<CategoriesResponse>`
+
+Lists all 25 categories.
+
+### `tc.coloringPages(params?): Promise<ColoringPagesResponse>`
+
+| Param      | Type     | Description                                        |
+| ---------- | -------- | -------------------------------------------------- |
+| `category` | `string` | Category slug, e.g. `animals`.                     |
+| `q`        | `string` | Search collection names (partial, case-insensitive). |
+| `limit`    | `number` | 1–100 (default 20).                                |
+| `offset`   | `number` | Pagination offset.                                 |
+
+### `tc.allColoringPages(params?): AsyncGenerator<Collection>`
+
+Auto-paginates and yields every matching collection.
+
+## Errors
+
+Any non-2xx response throws a `TapColorError` with `status` and `body`:
+
+```ts
+import { TapColor, TapColorError } from "@tapcolorapp/api";
+
+try {
+  await new TapColor({ apiKey: "bad" }).categories();
+} catch (err) {
+  if (err instanceof TapColorError) {
+    console.error(err.status, err.message); // 401 "invalid or missing api-key"
+  }
+}
+```
+
+Rate limit: **120 requests / 10 minutes per key** → `429`.
+
+## License
+
+MIT © TapColor

package/dist/index.cjs

@@ -0,0 +1,116 @@
+"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, {
+  TapColor: () => TapColor,
+  TapColorError: () => TapColorError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var TapColorError = class extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "TapColorError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var DEFAULT_BASE = "https://api.tapcolor.app";
+var TapColor = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new Error("TapColor: `apiKey` is required");
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+    const f = options.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new Error("TapColor: no global `fetch` found \u2014 pass options.fetch");
+    }
+    this.#fetch = f;
+  }
+  async #get(path, params) {
+    const url = new URL(this.#baseUrl + path);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== void 0 && v !== null && v !== "") {
+          url.searchParams.set(k, String(v));
+        }
+      }
+    }
+    const res = await this.#fetch(url.toString(), {
+      headers: { "api-key": this.#apiKey }
+    });
+    const text = await res.text();
+    let data = text;
+    try {
+      data = JSON.parse(text);
+    } catch {
+    }
+    if (!res.ok) {
+      const msg = data && typeof data === "object" && "error" in data ? String(data.error) : res.statusText || `HTTP ${res.status}`;
+      throw new TapColorError(res.status, msg, data);
+    }
+    return data;
+  }
+  /** List all 25 categories with collection and page counts. */
+  categories() {
+    return this.#get("/v1/categories");
+  }
+  /** List collections with optional filter, search and pagination. */
+  coloringPages(params = {}) {
+    return this.#get(
+      "/v1/coloring-pages",
+      params
+    );
+  }
+  /**
+   * Async-iterate every collection matching `params`, auto-paginating with
+   * `limit`/`offset` until the full result set is exhausted.
+   *
+   * ```ts
+   * for await (const c of tc.allColoringPages({ category: "animals" })) {
+   *   console.log(c.subtopic, c.url);
+   * }
+   * ```
+   */
+  async *allColoringPages(params = {}) {
+    const limit = params.limit ?? 100;
+    let offset = params.offset ?? 0;
+    for (; ; ) {
+      const page = await this.coloringPages({ ...params, limit, offset });
+      for (const item of page.items) yield item;
+      offset += page.count;
+      if (page.count === 0 || offset >= page.total) break;
+    }
+  }
+};
+var index_default = TapColor;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TapColor,
+  TapColorError
+});

package/dist/index.d.cts

@@ -0,0 +1,99 @@
+/**
+ * TapColor Developer API — official TypeScript/JavaScript client.
+ *
+ * Docs:   https://developer.tapcolor.app
+ * API:    https://api.tapcolor.app
+ * Source: https://github.com/tapcolorapp
+ *
+ * Zero dependencies. Works in Node 18+, Deno, Bun and modern browsers
+ * (uses the global `fetch`).
+ */
+/** A coloring category (one of the 25 top-level categories). */
+interface Category {
+    /** Human-readable name, e.g. "Animals". */
+    name: string;
+    /** Slug — use it as the `category` filter, e.g. "animals". */
+    slug: string;
+    /** Number of collections in the category. */
+    subtopics: number;
+    /** Total coloring pages across the category. */
+    pages: number;
+    /** Public category page on tapcolor.app. */
+    url: string;
+}
+/** A coloring collection (subtopic). */
+interface Collection {
+    category: string;
+    categorySlug: string;
+    subtopic: string;
+    subtopicSlug: string;
+    count: number;
+    url: string;
+    /** Cover thumbnail URL; may be null when no cover is set. */
+    image: string | null;
+}
+interface CategoriesResponse {
+    total: number;
+    items: Category[];
+}
+interface ColoringPagesResponse {
+    total: number;
+    limit: number;
+    offset: number;
+    count: number;
+    items: Collection[];
+}
+interface ColoringPagesParams {
+    /** Filter by category slug (see {@link Category.slug}). */
+    category?: string;
+    /** Search collection names (partial, case-insensitive). */
+    q?: string;
+    /** Page size, 1–100. Defaults to 20 server-side. */
+    limit?: number;
+    /** Skip the first N items for pagination. */
+    offset?: number;
+}
+interface TapColorOptions {
+    /** API key issued by TapColor (sent as the `api-key` header). */
+    apiKey: string;
+    /** Override the base URL. Defaults to `https://api.tapcolor.app`. */
+    baseUrl?: string;
+    /** Custom fetch implementation (e.g. for Node <18 or testing). */
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx response. */
+declare class TapColorError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+/**
+ * TapColor API client.
+ *
+ * ```ts
+ * import { TapColor } from "@tapcolorapp/api";
+ * const tc = new TapColor({ apiKey: "YOUR_API_KEY" });
+ * const { items } = await tc.coloringPages({ category: "animals", limit: 20 });
+ * ```
+ */
+declare class TapColor {
+    #private;
+    constructor(options: TapColorOptions);
+    /** List all 25 categories with collection and page counts. */
+    categories(): Promise<CategoriesResponse>;
+    /** List collections with optional filter, search and pagination. */
+    coloringPages(params?: ColoringPagesParams): Promise<ColoringPagesResponse>;
+    /**
+     * Async-iterate every collection matching `params`, auto-paginating with
+     * `limit`/`offset` until the full result set is exhausted.
+     *
+     * ```ts
+     * for await (const c of tc.allColoringPages({ category: "animals" })) {
+     *   console.log(c.subtopic, c.url);
+     * }
+     * ```
+     */
+    allColoringPages(params?: ColoringPagesParams): AsyncGenerator<Collection, void, unknown>;
+}
+
+export { type CategoriesResponse, type Category, type Collection, type ColoringPagesParams, type ColoringPagesResponse, TapColor, TapColorError, type TapColorOptions, TapColor as default };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * TapColor Developer API — official TypeScript/JavaScript client.
+ *
+ * Docs:   https://developer.tapcolor.app
+ * API:    https://api.tapcolor.app
+ * Source: https://github.com/tapcolorapp
+ *
+ * Zero dependencies. Works in Node 18+, Deno, Bun and modern browsers
+ * (uses the global `fetch`).
+ */
+/** A coloring category (one of the 25 top-level categories). */
+interface Category {
+    /** Human-readable name, e.g. "Animals". */
+    name: string;
+    /** Slug — use it as the `category` filter, e.g. "animals". */
+    slug: string;
+    /** Number of collections in the category. */
+    subtopics: number;
+    /** Total coloring pages across the category. */
+    pages: number;
+    /** Public category page on tapcolor.app. */
+    url: string;
+}
+/** A coloring collection (subtopic). */
+interface Collection {
+    category: string;
+    categorySlug: string;
+    subtopic: string;
+    subtopicSlug: string;
+    count: number;
+    url: string;
+    /** Cover thumbnail URL; may be null when no cover is set. */
+    image: string | null;
+}
+interface CategoriesResponse {
+    total: number;
+    items: Category[];
+}
+interface ColoringPagesResponse {
+    total: number;
+    limit: number;
+    offset: number;
+    count: number;
+    items: Collection[];
+}
+interface ColoringPagesParams {
+    /** Filter by category slug (see {@link Category.slug}). */
+    category?: string;
+    /** Search collection names (partial, case-insensitive). */
+    q?: string;
+    /** Page size, 1–100. Defaults to 20 server-side. */
+    limit?: number;
+    /** Skip the first N items for pagination. */
+    offset?: number;
+}
+interface TapColorOptions {
+    /** API key issued by TapColor (sent as the `api-key` header). */
+    apiKey: string;
+    /** Override the base URL. Defaults to `https://api.tapcolor.app`. */
+    baseUrl?: string;
+    /** Custom fetch implementation (e.g. for Node <18 or testing). */
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx response. */
+declare class TapColorError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+/**
+ * TapColor API client.
+ *
+ * ```ts
+ * import { TapColor } from "@tapcolorapp/api";
+ * const tc = new TapColor({ apiKey: "YOUR_API_KEY" });
+ * const { items } = await tc.coloringPages({ category: "animals", limit: 20 });
+ * ```
+ */
+declare class TapColor {
+    #private;
+    constructor(options: TapColorOptions);
+    /** List all 25 categories with collection and page counts. */
+    categories(): Promise<CategoriesResponse>;
+    /** List collections with optional filter, search and pagination. */
+    coloringPages(params?: ColoringPagesParams): Promise<ColoringPagesResponse>;
+    /**
+     * Async-iterate every collection matching `params`, auto-paginating with
+     * `limit`/`offset` until the full result set is exhausted.
+     *
+     * ```ts
+     * for await (const c of tc.allColoringPages({ category: "animals" })) {
+     *   console.log(c.subtopic, c.url);
+     * }
+     * ```
+     */
+    allColoringPages(params?: ColoringPagesParams): AsyncGenerator<Collection, void, unknown>;
+}
+
+export { type CategoriesResponse, type Category, type Collection, type ColoringPagesParams, type ColoringPagesResponse, TapColor, TapColorError, type TapColorOptions, TapColor as default };

package/dist/index.js

@@ -0,0 +1,90 @@
+// src/index.ts
+var TapColorError = class extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "TapColorError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var DEFAULT_BASE = "https://api.tapcolor.app";
+var TapColor = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new Error("TapColor: `apiKey` is required");
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+    const f = options.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new Error("TapColor: no global `fetch` found \u2014 pass options.fetch");
+    }
+    this.#fetch = f;
+  }
+  async #get(path, params) {
+    const url = new URL(this.#baseUrl + path);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== void 0 && v !== null && v !== "") {
+          url.searchParams.set(k, String(v));
+        }
+      }
+    }
+    const res = await this.#fetch(url.toString(), {
+      headers: { "api-key": this.#apiKey }
+    });
+    const text = await res.text();
+    let data = text;
+    try {
+      data = JSON.parse(text);
+    } catch {
+    }
+    if (!res.ok) {
+      const msg = data && typeof data === "object" && "error" in data ? String(data.error) : res.statusText || `HTTP ${res.status}`;
+      throw new TapColorError(res.status, msg, data);
+    }
+    return data;
+  }
+  /** List all 25 categories with collection and page counts. */
+  categories() {
+    return this.#get("/v1/categories");
+  }
+  /** List collections with optional filter, search and pagination. */
+  coloringPages(params = {}) {
+    return this.#get(
+      "/v1/coloring-pages",
+      params
+    );
+  }
+  /**
+   * Async-iterate every collection matching `params`, auto-paginating with
+   * `limit`/`offset` until the full result set is exhausted.
+   *
+   * ```ts
+   * for await (const c of tc.allColoringPages({ category: "animals" })) {
+   *   console.log(c.subtopic, c.url);
+   * }
+   * ```
+   */
+  async *allColoringPages(params = {}) {
+    const limit = params.limit ?? 100;
+    let offset = params.offset ?? 0;
+    for (; ; ) {
+      const page = await this.coloringPages({ ...params, limit, offset });
+      for (const item of page.items) yield item;
+      offset += page.count;
+      if (page.count === 0 || offset >= page.total) break;
+    }
+  }
+};
+var index_default = TapColor;
+export {
+  TapColor,
+  TapColorError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@tapcolorapp/api",
+  "version": "1.0.0",
+  "description": "Official TypeScript/JavaScript client for the TapColor Developer API — browse coloring categories and collections.",
+  "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"],
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "tapcolor",
+    "coloring",
+    "coloring-pages",
+    "api",
+    "sdk",
+    "rest",
+    "kids",
+    "client"
+  ],
+  "homepage": "https://developer.tapcolor.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tapcolorapp/tapcolor-js.git"
+  },
+  "bugs": { "url": "https://tapcolor.app/contact/" },
+  "author": "TapColor",
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  }
+}