@aicats/sdk 1.0.1 → 1.0.4

package/README.md

@@ -30,26 +30,39 @@ 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
+  size: Size.Medium,       // Image size (default: Large)
+  theme: Theme.Xmas,       // Optional theme
+  responseType: 'blob'     // 'blob' | 'arrayBuffer' | 'base64' | 'dataUrl'
 });
+
+// Get as base64
+const base64 = await AiCats.random({ responseType: 'base64' });
+
+// Get as data URL (for direct use in img.src)
+const dataUrl = await AiCats.random({ responseType: 'dataUrl' });
 ```
 
-### `AiCats.getById(id, size?)`
+### `AiCats.getById(id, options?)`
 Get a specific cat image by ID.
 
 ```typescript
-const blob = await AiCats.getById('abc-123-def', Size.Small);
+const blob = await AiCats.getById('669de24a-1da1-4fcd-84b1-9e55a43a0e0e', { size: Size.Small });
+
+// Get as base64
+const base64 = await AiCats.getById('669de24a-1da1-4fcd-84b1-9e55a43a0e0e', { responseType: 'base64' });
+
+// Get as data URL
+const dataUrl = await AiCats.getById('669de24a-1da1-4fcd-84b1-9e55a43a0e0e', { responseType: 'dataUrl' });
 ```
 
 ### `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
+const info = await AiCats.getInfo('669de24a-1da1-4fcd-84b1-9e55a43a0e0e');
+console.log(info.prompt);      // "In a futuristic space observatory..."
+console.log(info.theme);       // "Default"
+console.log(info.dateCreated); // 1724534067586
 ```
 
 ### `AiCats.search(options?)`
@@ -57,10 +70,10 @@ 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
+  query: 'rainbow',       // Search text
+  limit: 20,              // Max results (1-100)
+  theme: Theme.Halloween, // Filter by theme
+  descending: true        // Newest first
 });
 
 for (const cat of results) {
@@ -72,7 +85,7 @@ for (const cat of results) {
 Find cats similar to a given cat.
 
 ```typescript
-const similar = await AiCats.getSimilar('abc-123-def', { limit: 5 });
+const similar = await AiCats.getSimilar('669de24a-1da1-4fcd-84b1-9e55a43a0e0e', { limit: 5 });
 ```
 
 ### `AiCats.getThemes()`
@@ -93,6 +106,14 @@ const halloweenCount = await AiCats.getCount(Theme.Halloween);
 
 ## Types
 
+### ResponseType
+```typescript
+'blob'        // Blob object (default)
+'arrayBuffer' // ArrayBuffer
+'base64'      // Base64 encoded string
+'dataUrl'     // Data URL (data:image/jpeg;base64,...)
+```
+
 ### Size
 ```typescript
 Size.Large     // 1024x1024 (default)

package/dist/index.d.mts

