@dupecom/botcha 0.3.7 → 0.4.1

package/README.md

@@ -18,6 +18,13 @@
 📦 **npm:** [@dupecom/botcha](https://www.npmjs.com/package/@dupecom/botcha)  
 🔌 **OpenAPI:** [botcha.ai/openapi.json](https://botcha.ai/openapi.json)
 
+## Packages
+
+| Package | Runtime | Install |
+|---------|---------|---------|
+| [`@dupecom/botcha`](https://www.npmjs.com/package/@dupecom/botcha) | Node.js / Express | `npm install @dupecom/botcha` |
+| [`@dupecom/botcha-cloudflare`](./packages/cloudflare-workers) | Cloudflare Workers | `npm install @dupecom/botcha-cloudflare` |
+
 ## Why?
 
 CAPTCHAs ask "Are you human?" — **BOTCHA asks "Are you an AI?"**
@@ -177,6 +184,30 @@ const answers = botcha.solve([645234, 891023, 334521]);
 6. ✅ Access granted
 ```
 
+## Cloudflare Workers
+
+For edge deployment, use the Cloudflare Workers package:
+
+```bash
+npm install @dupecom/botcha-cloudflare
+```
+
+```typescript
+// Uses Hono + Web Crypto API (no Node.js dependencies)
+import app from '@dupecom/botcha-cloudflare';
+export default app;
+```
+
+Or deploy your own instance:
+
+```bash
+cd packages/cloudflare-workers
+npm install
+npm run deploy  # Deploys to your Cloudflare account
+```
+
+Same API endpoints, same challenge logic, running at the edge. See [`packages/cloudflare-workers/README.md`](./packages/cloudflare-workers/README.md) for full docs.
+
 ## Philosophy
 
 > "If a human writes a script to solve BOTCHA using an LLM... they've built an AI agent."
@@ -192,3 +223,63 @@ MIT © [Ramin](https://github.com/i8ramin)
 ---
 
 Built by [@i8ramin](https://github.com/i8ramin) and Choco 🐢
+
+---
+
+## Client SDK (for AI Agents)
+
+If you're building an AI agent that needs to access BOTCHA-protected APIs, use the client SDK:
+
+```typescript
+import { BotchaClient } from '@dupecom/botcha/client';
+
+const client = new BotchaClient();
+
+// Option 1: Auto-solve - fetches URL, solves any BOTCHA challenges automatically
+const response = await client.fetch('https://api.example.com/agent-only');
+const data = await response.json();
+
+// Option 2: Pre-solve - get headers with solved challenge
+const headers = await client.createHeaders();
+const response = await fetch('https://api.example.com/agent-only', { headers });
+
+// Option 3: Manual solve - solve challenge problems directly
+const answers = client.solve([123456, 789012]);
+```
+
+### Client Options
+
+```typescript
+const client = new BotchaClient({
+  baseUrl: 'https://botcha.ai',      // BOTCHA service URL
+  agentIdentity: 'MyAgent/1.0',       // User-Agent string
+  maxRetries: 3,                      // Max challenge solve attempts
+});
+```
+
+### Framework Integration Examples
+
+**OpenClaw / LangChain:**
+```typescript
+import { BotchaClient } from '@dupecom/botcha/client';
+
+const botcha = new BotchaClient({ agentIdentity: 'MyLangChainAgent/1.0' });
+
+// Use in your agent's HTTP tool
+const tool = {
+  name: 'fetch_protected_api',
+  call: async (url: string) => {
+    const response = await botcha.fetch(url);
+    return response.json();
+  }
+};
+```
+
+**Standalone Helper:**
+```typescript
+import { solveBotcha } from '@dupecom/botcha/client';
+
+// Just solve the problems, handle the rest yourself
+const answers = solveBotcha([123456, 789012]);
+// Returns: ['a1b2c3d4', 'e5f6g7h8']
+```

package/dist/lib/client/index.d.ts

@@ -0,0 +1,94 @@
+export interface BotchaClientOptions {
+    /** Base URL of BOTCHA service (default: https://botcha.ai) */
+    baseUrl?: string;
+    /** Custom identity header value */
+    agentIdentity?: string;
+    /** Max retries for challenge solving */
+    maxRetries?: number;
+}
+export interface ChallengeResponse {
+    success: boolean;
+    challenge?: {
+        id: string;
+        problems: number[];
+        timeLimit: number;
+        instructions: string;
+    };
+}
+export interface VerifyResponse {
+    success: boolean;
+    message: string;
+    solveTimeMs?: number;
+    verdict?: string;
+}
+/**
+ * BOTCHA Client SDK for AI Agents
+ *
+ * Automatically handles BOTCHA challenges when accessing protected endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { BotchaClient } from '@dupecom/botcha/client';
+ *
+ * const client = new BotchaClient();
+ *
+ * // Automatically solves challenges and retries
+ * const response = await client.fetch('https://api.example.com/agent-only');
+ * ```
+ */
+export declare class BotchaClient {
+    private baseUrl;
+    private agentIdentity;
+    private maxRetries;
+    constructor(options?: BotchaClientOptions);
+    /**
+     * Solve a BOTCHA speed challenge
+     *
+     * @param problems - Array of numbers to hash
+     * @returns Array of SHA256 first 8 hex chars for each number
+     */
+    solve(problems: number[]): string[];
+    /**
+     * Get and solve a challenge from BOTCHA service
+     */
+    solveChallenge(): Promise<{
+        id: string;
+        answers: string[];
+    }>;
+    /**
+     * Verify a solved challenge
+     */
+    verify(id: string, answers: string[]): Promise<VerifyResponse>;
+    /**
+     * Fetch a URL, automatically solving BOTCHA challenges if encountered
+     *
+     * @example
+     * ```typescript
+     * const response = await client.fetch('https://api.example.com/agent-only');
+     * const data = await response.json();
+     * ```
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Create headers with pre-solved challenge for manual use
+     *
+     * @example
+     * ```typescript
+     * const headers = await client.createHeaders();
+     * const response = await fetch('https://api.example.com/agent-only', { headers });
+     * ```
+     */
+    createHeaders(): Promise<Record<string, string>>;
+}
+/**
+ * Convenience function for one-off solves
+ *
+ * @example
+ * ```typescript
+ * const answers = solveBotcha([123456, 789012]);
+ * // Returns: ['a1b2c3d4', 'e5f6g7h8']
+ * ```
+ */
+export declare function solveBotcha(problems: number[]): string[];
+export default BotchaClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/client/index.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,GAAE,mBAAwB;IAM7C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAMnC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAwBlE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAsBpE;;;;;;;;OAQG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IA2C/D;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CASvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAIxD;AAED,eAAe,YAAY,CAAC"}

package/dist/lib/client/index.js

@@ -0,0 +1,155 @@
+import crypto from 'crypto';
+// SDK version - hardcoded since npm_package_version is unreliable when used as a library
+const SDK_VERSION = '0.4.0';
+/**
+ * BOTCHA Client SDK for AI Agents
+ *
+ * Automatically handles BOTCHA challenges when accessing protected endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { BotchaClient } from '@dupecom/botcha/client';
+ *
+ * const client = new BotchaClient();
+ *
+ * // Automatically solves challenges and retries
+ * const response = await client.fetch('https://api.example.com/agent-only');
+ * ```
+ */
+export class BotchaClient {
+    baseUrl;
+    agentIdentity;
+    maxRetries;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl || 'https://botcha.ai';
+        this.agentIdentity = options.agentIdentity || `BotchaClient/${SDK_VERSION}`;
+        this.maxRetries = options.maxRetries || 3;
+    }
+    /**
+     * Solve a BOTCHA speed challenge
+     *
+     * @param problems - Array of numbers to hash
+     * @returns Array of SHA256 first 8 hex chars for each number
+     */
+    solve(problems) {
+        return problems.map(num => crypto.createHash('sha256').update(num.toString()).digest('hex').substring(0, 8));
+    }
+    /**
+     * Get and solve a challenge from BOTCHA service
+     */
+    async solveChallenge() {
+        const res = await fetch(`${this.baseUrl}/api/speed-challenge`, {
+            headers: { 'User-Agent': this.agentIdentity },
+        });
+        if (!res.ok) {
+            throw new Error(`Challenge request failed with status ${res.status} ${res.statusText}`);
+        }
+        const contentType = res.headers.get('content-type') || '';
+        if (!contentType.toLowerCase().includes('application/json')) {
+            throw new Error('Expected JSON response for challenge request');
+        }
+        const data = await res.json();
+        if (!data.success || !data.challenge) {
+            throw new Error('Failed to get challenge');
+        }
+        const answers = this.solve(data.challenge.problems);
+        return { id: data.challenge.id, answers };
+    }
+    /**
+     * Verify a solved challenge
+     */
+    async verify(id, answers) {
+        const res = await fetch(`${this.baseUrl}/api/speed-challenge`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': this.agentIdentity,
+            },
+            body: JSON.stringify({ id, answers }),
+        });
+        if (!res.ok) {
+            throw new Error(`Verification request failed with status ${res.status} ${res.statusText}`);
+        }
+        const contentType = res.headers.get('content-type') || '';
+        if (!contentType.toLowerCase().includes('application/json')) {
+            throw new Error('Expected JSON response for verification request');
+        }
+        return await res.json();
+    }
+    /**
+     * Fetch a URL, automatically solving BOTCHA challenges if encountered
+     *
+     * @example
+     * ```typescript
+     * const response = await client.fetch('https://api.example.com/agent-only');
+     * const data = await response.json();
+     * ```
+     */
+    async fetch(url, init) {
+        let response = await fetch(url, {
+            ...init,
+            headers: {
+                ...Object.fromEntries(new Headers(init?.headers).entries()),
+                'User-Agent': this.agentIdentity,
+            },
+        });
+        let retries = 0;
+        while (response.status === 403 && retries < this.maxRetries) {
+            // Clone response before reading body to preserve it for the caller
+            const clonedResponse = response.clone();
+            const body = await clonedResponse.json().catch(() => null);
+            // Check if this is a BOTCHA challenge
+            if (body?.error === 'BOTCHA_CHALLENGE' || body?.challenge?.problems) {
+                const challenge = body.challenge;
+                if (challenge?.problems && Array.isArray(challenge.problems)) {
+                    // Solve the challenge
+                    const answers = this.solve(challenge.problems);
+                    // Create fresh headers for retry to avoid state issues
+                    const retryHeaders = new Headers(init?.headers);
+                    retryHeaders.set('User-Agent', this.agentIdentity);
+                    retryHeaders.set('X-Botcha-Id', challenge.id);
+                    retryHeaders.set('X-Botcha-Answers', JSON.stringify(answers));
+                    response = await fetch(url, { ...init, headers: retryHeaders });
+                    retries++;
+                }
+                else {
+                    break;
+                }
+            }
+            else {
+                break;
+            }
+        }
+        return response;
+    }
+    /**
+     * Create headers with pre-solved challenge for manual use
+     *
+     * @example
+     * ```typescript
+     * const headers = await client.createHeaders();
+     * const response = await fetch('https://api.example.com/agent-only', { headers });
+     * ```
+     */
+    async createHeaders() {
+        const { id, answers } = await this.solveChallenge();
+        return {
+            'X-Botcha-Id': id,
+            'X-Botcha-Answers': JSON.stringify(answers),
+            'User-Agent': this.agentIdentity,
+        };
+    }
+}
+/**
+ * Convenience function for one-off solves
+ *
+ * @example
+ * ```typescript
+ * const answers = solveBotcha([123456, 789012]);
+ * // Returns: ['a1b2c3d4', 'e5f6g7h8']
+ * ```
+ */
+export function solveBotcha(problems) {
+    return problems.map(num => crypto.createHash('sha256').update(num.toString()).digest('hex').substring(0, 8));
+}
+export default BotchaClient;

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@dupecom/botcha",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "description": "Prove you're a bot. Humans need not apply. Reverse CAPTCHA for AI-only APIs.",
+  "workspaces": [
+    "packages/*"
+  ],
   "main": "dist/lib/index.js",
   "types": "dist/lib/index.d.ts",
   "type": "module",
@@ -9,6 +12,10 @@
     ".": {
       "import": "./dist/lib/index.js",
       "types": "./dist/lib/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/lib/client/index.js",
+      "types": "./dist/lib/client/index.d.ts"
     }
   },
   "files": [
@@ -20,7 +27,10 @@
     "build": "tsc",
     "dev": "tsx watch src/index.ts",
     "prepublishOnly": "npm run build",
-    "test": "echo \"Tests coming soon\"",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "release:patch": "npm version patch && git push --follow-tags",
     "release:minor": "npm version minor && git push --follow-tags",
     "release:major": "npm version major && git push --follow-tags"
@@ -34,7 +44,9 @@
     "middleware",
     "express",
     "api",
-    "authentication"
+    "authentication",
+    "sdk",
+    "client"
   ],
   "author": "Ramin <ramin@dupe.com>",
   "license": "MIT",
@@ -49,12 +61,20 @@
   "peerDependencies": {
     "express": "^4.0.0 || ^5.0.0"
   },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/express": "^4.17.25",
-    "@types/node": "^20.19.30",
-    "express": "^4.22.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "@types/node": "^20.19.0",
+    "@vitest/ui": "^4.0.18",
+    "express": "^4.18.2",
+    "happy-dom": "^20.4.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18"