@embed-ai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2025-present ZKAI Labs Pte. Ltd.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted
+provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice, this list of
+    conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright notice, this list of
+    conditions and the following disclaimer in the documentation and/or other materials
+    provided with the distribution.
+
+    3. Neither the name of the copyright holder nor the names of its contributors may
+    be used to endorse or promote products derived from this software without specific prior
+    written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,347 @@
+# Embed TypeScript
+
+The core TypeScript package for embed APIs, featuring an Effect-based HTTP client with robust error handling and configurable retry logic for mbd.xyz API.
+
+## Features
+
+- 🚀 **Effect-based HTTP client** with structured error handling
+- 🔄 **Configurable retry logic** with exponential backoff
+- 🛡️ **Type-safe error handling** with tagged error types
+- ⏱️ **Request timeouts** with proper timeout handling
+- 🔐 **Automatic authentication** with Bearer tokens
+- 📝 **All required headers** set automatically
+- 📊 **Built-in logging** of failed requests and retries
+- 🎯 **Selective retry logic** for different error types
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { getClient } from "@embed-ai/sdk"
+const client = getClient(process.env.API_KEY_EMBED)
+const feed = await client.feed.byUserId("16085")
+console.log("✅ Success we got:", feed.length, "items")
+```
+
+## Error Handling Guide
+
+The @embed-ai/sdk package provides comprehensive error handling with typed errors and automatic retries. Here's everything you need to know.
+
+### What Gets Retried Automatically
+
+- ✅ **Network errors** (connection failures, DNS issues)
+- ✅ **Timeout errors** (requests taking too long)
+- ✅ **Server errors** (500, 502, 503, 504 by default)
+- ✅ **Rate limiting** (429 when configured)
+- ❌ **Parse errors** (malformed JSON responses)
+- ❌ **Client errors** (4xx except when configured)
+
+### Basic Error Handling
+
+For simple applications, basic try/catch is sufficient:
+
+```typescript
+import { getClient } from "@embed-ai/sdk"
+
+const client = getClient(process.env.API_KEY_EMBED)
+
+try {
+  const feed = await client.feed.byUserId("16085")
+  return feed
+} catch (error) {
+  console.error("API request failed:", error)
+  throw error // Re-throw or handle as needed
+}
+```
+
+### Understanding Error Types
+
+The package exports four specific error types for structured error handling:
+
+```typescript
+import {
+  HttpRequestError,  // HTTP response errors (4xx, 5xx)
+  NetworkError,      // Network connection issues
+  TimeoutError,      // Request timeout errors
+  ParseError         // JSON parsing errors
+} from "@embed-ai/sdk"
+```
+
+Each error type contains rich information to help you understand and handle the issue:
+
+```typescript
+// HttpRequestError - HTTP response errors
+{
+  status: 401,                    // HTTP status code
+  statusText: "Unauthorized",     // Status text
+  url: "https://api.mbd.xyz/...", // Request URL
+  body: "Invalid API key"         // Response body (if available)
+}
+
+// NetworkError - Connection issues
+{
+  message: "Failed to fetch",     // Error description
+  cause: Error                    // Original error
+}
+
+// TimeoutError - Request timeouts
+{
+  message: "Request timed out",   // Error description
+  timeoutMs: 30000               // Timeout duration
+}
+
+// ParseError - JSON parsing issues
+{
+  message: "Failed to parse JSON", // Error description
+  cause: SyntaxError              // Original parsing error
+}
+```
+
+### Basic Usage with Error Handling
+
+```typescript
+import { getClient, HttpRequestError, NetworkError, TimeoutError } from "@embed-ai/sdk"
+
+const client = getClient(process.env.API_KEY_EMBED)
+
+try {
+  const feed = await client.feed.byUserId("16085")
+  console.log("✅ Success:", feed.length, "items")
+} catch (error) {
+  console.error("❌ Error:", error)
+  
+  // Handle specific error types
+  if (error instanceof HttpRequestError) {
+    console.error(`HTTP ${error.status}: ${error.statusText}`)
+  } else if (error instanceof NetworkError) {
+    console.error("Network connection failed")
+  } else if (error instanceof TimeoutError) {
+    console.error(`Request timed out after ${error.timeoutMs}ms`)
+  }
+}
+```
+
+### Typed Error Handling
+
+For production applications, use typed error handling for better control:
+
+```typescript
+import { 
+  getClient, 
+  HttpRequestError, 
+  NetworkError, 
+  TimeoutError, 
+  ParseError 
+} from "@embed-ai/sdk"
+
+const client = getClient(process.env.API_KEY_EMBED)
+
+async function getFeedWithErrorHandling(userId: string) {
+  try {
+    return await client.feed.byUserId(userId)
+  } catch (error) {
+    if (error instanceof HttpRequestError) {
+      switch (error.status) {
+        case 401:
+          throw new Error("Invalid API key - please check your credentials")
+        case 403:
+          throw new Error("Access denied - check your API permissions")
+        case 404:
+          throw new Error("User not found")
+        case 429:
+          throw new Error("Rate limit exceeded - please try again later")
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+          throw new Error("Server error - please try again later")
+        default:
+          throw new Error(`HTTP error ${error.status}: ${error.statusText}`)
+      }
+    } else if (error instanceof NetworkError) {
+      throw new Error("Network connection failed - check your internet connection")
+    } else if (error instanceof TimeoutError) {
+      throw new Error(`Request timed out after ${error.timeoutMs}ms`)
+    } else if (error instanceof ParseError) {
+      throw new Error("Invalid response from server")
+    } else {
+      throw new Error("Unknown error occurred")
+    }
+  }
+}
+```
+
+### Custom Retry Configuration
+
+Configure retry behavior for your specific needs:
+
+```typescript
+import { getClient } from "@embed-ai/sdk"
+
+const client = getClient(process.env.API_KEY_EMBED, {
+  retry: {
+    maxRetries: 5,                    // Max retry attempts
+    initialDelay: 1000,               // Initial delay in ms
+    exponentialBackoff: true,         // Use exponential backoff
+    maxDelay: 15000,                  // Max delay between retries
+    retryableStatusCodes: [429, 500, 502, 503, 504], // HTTP codes to retry
+    timeoutMs: 60000                  // Request timeout in ms
+  }
+})
+
+// Now all requests will use this retry configuration
+const feed = await client.feed.byWalletAddress("0x123...")
+```
+
+### What Happens When Retries Fail
+
+When all retry attempts are exhausted, you receive the **last error that occurred** with full context:
+
+```typescript
+try {
+  const feed = await client.feed.byUserId("16085")
+} catch (error) {
+  // This error represents the final failure after all retries
+  if (error instanceof HttpRequestError) {
+    console.error(`Final HTTP error after retries: ${error.status}`)
+    console.error(`Request URL: ${error.url}`)
+    console.error(`Response body: ${error.body}`)
+  } else if (error instanceof NetworkError) {
+    console.error(`Final network error after retries: ${error.message}`)
+  }
+}
+```
+
+**Error Flow:**
+1. **Request made** → Network fails
+2. **Retry 1** → Network fails  
+3. **Retry 2** → Network fails
+4. **Retry 3** → Network fails
+5. **Final error** → `NetworkError` with original failure details
+
+### Error Handling Best Practices
+
+#### 1. **Use Typed Error Handling in Production**
+
+```typescript
+// ✅ Good - Specific error handling
+try {
+  const feed = await client.feed.byUserId(userId)
+} catch (error) {
+  if (error instanceof HttpRequestError) {
+    // Handle specific HTTP errors
+  } else if (error instanceof NetworkError) {
+    // Handle network issues
+  }
+}
+
+// ❌ Avoid - Generic error handling
+try {
+  const feed = await client.feed.byUserId(userId)
+} catch (error) {
+  console.error("Something went wrong:", error) // Too generic
+}
+```
+
+#### 2. **Provide User-Friendly Error Messages**
+
+```typescript
+function getUserFriendlyError(error: unknown): string {
+  if (error instanceof HttpRequestError) {
+    switch (error.status) {
+      case 401: return "Please check your API key"
+      case 429: return "Too many requests - please wait a moment"
+      case 500: return "Server is temporarily unavailable"
+      default: return "Something went wrong with the request"
+    }
+  } else if (error instanceof NetworkError) {
+    return "Please check your internet connection"
+  } else if (error instanceof TimeoutError) {
+    return "Request took too long - please try again"
+  }
+  return "An unexpected error occurred"
+}
+```
+
+#### 3. **Implement Fallback Strategies**
+
+```typescript
+async function getFeedWithFallback(userId: string) {
+  try {
+    return await client.feed.byUserId(userId)
+  } catch (error) {
+    if (error instanceof HttpRequestError && error.status === 404) {
+      // User not found - return empty feed
+      return []
+    } else if (error instanceof NetworkError || error instanceof TimeoutError) {
+      // Network issues - return cached data if available
+      return getCachedFeed(userId) || []
+    }
+    throw error // Re-throw other errors
+  }
+}
+```
+
+#### 4. **Log Errors for Monitoring**
+
+```typescript
+import { getClient, HttpRequestError } from "@embed-ai/sdk"
+
+const client = getClient(process.env.API_KEY_EMBED)
+
+async function getFeedWithLogging(userId: string) {
+  try {
+    return await client.feed.byUserId(userId)
+  } catch (error) {
+    // Log error details for monitoring
+    if (error instanceof HttpRequestError) {
+      console.error("API Error:", {
+        status: error.status,
+        url: error.url,
+        userId,
+        timestamp: new Date().toISOString()
+      })
+    }
+    throw error
+  }
+}
+```
+
+## API Methods
+
+### Available Methods
+
+```typescript
+// Get personalized "For You" feed by user ID
+await client.feed.byUserId(userId: string, options?: FeedOptions)
+
+// Get personalized "For You" feed by wallet address
+await client.feed.byWalletAddress(walletAddress: string, options?: FeedOptions)
+
+// Feed management to create new feeds and manage these custom feeds e.g. as custom feed per user in your app, which can be built on top of base feeds
+await client.feed.createConfig(options: CreateFeedOptions)
+await client.feed.getConfig(configId: string)
+await client.feed.listConfigs(visibility?: "private" | "public")
+await client.feed.updateConfig(options: UpdateFeedOptions)
+```
+
+### Factory Function
+
+```typescript
+import { getClient } from "@embed-ai/sdk"
+
+// Create client with factory function
+const client = getClient(process.env.API_KEY_EMBED, {
+  retry: { maxRetries: 5 }
+})
+```
+
+
+## Why Effect?
+
+- **Structured Error Handling**: Type-safe error channels prevent runtime surprises
+- **Composable**: Chain and combine operations with powerful combinators
+- **Reliable**: Automatic retries handle transient failures gracefully
+- **Observable**: Built-in logging and tracing for debugging
+- **Type-Safe**: Full TypeScript support with inferred types

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@embed-ai/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "BSD-3-Clause",
+  "description": "The typescript sdk package for embed AI APIs.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ZKAI-Network/embed-sdk/",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "scripts": {
+    "build": "bun run build-esm && bun run build-annotate && bun run build-cjs && cp package.json README.md LICENSE dist/ && bun run fix-deps",
+    "build-esm": "tsc --project tsconfig.build.json --noEmit && tsc --project tsconfig.src.json",
+    "build-cjs": "babel dist --plugins @babel/transform-export-namespace-from --plugins @babel/transform-modules-commonjs --out-dir dist --source-maps",
+    "build-annotate": "babel dist --plugins annotate-pure-calls --out-dir dist --source-maps",
+    "fix-deps": "bun scripts/fix-deps.js",
+    "check": "tsc -b tsconfig.json",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  },
+  "dependencies": {
+    "@embed-ai/types": "^0.1.0",
+    "effect": "latest"
+  }
+}

package/src/client.d.ts

@@ -0,0 +1,165 @@
+import { FeedNamespace } from "./feed/namespace.js";
+declare const NetworkError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NetworkError";
+} & Readonly<A>;
+/**
+ * Network-related errors (connection issues, DNS failures, etc.)
+ */
+export declare class NetworkError extends NetworkError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const HttpRequestError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "HttpRequestError";
+} & Readonly<A>;
+/**
+ * HTTP response errors (4xx, 5xx status codes)
+ */
+export declare class HttpRequestError extends HttpRequestError_base<{
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    readonly body?: string;
+}> {
+}
+declare const ParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ParseError";
+} & Readonly<A>;
+/**
+ * JSON parsing errors
+ */
+export declare class ParseError extends ParseError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const TimeoutError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "TimeoutError";
+} & Readonly<A>;
+/**
+ * Timeout errors
+ */
+export declare class TimeoutError extends TimeoutError_base<{
+    readonly message: string;
+    readonly timeoutMs: number;
+}> {
+}
+/**
+ * Union of all possible HTTP client errors
+ */
+export type HttpClientError = NetworkError | HttpRequestError | ParseError | TimeoutError;
+/**
+ * Configuration for retry behavior
+ *
+ * @example
+ * ```typescript
+ * const client = getClient('your-api-key', {
+ *   retry: {
+ *     maxRetries: 5,
+ *     initialDelay: 1000,
+ *     exponentialBackoff: true,
+ *     timeoutMs: 30000
+ *   }
+ * })
+ * ```
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    readonly maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 1000) */
+    readonly initialDelay?: number;
+    /** Whether to use exponential backoff (default: true) */
+    readonly exponentialBackoff?: boolean;
+    /** Maximum delay between retries in milliseconds (default: 10000) */
+    readonly maxDelay?: number;
+    /** HTTP status codes that should trigger a retry (default: [500, 502, 503, 504]) */
+    readonly retryableStatusCodes?: ReadonlyArray<number>;
+    /** Request timeout in milliseconds (default: 30000) */
+    readonly timeoutMs?: number;
+}
+/**
+ * Configuration for the Embed API client
+ *
+ * @example
+ * ```typescript
+ * const client = getClient('your-api-key', {
+ *   title: 'my-app',
+ *   retry: {
+ *     maxRetries: 3,
+ *     timeoutMs: 30000
+ *   }
+ * })
+ * ```
+ */
+export interface mbdClientConfig {
+    /** Base URL for the API (default: https://api.mbd.xyz) */
+    readonly baseUrl?: string;
+    /** API token for authentication */
+    readonly token?: string;
+    /** HTTP referer header value */
+    readonly referer?: string;
+    /** Application title for tracking (default: embed_sdk_typescript) */
+    readonly title?: string;
+    /** Retry configuration */
+    readonly retry?: RetryConfig;
+}
+/**
+ * Main Embed API client providing access to personalized feeds and feed management
+ *
+ * @example
+ * ```typescript
+ * import { getClient } from '@embed-ai/sdk'
+ *
+ * const client = getClient('your-api-key')
+ *
+ * // Get personalized feed
+ * const feed = await client.feed.byUserId('16085')
+ *
+ * // Create a custom feed
+ * const customFeed = await client.feed.createConfig({
+ *   name: 'My Custom Feed',
+ *   description: 'A feed for my app'
+ * })
+ * ```
+ */
+export declare class mbdClient {
+    private http;
+    readonly feed: FeedNamespace;
+    constructor(token?: string, options?: mbdClientConfig);
+}
+/**
+ * Get a new Embed Client instance
+ *
+ * @param token - API token required for authentication
+ * @param options - Optional client configuration
+ * @returns Embed Client instance with namespaced methods
+ *
+ * @example
+ * ```typescript
+ * import { getClient } from '@embed-ai/sdk'
+ *
+ * // Basic usage
+ * const client = getClient('your-api-key')
+ *
+ * // Get personalized feed
+ * const feed = await client.feed.byUserId('16085')
+ *
+ * // Create a custom feed
+ * const customFeed = await client.feed.createConfig({
+ *   name: 'My Custom Feed',
+ *   description: 'A feed for my app'
+ * })
+ *
+ * // With configuration
+ * const client = getClient('your-api-key', {
+ *   retry: {
+ *     maxRetries: 3,
+ *     timeoutMs: 30000
+ *   }
+ * })
+ * ```
+ */
+export declare function getClient(token?: string, options?: mbdClientConfig): mbdClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;;;;AAOnD;;GAEG;AACH,qBAAa,YAAa,SAAQ,kBAAiC;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;CAAG;;;;AAEL;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,sBAAqC;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB,CAAC;CAAG;;;;AAEL;;GAEG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;CAAG;;;;AAEL;;GAEG;AACH,qBAAa,YAAa,SAAQ,kBAAiC;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,CAAC;CAAG;AAEL;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,gBAAgB,GAAG,UAAU,GAAG,YAAY,CAAA;AAMzF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;IACrC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrD,uDAAuD;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAkBD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAC7B;AA+PD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAY;IACxB,SAAgB,IAAI,EAAE,aAAa,CAAA;gBAEvB,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe;CAatD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAE9E"}