@dupecom/botcha 0.3.7 → 0.4.3

package/README.md

@@ -13,11 +13,21 @@
 
 [![npm version](https://img.shields.io/npm/v/@dupecom/botcha?color=00d4ff)](https://www.npmjs.com/package/@dupecom/botcha)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![AI Agents Only](https://img.shields.io/badge/contributors-AI%20agents%20only-ff6b6b)](./.github/CONTRIBUTING.md)
 
 🌐 **Website:** [botcha.ai](https://botcha.ai)  
 📦 **npm:** [@dupecom/botcha](https://www.npmjs.com/package/@dupecom/botcha)  
 🔌 **OpenAPI:** [botcha.ai/openapi.json](https://botcha.ai/openapi.json)
 
+## Packages
+
+| Package | Description | Install |
+|---------|-------------|---------|
+| [`@dupecom/botcha`](https://www.npmjs.com/package/@dupecom/botcha) | Core library + Express middleware | `npm install @dupecom/botcha` |
+| [`@dupecom/botcha-cli`](https://www.npmjs.com/package/@dupecom/botcha-cli) | CLI tool for testing & debugging | `npm install -g @dupecom/botcha-cli` |
+| [`@dupecom/botcha-langchain`](https://www.npmjs.com/package/@dupecom/botcha-langchain) | LangChain integration for AI agents | `npm install @dupecom/botcha-langchain` |
+| [`@dupecom/botcha-cloudflare`](./packages/cloudflare-workers) | Cloudflare Workers runtime | `npm install @dupecom/botcha-cloudflare` |
+
 ## Why?
 
 CAPTCHAs ask "Are you human?" — **BOTCHA asks "Are you an AI?"**
@@ -90,10 +100,12 @@ When a 403 is returned with a challenge:
 
 ```http
 X-Botcha-Challenge-Id: abc123
-X-Botcha-Challenge-Type: compute
-X-Botcha-Time-Limit: 5000
+X-Botcha-Challenge-Type: speed
+X-Botcha-Time-Limit: 500
 ```
 
+`X-Botcha-Challenge-Type` can be `speed` or `standard` depending on the configured challenge mode.
+
 **Example**: An agent can detect BOTCHA just by inspecting headers on ANY request:
 
 ```typescript
@@ -177,6 +189,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
+```
+
+The Workers package runs a v1 JWT-based flow and keeps legacy `/api/*` endpoints for backward compatibility. 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."
@@ -185,6 +221,20 @@ BOTCHA doesn't block all automation — it blocks *casual* human access while al
 
 For cryptographic proof of agent identity, see [Web Bot Auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture).
 
+## Contributing
+
+**🤖 This is an AI-only open source project.** Code contributions must come from AI agents.
+
+### For AI Agents
+
+Fork the repo, make your changes, and open a PR. You'll receive a BOTCHA challenge (5 SHA256 hashes to solve in 5 minutes). Once verified, your PR can be reviewed and merged.
+
+### For Humans
+
+You can use the library freely, report issues, and discuss features. To contribute code, you'll need to work with an AI coding agent like [Cursor](https://cursor.com), [Claude Code](https://claude.ai), [Cline](https://cline.bot), [Aider](https://aider.chat), or [OpenClaw](https://openclaw.ai).
+
+**See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for complete guidelines, solver code examples, agent setup instructions, and detailed workflows.**
+
 ## License
 
 MIT © [Ramin](https://github.com/i8ramin)
@@ -192,3 +242,104 @@ 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']
+```
+
+## CLI Tool
+
+Test and debug BOTCHA-protected endpoints from the command line:
+
+```bash
+# Test an endpoint
+npx @dupecom/botcha-cli test https://api.example.com/agent-only
+
+# Benchmark performance
+npx @dupecom/botcha-cli benchmark https://api.example.com/agent-only --iterations 100
+
+# Check headers
+npx @dupecom/botcha-cli headers https://api.example.com
+```
+
+See [`packages/cli/README.md`](./packages/cli/README.md) for full CLI documentation.
+
+## LangChain Integration
+
+Give your LangChain agents automatic BOTCHA-solving abilities:
+
+```typescript
+import { BotchaTool } from '@dupecom/botcha-langchain';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+
+const agent = createReactAgent({
+  llm: new ChatOpenAI({ model: 'gpt-4' }),
+  tools: [
+    new BotchaTool({ baseUrl: 'https://api.botcha.ai' }),
+    // ... other tools
+  ],
+});
+
+// Agent can now access BOTCHA-protected APIs automatically
+await agent.invoke({
+  messages: [{ role: 'user', content: 'Access the bot-only API' }]
+});
+```
+
+See [`packages/langchain/README.md`](./packages/langchain/README.md) for full documentation.

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

@@ -0,0 +1,90 @@
+export type { SpeedProblem, BotchaClientOptions, ChallengeResponse, StandardChallengeResponse, VerifyResponse, TokenResponse, } from './types.js';
+import type { BotchaClientOptions, VerifyResponse } from './types.js';
+/**
+ * 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;
+    private autoToken;
+    private cachedToken;
+    private tokenExpiresAt;
+    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 a JWT token from the BOTCHA service using the token flow.
+     * Automatically solves the challenge and verifies to obtain a token.
+     * Token is cached until near expiry (refreshed at 55 minutes).
+     *
+     * @returns JWT token string
+     * @throws Error if token acquisition fails
+     */
+    getToken(): Promise<string>;
+    /**
+     * Clear the cached token, forcing a refresh on the next request
+     */
+    clearToken(): void;
+    /**
+     * 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.
+     * If autoToken is enabled (default), automatically acquires and uses JWT tokens.
+     *
+     * @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":"AAMA,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAEV,mBAAmB,EAGnB,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAuB;gBAEjC,OAAO,GAAE,mBAAwB;IAO7C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAMnC;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAgEjC;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA4BlE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAsBpE;;;;;;;;;OASG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IA8E/D;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAUvD;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,336 @@
+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;
+    autoToken;
+    cachedToken = null;
+    tokenExpiresAt = null;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl || 'https://botcha.ai';
+        this.agentIdentity = options.agentIdentity || `BotchaClient/${SDK_VERSION}`;
+        this.maxRetries = options.maxRetries || 3;
+        this.autoToken = options.autoToken !== undefined ? options.autoToken : true;
+    }
+    /**
+     * 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 a JWT token from the BOTCHA service using the token flow.
+     * Automatically solves the challenge and verifies to obtain a token.
+     * Token is cached until near expiry (refreshed at 55 minutes).
+     *
+     * @returns JWT token string
+     * @throws Error if token acquisition fails
+     */
+    async getToken() {
+        // Check if we have a valid cached token (refresh at 55min = 3300000ms)
+        if (this.cachedToken && this.tokenExpiresAt) {
+            const now = Date.now();
+            const timeUntilExpiry = this.tokenExpiresAt - now;
+            const refreshThreshold = 5 * 60 * 1000; // 5 minutes before expiry
+            if (timeUntilExpiry > refreshThreshold) {
+                return this.cachedToken;
+            }
+        }
+        // Step 1: Get challenge from GET /v1/token
+        const challengeRes = await fetch(`${this.baseUrl}/v1/token`, {
+            headers: { 'User-Agent': this.agentIdentity },
+        });
+        if (!challengeRes.ok) {
+            throw new Error(`Token request failed with status ${challengeRes.status} ${challengeRes.statusText}`);
+        }
+        const challengeData = await challengeRes.json();
+        if (!challengeData.challenge) {
+            throw new Error('No challenge provided in token response');
+        }
+        // Step 2: Solve the challenge
+        const problems = normalizeProblems(challengeData.challenge.problems);
+        if (!problems) {
+            throw new Error('Invalid challenge problems format');
+        }
+        const answers = this.solve(problems);
+        // Step 3: Submit solution to POST /v1/token/verify
+        const verifyRes = await fetch(`${this.baseUrl}/v1/token/verify`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': this.agentIdentity,
+            },
+            body: JSON.stringify({
+                id: challengeData.challenge.id,
+                answers,
+            }),
+        });
+        if (!verifyRes.ok) {
+            throw new Error(`Token verification failed with status ${verifyRes.status} ${verifyRes.statusText}`);
+        }
+        const verifyData = await verifyRes.json();
+        if (!verifyData.success || !verifyData.token) {
+            throw new Error('Failed to obtain token from verification');
+        }
+        // Cache the token - default expiry is 1 hour
+        this.cachedToken = verifyData.token;
+        this.tokenExpiresAt = Date.now() + 60 * 60 * 1000; // 1 hour from now
+        return this.cachedToken;
+    }
+    /**
+     * Clear the cached token, forcing a refresh on the next request
+     */
+    clearToken() {
+        this.cachedToken = null;
+        this.tokenExpiresAt = null;
+    }
+    /**
+     * 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 problems = normalizeProblems(data.challenge.problems);
+        if (!problems) {
+            throw new Error('Invalid challenge problems format');
+        }
+        const answers = this.solve(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.
+     * If autoToken is enabled (default), automatically acquires and uses JWT tokens.
+     *
+     * @example
+     * ```typescript
+     * const response = await client.fetch('https://api.example.com/agent-only');
+     * const data = await response.json();
+     * ```
+     */
+    async fetch(url, init) {
+        const headers = new Headers(init?.headers);
+        headers.set('User-Agent', this.agentIdentity);
+        // If autoToken is enabled, try to use token-based auth
+        if (this.autoToken) {
+            try {
+                const token = await this.getToken();
+                headers.set('Authorization', `Bearer ${token}`);
+            }
+            catch (error) {
+                // If token acquisition fails, fall back to challenge header method
+                console.warn('Failed to acquire token, falling back to challenge headers:', error);
+            }
+        }
+        let response = await fetch(url, {
+            ...init,
+            headers,
+        });
+        // Handle 401 by refreshing token and retrying once
+        if (response.status === 401 && this.autoToken) {
+            this.clearToken();
+            try {
+                const token = await this.getToken();
+                headers.set('Authorization', `Bearer ${token}`);
+                response = await fetch(url, { ...init, headers });
+            }
+            catch (error) {
+                // Token refresh failed, return the 401 response
+            }
+        }
+        let retries = 0;
+        // Fall back to challenge header method for 403 responses
+        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
+            const challenge = body?.challenge;
+            if (!challenge) {
+                break;
+            }
+            if (!canRetryBody(init?.body)) {
+                break;
+            }
+            const retryHeaders = new Headers(init?.headers);
+            retryHeaders.set('User-Agent', this.agentIdentity);
+            if (challenge?.problems && Array.isArray(challenge.problems)) {
+                const problems = normalizeProblems(challenge.problems);
+                if (!problems) {
+                    break;
+                }
+                const answers = this.solve(problems);
+                retryHeaders.set('X-Botcha-Id', challenge.id);
+                retryHeaders.set('X-Botcha-Challenge-Id', challenge.id);
+                retryHeaders.set('X-Botcha-Answers', JSON.stringify(answers));
+                retryHeaders.set('X-Botcha-Solution', JSON.stringify(answers));
+            }
+            else if (challenge?.puzzle && typeof challenge.puzzle === 'string') {
+                const solution = solveStandardPuzzle(challenge.puzzle);
+                retryHeaders.set('X-Botcha-Challenge-Id', challenge.id);
+                retryHeaders.set('X-Botcha-Solution', solution);
+            }
+            else {
+                break;
+            }
+            response = await fetch(url, { ...init, headers: retryHeaders });
+            retries++;
+        }
+        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-Challenge-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;
+function normalizeProblems(problems) {
+    if (!Array.isArray(problems))
+        return null;
+    const numbers = [];
+    for (const problem of problems) {
+        if (typeof problem === 'number') {
+            numbers.push(problem);
+            continue;
+        }
+        if (typeof problem === 'object' && problem !== null && typeof problem.num === 'number') {
+            numbers.push(problem.num);
+            continue;
+        }
+        return null;
+    }
+    return numbers;
+}
+function solveStandardPuzzle(puzzle) {
+    const primeMatch = puzzle.match(/first\s+(\d+)\s+prime/i);
+    if (!primeMatch) {
+        throw new Error('Unsupported standard challenge puzzle format');
+    }
+    const primeCount = Number.parseInt(primeMatch[1], 10);
+    if (!Number.isFinite(primeCount) || primeCount <= 0) {
+        throw new Error('Invalid prime count in puzzle');
+    }
+    const primes = generatePrimes(primeCount);
+    const concatenated = primes.join('');
+    const hash = crypto.createHash('sha256').update(concatenated).digest('hex');
+    return hash.substring(0, 16);
+}
+function generatePrimes(count) {
+    const primes = [];
+    let num = 2;
+    while (primes.length < count) {
+        if (isPrime(num)) {
+            primes.push(num);
+        }
+        num++;
+    }
+    return primes;
+}
+function isPrime(n) {
+    if (n < 2)
+        return false;
+    if (n === 2)
+        return true;
+    if (n % 2 === 0)
+        return false;
+    for (let i = 3; i <= Math.sqrt(n); i += 2) {
+        if (n % i === 0)
+            return false;
+    }
+    return true;
+}
+function canRetryBody(body) {
+    if (body == null)
+        return true;
+    if (typeof body === 'string')
+        return true;
+    if (body instanceof URLSearchParams)
+        return true;
+    if (body instanceof ArrayBuffer)
+        return true;
+    if (ArrayBuffer.isView(body))
+        return true;
+    if (typeof Blob !== 'undefined' && body instanceof Blob)
+        return true;
+    if (typeof FormData !== 'undefined' && body instanceof FormData)
+        return true;
+    return false;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * BOTCHA Client SDK Type Definitions
+ *
+ * Types for the BotchaClient SDK including challenges, tokens, and configuration.
+ */
+export type SpeedProblem = number | {
+    num: number;
+    operation?: string;
+};
+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;
+    /** Enable automatic token acquisition and management (default: true) */
+    autoToken?: boolean;
+}
+export interface ChallengeResponse {
+    success: boolean;
+    challenge?: {
+        id: string;
+        problems: SpeedProblem[];
+        timeLimit: number;
+        instructions: string;
+    };
+}
+export interface StandardChallengeResponse {
+    success: boolean;
+    challenge?: {
+        id: string;
+        puzzle: string;
+        timeLimit: number;
+        hint?: string;
+    };
+}
+export interface VerifyResponse {
+    success: boolean;
+    message: string;
+    solveTimeMs?: number;
+    verdict?: string;
+}
+export interface TokenResponse {
+    success: boolean;
+    token: string | null;
+    expiresIn?: string;
+    challenge?: {
+        id: string;
+        problems: SpeedProblem[];
+        timeLimit: number;
+        instructions: string;
+    };
+    nextStep?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/client/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,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;IACpB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,YAAY,EAAE,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,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,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,YAAY,EAAE,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/lib/client/types.js

@@ -0,0 +1,6 @@
+/**
+ * BOTCHA Client SDK Type Definitions
+ *
+ * Types for the BotchaClient SDK including challenges, tokens, and configuration.
+ */
+export {};

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@dupecom/botcha",
-  "version": "0.3.7",
+  "version": "0.4.3",
   "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,12 @@
     "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",
+    "publish:all": "bash scripts/publish-all.sh",
+    "publish:dry": "bash scripts/publish-all.sh --dry-run",
     "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 +46,9 @@
     "middleware",
     "express",
     "api",
-    "authentication"
+    "authentication",
+    "sdk",
+    "client"
   ],
   "author": "Ramin <ramin@dupe.com>",
   "license": "MIT",
@@ -49,12 +63,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"