@@ -38,6 +38,8 @@ declare enum Theme {
 interface CatInfo {
     /** Unique identifier for the cat image */
     id: string;
+    /** URL to access the cat image */
+    url: string;
     /** Unix timestamp when the image was created */
     dateCreated: number;
     /** The AI prompt used to generate this cat image */
@@ -66,12 +68,18 @@ declare enum Size {
     Micro = "16"
 }
 
+/** Response type for image requests */
+type ResponseType = 'blob' | 'arrayBuffer' | 'base64' | 'dataUrl';
+/** Image response based on responseType */
+type ImageResponse<T extends ResponseType = 'blob'> = T extends 'blob' ? Blob : T extends 'arrayBuffer' ? ArrayBuffer : T extends 'base64' ? string : T extends 'dataUrl' ? string : Blob;
 /** Options for getting a random cat */
-interface RandomCatOptions {
+interface RandomCatOptions<T extends ResponseType = 'blob'> {
     /** Image size (default: Large) */
     size?: Size;
     /** Theme of the cat image */
     theme?: Theme;
+    /** Response format (default: blob) */
+    responseType?: T;
 }
 /** Options for searching cats */
 interface SearchOptions {
@@ -95,15 +103,22 @@ interface SimilarOptions {
     /** Image size in results */
     size?: Size;
 }
+/** Options for getting a cat by ID */
+interface GetByIdOptions<T extends ResponseType = 'blob'> {
+    /** Image size (default: Large) */
+    size?: Size;
+    /** Response format (default: blob) */
+    responseType?: T;
+}
 
 declare const AiCats: {
-    random: (options?: RandomCatOptions) => Promise<Blob>;
-    getById: (id: string, size?: Size) => Promise<Blob>;
+    random: <T extends ResponseType = "blob">(options?: RandomCatOptions<T>) => Promise<ImageResponse<T>>;
+    getById: <T extends ResponseType = "blob">(id: string, options?: GetByIdOptions<T>) => Promise<ImageResponse<T>>;
     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[]>;
+    getThemes: () => Promise<Theme[]>;
     getCount: (theme?: Theme) => Promise<number>;
 };
 

package/dist/index.d.ts

@@ -38,6 +38,8 @@ declare enum Theme {
 interface CatInfo {
     /** Unique identifier for the cat image */
     id: string;
+    /** URL to access the cat image */
+    url: string;
     /** Unix timestamp when the image was created */
     dateCreated: number;
     /** The AI prompt used to generate this cat image */
@@ -66,12 +68,18 @@ declare enum Size {
     Micro = "16"
 }
 
+/** Response type for image requests */
+type ResponseType = 'blob' | 'arrayBuffer' | 'base64' | 'dataUrl';
+/** Image response based on responseType */
+type ImageResponse<T extends ResponseType = 'blob'> = T extends 'blob' ? Blob : T extends 'arrayBuffer' ? ArrayBuffer : T extends 'base64' ? string : T extends 'dataUrl' ? string : Blob;
 /** Options for getting a random cat */
-interface RandomCatOptions {
+interface RandomCatOptions<T extends ResponseType = 'blob'> {
     /** Image size (default: Large) */
     size?: Size;
     /** Theme of the cat image */
     theme?: Theme;
+    /** Response format (default: blob) */
+    responseType?: T;
 }
 /** Options for searching cats */
 interface SearchOptions {
@@ -95,15 +103,22 @@ interface SimilarOptions {
     /** Image size in results */
     size?: Size;
 }
+/** Options for getting a cat by ID */
+interface GetByIdOptions<T extends ResponseType = 'blob'> {
+    /** Image size (default: Large) */
+    size?: Size;
+    /** Response format (default: blob) */
+    responseType?: T;
+}
 
 declare const AiCats: {
-    random: (options?: RandomCatOptions) => Promise<Blob>;
-    getById: (id: string, size?: Size) => Promise<Blob>;
+    random: <T extends ResponseType = "blob">(options?: RandomCatOptions<T>) => Promise<ImageResponse<T>>;
+    getById: <T extends ResponseType = "blob">(id: string, options?: GetByIdOptions<T>) => Promise<ImageResponse<T>>;
     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[]>;
+    getThemes: () => Promise<Theme[]>;
     getCount: (theme?: Theme) => Promise<number>;
 };
 

package/dist/index.js

@@ -54,25 +54,52 @@ var Theme = /* @__PURE__ */ ((Theme2) => {
 
 // src/api/v1.api.ts
 var ApiUrl = "https://api.ai-cats.net/v1";
+async function toResponseType(buffer, type = "blob") {
+  switch (type) {
+    case "arrayBuffer":
+      return buffer;
+    case "base64": {
+      const bytes = new Uint8Array(buffer);
+      let binary = "";
+      for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+      }
+      return btoa(binary);
+    }
+    case "dataUrl": {
+      const bytes = new Uint8Array(buffer);
+      let binary = "";
+      for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+      }
+      return `data:image/jpeg;base64,${btoa(binary)}`;
+    }
+    case "blob":
+    default:
+      return new Blob([buffer], { type: "image/jpeg" });
+  }
+}
 async function random(options) {
   const params = new URLSearchParams();
   if (options?.size) params.set("size", options.size);
   if (options?.theme) params.set("theme", options.theme);
+  params.set("rnd", Math.random().toString());
   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" });
+  return toResponseType(buffer, options?.responseType ?? "blob");
 }
-async function getById(id, size = "1024" /* Large */) {
+async function getById(id, options) {
+  const size = options?.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" });
+  return toResponseType(buffer, options?.responseType ?? "blob");
 }
 async function getInfo(id) {
   const response = await fetch(`${ApiUrl}/cat/info/${id}`);

package/dist/index.mjs

@@ -26,25 +26,52 @@ var Theme = /* @__PURE__ */ ((Theme2) => {
 
 // src/api/v1.api.ts
 var ApiUrl = "https://api.ai-cats.net/v1";
+async function toResponseType(buffer, type = "blob") {
+  switch (type) {
+    case "arrayBuffer":
+      return buffer;
+    case "base64": {
+      const bytes = new Uint8Array(buffer);
+      let binary = "";
+      for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+      }
+      return btoa(binary);
+    }
+    case "dataUrl": {
+      const bytes = new Uint8Array(buffer);
+      let binary = "";
+      for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+      }
+      return `data:image/jpeg;base64,${btoa(binary)}`;
+    }
+    case "blob":
+    default:
+      return new Blob([buffer], { type: "image/jpeg" });
+  }
+}
 async function random(options) {
   const params = new URLSearchParams();
   if (options?.size) params.set("size", options.size);
   if (options?.theme) params.set("theme", options.theme);
+  params.set("rnd", Math.random().toString());
   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" });
+  return toResponseType(buffer, options?.responseType ?? "blob");
 }
-async function getById(id, size = "1024" /* Large */) {
+async function getById(id, options) {
+  const size = options?.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" });
+  return toResponseType(buffer, options?.responseType ?? "blob");
 }
 async function getInfo(id) {
   const response = await fetch(`${ApiUrl}/cat/info/${id}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicats/sdk",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Official JavaScript SDK for the ai-cats.net API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",