@aicats/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario Bertsch
+
+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,140 @@
+# 🐱 ai-cats-sdk
+
+Official JavaScript/TypeScript SDK for the [ai-cats.net](https://ai-cats.net) API - Get AI-generated cat images!
+
+## Installation
+
+```bash
+npm install @aicats/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AiCats, Theme, Size } from '@aicats/sdk';
+
+// Get a random cat image
+const imageBlob = await AiCats.random();
+
+// Get a Halloween-themed cat
+const spookyCat = await AiCats.random({ theme: Theme.Halloween });
+
+// Search for cats
+const results = await AiCats.search({ query: 'orange fluffy cat', limit: 10 });
+```
+
+## API Reference
+
+### `AiCats.random(options?)`
+Get a random AI-generated cat image.
+
+```typescript
+const blob = await AiCats.random({
+  size: Size.Medium,     // Image size (default: Large)
+  theme: Theme.Xmas      // Optional theme
+});
+```
+
+### `AiCats.getById(id, size?)`
+Get a specific cat image by ID.
+
+```typescript
+const blob = await AiCats.getById('abc-123-def', Size.Small);
+```
+
+### `AiCats.getInfo(id)`
+Get detailed information about a cat image.
+
+```typescript
+const info = await AiCats.getInfo('abc-123-def');
+console.log(info.prompt);      // "A fluffy orange cat..."
+console.log(info.theme);       // "Halloween"
+console.log(info.dateCreated); // 1699012345678
+```
+
+### `AiCats.search(options?)`
+Search for cat images.
+
+```typescript
+const results = await AiCats.search({
+  query: 'black cat',    // Search text
+  limit: 20,             // Max results (1-100)
+  theme: Theme.Halloween,// Filter by theme
+  descending: true       // Newest first
+});
+
+for (const cat of results) {
+  console.log(cat.id, cat.url);
+}
+```
+
+### `AiCats.getSimilar(id, options?)`
+Find cats similar to a given cat.
+
+```typescript
+const similar = await AiCats.getSimilar('abc-123-def', { limit: 5 });
+```
+
+### `AiCats.getThemes()`
+Get all available themes.
+
+```typescript
+const themes = await AiCats.getThemes();
+// ['Default', 'Spring', 'Summer', 'Halloween', 'Xmas', ...]
+```
+
+### `AiCats.getCount(theme?)`
+Get the total number of cat images.
+
+```typescript
+const total = await AiCats.getCount();
+const halloweenCount = await AiCats.getCount(Theme.Halloween);
+```
+
+## Types
+
+### Size
+```typescript
+Size.Large     // 1024x1024 (default)
+Size.Medium    // 512x512
+Size.Small     // 256x256
+Size.Thumbnail // 128x128
+Size.Icon      // 64x64
+Size.Tiny      // 32x32
+Size.Micro     // 16x16
+```
+
+### Theme
+```typescript
+Theme.Default
+Theme.Spring
+Theme.Summer
+Theme.Autumn
+Theme.Winter
+Theme.Halloween
+Theme.Xmas
+Theme.NewYear
+Theme.Easter
+```
+
+## Browser Usage
+
+```html
+<script type="module">
+  import { AiCats } from 'https://unpkg.com/@aicats/sdk/dist/index.mjs';
+  
+  const blob = await AiCats.random();
+  const img = document.createElement('img');
+  img.src = URL.createObjectURL(blob);
+  document.body.appendChild(img);
+</script>
+```
+
+## Requirements
+
+- **Node.js 18+** (uses native `fetch`)
+- **Modern browsers** (Chrome, Firefox, Safari, Edge)
+
+## License
+
+MIT © [Mario Bertsch](https://mariobertsch.com)

package/dist/index.d.mts

@@ -0,0 +1,110 @@
+/**
+ * A search result containing a cat image ID and URL
+ */
+interface SearchResult {
+    /** Unique identifier for the cat image */
+    id: string;
+    /** Direct URL to the cat image */
+    url: string;
+}
+
+/**
+ * Available themes for AI cat images
+ */
+declare enum Theme {
+    /** Standard cat images */
+    Default = "Default",
+    /** Spring-themed cats with flowers and nature */
+    Spring = "Spring",
+    /** Summer-themed cats with sun and beach vibes */
+    Summer = "Summer",
+    /** Autumn-themed cats with fall colors and leaves */
+    Autumn = "Autumn",
+    /** Winter-themed cats with snow and cozy scenes */
+    Winter = "Winter",
+    /** Halloween-themed cats with spooky elements */
+    Halloween = "Halloween",
+    /** Christmas-themed cats with festive decorations */
+    Xmas = "Xmas",
+    /** New Year's themed cats with celebrations */
+    NewYear = "NewYear",
+    /** Easter-themed cats with bunnies and eggs */
+    Easter = "Easter"
+}
+
+/**
+ * Detailed information about a cat image
+ */
+interface CatInfo {
+    /** Unique identifier for the cat image */
+    id: string;
+    /** Unix timestamp when the image was created */
+    dateCreated: number;
+    /** The AI prompt used to generate this cat image */
+    prompt: string;
+    /** The theme of the cat image */
+    theme: Theme;
+}
+
+/**
+ * Available image sizes for AI cat images
+ */
+declare enum Size {
+    /** 1024x1024 pixels (default, highest quality) */
+    Large = "1024",
+    /** 512x512 pixels */
+    Medium = "512",
+    /** 256x256 pixels */
+    Small = "256",
+    /** 128x128 pixels */
+    Thumbnail = "128",
+    /** 64x64 pixels */
+    Icon = "64",
+    /** 32x32 pixels */
+    Tiny = "32",
+    /** 16x16 pixels */
+    Micro = "16"
+}
+
+/** Options for getting a random cat */
+interface RandomCatOptions {
+    /** Image size (default: Large) */
+    size?: Size;
+    /** Theme of the cat image */
+    theme?: Theme;
+}
+/** Options for searching cats */
+interface SearchOptions {
+    /** Search query (e.g., "orange fluffy cat") */
+    query?: string;
+    /** Maximum number of results (1-100, default: 10) */
+    limit?: number;
+    /** Pagination cursor - ID to start from */
+    from?: string;
+    /** Sort by newest first */
+    descending?: boolean;
+    /** Filter by theme */
+    theme?: Theme;
+    /** Image size in results */
+    size?: Size;
+}
+/** Options for similar cats */
+interface SimilarOptions {
+    /** Maximum number of results (1-100, default: 10) */
+    limit?: number;
+    /** Image size in results */
+    size?: Size;
+}
+
+declare const AiCats: {
+    random: (options?: RandomCatOptions) => Promise<Blob>;
+    getById: (id: string, size?: Size) => Promise<Blob>;
+    getInfo: (id: string) => Promise<CatInfo>;
+    search: (options?: SearchOptions) => Promise<SearchResult[]>;
+    getSimilar: (id: string, options?: SimilarOptions) => Promise<SearchResult[]>;
+    getSearchCompletion: (options?: SearchOptions) => Promise<string>;
+    getThemes: () => Promise<string[]>;
+    getCount: (theme?: Theme) => Promise<number>;
+};
+
+export { AiCats, type CatInfo, type RandomCatOptions, type SearchOptions, type SearchResult, type SimilarOptions, Size, Theme };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * A search result containing a cat image ID and URL
+ */
+interface SearchResult {
+    /** Unique identifier for the cat image */
+    id: string;
+    /** Direct URL to the cat image */
+    url: string;
+}
+
+/**
+ * Available themes for AI cat images
+ */
+declare enum Theme {
+    /** Standard cat images */
+    Default = "Default",
+    /** Spring-themed cats with flowers and nature */
+    Spring = "Spring",
+    /** Summer-themed cats with sun and beach vibes */
+    Summer = "Summer",
+    /** Autumn-themed cats with fall colors and leaves */
+    Autumn = "Autumn",
+    /** Winter-themed cats with snow and cozy scenes */
+    Winter = "Winter",
+    /** Halloween-themed cats with spooky elements */
+    Halloween = "Halloween",
+    /** Christmas-themed cats with festive decorations */
+    Xmas = "Xmas",
+    /** New Year's themed cats with celebrations */
+    NewYear = "NewYear",
+    /** Easter-themed cats with bunnies and eggs */
+    Easter = "Easter"
+}
+
+/**
+ * Detailed information about a cat image
+ */
+interface CatInfo {
+    /** Unique identifier for the cat image */
+    id: string;
+    /** Unix timestamp when the image was created */
+    dateCreated: number;
+    /** The AI prompt used to generate this cat image */
+    prompt: string;
+    /** The theme of the cat image */
+    theme: Theme;
+}
+
+/**
+ * Available image sizes for AI cat images
+ */
+declare enum Size {
+    /** 1024x1024 pixels (default, highest quality) */
+    Large = "1024",
+    /** 512x512 pixels */
+    Medium = "512",
+    /** 256x256 pixels */
+    Small = "256",
+    /** 128x128 pixels */
+    Thumbnail = "128",
+    /** 64x64 pixels */
+    Icon = "64",
+    /** 32x32 pixels */
+    Tiny = "32",
+    /** 16x16 pixels */
+    Micro = "16"
+}
+
+/** Options for getting a random cat */
+interface RandomCatOptions {
+    /** Image size (default: Large) */
+    size?: Size;
+    /** Theme of the cat image */
+    theme?: Theme;
+}
+/** Options for searching cats */
+interface SearchOptions {
+    /** Search query (e.g., "orange fluffy cat") */
+    query?: string;
+    /** Maximum number of results (1-100, default: 10) */
+    limit?: number;
+    /** Pagination cursor - ID to start from */
+    from?: string;
+    /** Sort by newest first */
+    descending?: boolean;
+    /** Filter by theme */
+    theme?: Theme;
+    /** Image size in results */
+    size?: Size;
+}
+/** Options for similar cats */
+interface SimilarOptions {
+    /** Maximum number of results (1-100, default: 10) */
+    limit?: number;
+    /** Image size in results */
+    size?: Size;
+}
+
+declare const AiCats: {
+    random: (options?: RandomCatOptions) => Promise<Blob>;
+    getById: (id: string, size?: Size) => Promise<Blob>;
+    getInfo: (id: string) => Promise<CatInfo>;
+    search: (options?: SearchOptions) => Promise<SearchResult[]>;
+    getSimilar: (id: string, options?: SimilarOptions) => Promise<SearchResult[]>;
+    getSearchCompletion: (options?: SearchOptions) => Promise<string>;
+    getThemes: () => Promise<string[]>;
+    getCount: (theme?: Theme) => Promise<number>;
+};
+
+export { AiCats, type CatInfo, type RandomCatOptions, type SearchOptions, type SearchResult, type SimilarOptions, Size, Theme };

package/dist/index.js

@@ -0,0 +1,160 @@
+"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, {
+  AiCats: () => AiCats,
+  Size: () => Size,
+  Theme: () => Theme
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/models/enums/size.enum.ts
+var Size = /* @__PURE__ */ ((Size2) => {
+  Size2["Large"] = "1024";
+  Size2["Medium"] = "512";
+  Size2["Small"] = "256";
+  Size2["Thumbnail"] = "128";
+  Size2["Icon"] = "64";
+  Size2["Tiny"] = "32";
+  Size2["Micro"] = "16";
+  return Size2;
+})(Size || {});
+
+// src/models/enums/theme.enum.ts
+var Theme = /* @__PURE__ */ ((Theme2) => {
+  Theme2["Default"] = "Default";
+  Theme2["Spring"] = "Spring";
+  Theme2["Summer"] = "Summer";
+  Theme2["Autumn"] = "Autumn";
+  Theme2["Winter"] = "Winter";
+  Theme2["Halloween"] = "Halloween";
+  Theme2["Xmas"] = "Xmas";
+  Theme2["NewYear"] = "NewYear";
+  Theme2["Easter"] = "Easter";
+  return Theme2;
+})(Theme || {});
+
+// src/api/v1.api.ts
+var ApiUrl = "https://api.ai-cats.net/v1";
+async function random(options) {
+  const params = new URLSearchParams();
+  if (options?.size) params.set("size", options.size);
+  if (options?.theme) params.set("theme", options.theme);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat${query}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching cat image: ${response.statusText}`);
+  }
+  const buffer = await response.arrayBuffer();
+  return new Blob([buffer], { type: "image/jpeg" });
+}
+async function getById(id, size = "1024" /* Large */) {
+  const response = await fetch(`${ApiUrl}/cat/${id}?size=${size}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching cat image: ${response.statusText}`);
+  }
+  const buffer = await response.arrayBuffer();
+  return new Blob([buffer], { type: "image/jpeg" });
+}
+async function getInfo(id) {
+  const response = await fetch(`${ApiUrl}/cat/info/${id}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching cat info: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function search(options = {}) {
+  const params = new URLSearchParams();
+  if (options.query) params.set("query", options.query);
+  if (options.limit) params.set("limit", options.limit.toString());
+  if (options.from) params.set("from", options.from);
+  if (options.descending) params.set("descending", "true");
+  if (options.theme) params.set("theme", options.theme);
+  if (options.size) params.set("size", options.size);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat/search${query}`);
+  if (!response.ok) {
+    throw new Error(`Error searching for cats: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function getSimilar(id, options) {
+  const params = new URLSearchParams();
+  if (options?.limit) params.set("limit", options.limit.toString());
+  if (options?.size) params.set("size", options.size);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat/similar/${id}${query}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching similar cats: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function getSearchCompletion(options = {}) {
+  const params = new URLSearchParams();
+  if (options.query) params.set("query", options.query);
+  if (options.limit) params.set("limit", options.limit.toString());
+  if (options.from) params.set("from", options.from);
+  if (options.descending) params.set("descending", "true");
+  if (options.theme) params.set("theme", options.theme);
+  if (options.size) params.set("size", options.size);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat/search-completion${query}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching completion: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data.completion;
+}
+async function getThemes() {
+  const response = await fetch(`${ApiUrl}/cat/themes`);
+  if (!response.ok) {
+    throw new Error(`Error fetching themes: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data.themes;
+}
+async function getCount(theme) {
+  const response = await fetch(`${ApiUrl}/cat/count${theme ? `?theme=${theme}` : ""}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching count: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data.count;
+}
+var V1Api = {
+  random,
+  getById,
+  getInfo,
+  search,
+  getSimilar,
+  getSearchCompletion,
+  getThemes,
+  getCount
+};
+
+// src/index.ts
+var AiCats = V1Api;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AiCats,
+  Size,
+  Theme
+});

package/dist/index.mjs

@@ -0,0 +1,131 @@
+// src/models/enums/size.enum.ts
+var Size = /* @__PURE__ */ ((Size2) => {
+  Size2["Large"] = "1024";
+  Size2["Medium"] = "512";
+  Size2["Small"] = "256";
+  Size2["Thumbnail"] = "128";
+  Size2["Icon"] = "64";
+  Size2["Tiny"] = "32";
+  Size2["Micro"] = "16";
+  return Size2;
+})(Size || {});
+
+// src/models/enums/theme.enum.ts
+var Theme = /* @__PURE__ */ ((Theme2) => {
+  Theme2["Default"] = "Default";
+  Theme2["Spring"] = "Spring";
+  Theme2["Summer"] = "Summer";
+  Theme2["Autumn"] = "Autumn";
+  Theme2["Winter"] = "Winter";
+  Theme2["Halloween"] = "Halloween";
+  Theme2["Xmas"] = "Xmas";
+  Theme2["NewYear"] = "NewYear";
+  Theme2["Easter"] = "Easter";
+  return Theme2;
+})(Theme || {});
+
+// src/api/v1.api.ts
+var ApiUrl = "https://api.ai-cats.net/v1";
+async function random(options) {
+  const params = new URLSearchParams();
+  if (options?.size) params.set("size", options.size);
+  if (options?.theme) params.set("theme", options.theme);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat${query}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching cat image: ${response.statusText}`);
+  }
+  const buffer = await response.arrayBuffer();
+  return new Blob([buffer], { type: "image/jpeg" });
+}
+async function getById(id, size = "1024" /* Large */) {
+  const response = await fetch(`${ApiUrl}/cat/${id}?size=${size}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching cat image: ${response.statusText}`);
+  }
+  const buffer = await response.arrayBuffer();
+  return new Blob([buffer], { type: "image/jpeg" });
+}
+async function getInfo(id) {
+  const response = await fetch(`${ApiUrl}/cat/info/${id}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching cat info: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function search(options = {}) {
+  const params = new URLSearchParams();
+  if (options.query) params.set("query", options.query);
+  if (options.limit) params.set("limit", options.limit.toString());
+  if (options.from) params.set("from", options.from);
+  if (options.descending) params.set("descending", "true");
+  if (options.theme) params.set("theme", options.theme);
+  if (options.size) params.set("size", options.size);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat/search${query}`);
+  if (!response.ok) {
+    throw new Error(`Error searching for cats: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function getSimilar(id, options) {
+  const params = new URLSearchParams();
+  if (options?.limit) params.set("limit", options.limit.toString());
+  if (options?.size) params.set("size", options.size);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat/similar/${id}${query}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching similar cats: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function getSearchCompletion(options = {}) {
+  const params = new URLSearchParams();
+  if (options.query) params.set("query", options.query);
+  if (options.limit) params.set("limit", options.limit.toString());
+  if (options.from) params.set("from", options.from);
+  if (options.descending) params.set("descending", "true");
+  if (options.theme) params.set("theme", options.theme);
+  if (options.size) params.set("size", options.size);
+  const query = params.toString() ? `?${params}` : "";
+  const response = await fetch(`${ApiUrl}/cat/search-completion${query}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching completion: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data.completion;
+}
+async function getThemes() {
+  const response = await fetch(`${ApiUrl}/cat/themes`);
+  if (!response.ok) {
+    throw new Error(`Error fetching themes: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data.themes;
+}
+async function getCount(theme) {
+  const response = await fetch(`${ApiUrl}/cat/count${theme ? `?theme=${theme}` : ""}`);
+  if (!response.ok) {
+    throw new Error(`Error fetching count: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data.count;
+}
+var V1Api = {
+  random,
+  getById,
+  getInfo,
+  search,
+  getSimilar,
+  getSearchCompletion,
+  getThemes,
+  getCount
+};
+
+// src/index.ts
+var AiCats = V1Api;
+export {
+  AiCats,
+  Size,
+  Theme
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@aicats/sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript SDK for the ai-cats.net API",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "public": "npm publish --access public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AiCatsAPI/ai-cats-sdk.git"
+  },
+  "keywords": [
+    "ai",
+    "cats",
+    "api",
+    "sdk",
+    "ai-cats",
+    "images"
+  ],
+  "author": {
+    "name": "Mario Bertsch",
+    "url": "https://mariobertsch.com"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/AiCatsAPI/ai-cats-sdk/issues"
+  },
+  "homepage": "https://ai-cats.net",
+  "devDependencies": {
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}