@dupecom/botcha 0.6.0 → 0.9.0

package/README.md

@@ -12,11 +12,14 @@
 **BOTCHA** is a reverse CAPTCHA — it verifies that visitors are AI agents, not humans. Perfect for AI-only APIs, agent marketplaces, and bot networks.
 
 [![npm version](https://img.shields.io/npm/v/@dupecom/botcha?color=00d4ff)](https://www.npmjs.com/package/@dupecom/botcha)
+[![PyPI version](https://img.shields.io/pypi/v/botcha?color=00d4ff)](https://pypi.org/project/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)  
+🐍 **PyPI:** [botcha](https://pypi.org/project/botcha/)  
+🔐 **Verify:** [@botcha/verify](./packages/verify/) (TS) · [botcha-verify](./packages/python-verify/) (Python)  
 🔌 **OpenAPI:** [botcha.ai/openapi.json](https://botcha.ai/openapi.json)
 
 ## Why?
@@ -28,15 +31,26 @@ Use cases:
 - 🔄 AI-to-AI marketplaces
 - 🎫 Bot verification systems
 - 🔐 Autonomous agent authentication
+- 🏢 Multi-tenant app isolation
 
 ## Install
 
+### TypeScript/JavaScript
+
 ```bash
 npm install @dupecom/botcha
 ```
 
+### Python
+
+```bash
+pip install botcha
+```
+
 ## Quick Start
 
+### TypeScript/JavaScript
+
 ```typescript
 import express from 'express';
 import { botcha } from '@dupecom/botcha';
@@ -51,6 +65,21 @@ app.get('/agent-only', botcha.verify(), (req, res) => {
 app.listen(3000);
 ```
 
+### Python
+
+```python
+from botcha import BotchaClient, solve_botcha
+
+# Client SDK for AI agents
+async with BotchaClient() as client:
+    # Get verification token
+    token = await client.get_token()
+    
+    # Or auto-solve and fetch protected endpoints
+    response = await client.fetch("https://api.example.com/agent-only")
+    data = await response.json()
+```
+
 ## How It Works
 
 BOTCHA offers multiple challenge types. The default is **hybrid** — combining speed AND reasoning:
@@ -80,6 +109,135 @@ GET /v1/challenges?type=hybrid
 GET /v1/reasoning
 ```
 
+## 🔐 JWT Security (Production-Grade)
+
+BOTCHA uses **OAuth2-style token rotation** with short-lived access tokens and long-lived refresh tokens.
+
+> **📖 Full guide:** [doc/JWT-SECURITY.md](./doc/JWT-SECURITY.md) — endpoint reference, request/response examples, audience scoping, IP binding, revocation, design decisions.
+
+### Token Flow
+
+```
+1. Solve challenge → receive access_token (5min) + refresh_token (1hr)
+2. Use access_token for API calls
+3. When access_token expires → POST /v1/token/refresh with refresh_token
+4. When compromised → POST /v1/token/revoke to invalidate immediately
+```
+
+### Security Features
+
+| Feature | What it does |
+|---------|-------------|
+| **5-minute access tokens** | Compromise window reduced from 1hr to 5min |
+| **Refresh tokens (1hr)** | Renew access without re-solving challenges |
+| **Audience (`aud`) scoping** | Token for `api.stripe.com` is rejected by `api.github.com` |
+| **Client IP binding** | Optional — solve on machine A, can't use on machine B |
+| **Token revocation** | `POST /v1/token/revoke` — KV-backed, fail-open |
+| **JTI (JWT ID)** | Unique ID per token for revocation and audit |
+
+### Quick Example
+
+```typescript
+const client = new BotchaClient({
+  audience: 'https://api.example.com', // Scope token to this service
+});
+
+// Auto-handles: challenge → token → refresh → retry on 401
+const response = await client.fetch('https://api.example.com/agent-only');
+```
+
+```python
+async with BotchaClient(audience="https://api.example.com") as client:
+    response = await client.fetch("https://api.example.com/agent-only")
+```
+
+### Token Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /v1/token` | Get challenge for token flow |
+| `POST /v1/token/verify` | Submit solution → receive `access_token` + `refresh_token` |
+| `POST /v1/token/refresh` | Exchange `refresh_token` for new `access_token` |
+| `POST /v1/token/revoke` | Invalidate any token immediately |
+
+See **[JWT Security Guide](./doc/JWT-SECURITY.md)** for full request/response examples, `curl` commands, and server-side verification.
+
+## 🏢 Multi-Tenant API Keys
+
+BOTCHA supports **multi-tenant isolation** — create separate apps with unique API keys for different services or environments.
+
+### Why Multi-Tenant?
+
+- **Isolation**: Each app gets its own rate limits and analytics
+- **Security**: Tokens are scoped to specific apps via `app_id` claim
+- **Flexibility**: Different services can use the same BOTCHA instance
+- **Tracking**: Per-app usage analytics (coming soon)
+
+### Creating an App
+
+```bash
+# Create a new app
+curl -X POST https://botcha.ai/v1/apps
+
+# Returns (save the secret - it's only shown once!):
+{
+  "app_id": "app_abc123",
+  "app_secret": "sk_xyz789",
+  "warning": "Save your secret now. It won't be shown again."
+}
+```
+
+### Using Your App ID
+
+All challenge and token endpoints accept an optional `app_id` query parameter:
+
+```bash
+# Get challenge with app_id
+curl "https://botcha.ai/v1/challenges?app_id=app_abc123"
+
+# Get token with app_id
+curl "https://botcha.ai/v1/token?app_id=app_abc123"
+```
+
+When you solve a challenge with an `app_id`, the resulting token includes the `app_id` claim.
+
+### SDK Support
+
+**TypeScript:**
+
+```typescript
+import { BotchaClient } from '@dupecom/botcha/client';
+
+const client = new BotchaClient({
+  appId: 'app_abc123',  // All requests will include this app_id
+});
+
+const response = await client.fetch('https://api.example.com/agent-only');
+```
+
+**Python:**
+
+```python
+from botcha import BotchaClient
+
+async with BotchaClient(app_id="app_abc123") as client:
+    response = await client.fetch("https://api.example.com/agent-only")
+```
+
+### Rate Limiting
+
+Each app gets its own rate limit bucket:
+- Default rate limit: 100 requests/hour per app
+- Rate limit key: `rate:app:{app_id}`
+- Fail-open design: KV errors don't block requests
+
+### Get App Info
+
+```bash
+# Get app details (secret is NOT included)
+curl https://botcha.ai/v1/apps/app_abc123
+```
+
 ## 🔄 SSE Streaming Flow (AI-Native)
 
 For AI agents that prefer a **conversational handshake**, BOTCHA offers **Server-Sent Events (SSE)** streaming:
@@ -352,6 +510,50 @@ You can use the library freely, report issues, and discuss features. To contribu
 
 **See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for complete guidelines, solver code examples, agent setup instructions, and detailed workflows.**
 
+## Server-Side Verification (for API Providers)
+
+If you're building an API that accepts BOTCHA tokens from agents, use the verification SDKs:
+
+### TypeScript (Express / Hono)
+
+```bash
+npm install @botcha/verify
+```
+
+```typescript
+import { botchaVerify } from '@botcha/verify/express';
+
+app.use('/api', botchaVerify({
+  secret: process.env.BOTCHA_SECRET!,
+  audience: 'https://api.example.com',
+}));
+
+app.get('/api/protected', (req, res) => {
+  console.log('Solve time:', req.botcha?.solveTime);
+  res.json({ message: 'Welcome, verified agent!' });
+});
+```
+
+### Python (FastAPI / Django)
+
+```bash
+pip install botcha-verify
+```
+
+```python
+from fastapi import FastAPI, Depends
+from botcha_verify.fastapi import BotchaVerify
+
+app = FastAPI()
+botcha = BotchaVerify(secret='your-secret-key')
+
+@app.get('/api/data')
+async def get_data(token = Depends(botcha)):
+    return {"solve_time": token.solve_time}
+```
+
+> **Docs:** See [`@botcha/verify` README](./packages/verify/README.md) and [`botcha-verify` README](./packages/python-verify/README.md) for full API reference, Hono middleware, Django middleware, revocation checking, and custom error handlers.
+
 ## Client SDK (for AI Agents)
 
 If you're building an AI agent that needs to access BOTCHA-protected APIs, use the client SDK:
@@ -410,6 +612,22 @@ const answers = solveBotcha([123456, 789012]);
 // Returns: ['a1b2c3d4', 'e5f6g7h8']
 ```
 
+**Python SDK:**
+```python
+from botcha import BotchaClient, solve_botcha
+
+# Option 1: Auto-solve with client
+async with BotchaClient() as client:
+    response = await client.fetch("https://api.example.com/agent-only")
+    data = await response.json()
+
+# Option 2: Manual solve
+answers = solve_botcha([123456, 789012])
+# Returns: ['a1b2c3d4', 'e5f6g7h8']
+```
+
+> **Note:** The Python SDK is available on [PyPI](https://pypi.org/project/botcha/): `pip install botcha`
+
 ## License
 
 MIT © [Dupe](https://dupe.com)

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

@@ -21,7 +21,10 @@ export declare class BotchaClient {
     private agentIdentity;
     private maxRetries;
     private autoToken;
+    private appId?;
+    private opts;
     private cachedToken;
+    private _refreshToken;
     private tokenExpiresAt;
     constructor(options?: BotchaClientOptions);
     /**
@@ -34,12 +37,20 @@ export declare class BotchaClient {
     /**
      * 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).
+     * Token is cached until near expiry (refreshed at 4 minutes).
      *
      * @returns JWT token string
      * @throws Error if token acquisition fails
      */
     getToken(): Promise<string>;
+    /**
+     * Refresh the access token using the refresh token.
+     * Only works if a refresh token was obtained from a previous getToken() call.
+     *
+     * @returns New JWT access token string
+     * @throws Error if refresh fails or no refresh token available
+     */
+    refreshToken(): Promise<string>;
     /**
      * Clear the cached token, forcing a refresh on the next request
      */

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

@@ -1 +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,EACb,aAAa,EACb,WAAW,EACX,OAAO,EACP,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAEV,mBAAmB,EAGnB,cAAc,EAEf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;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"}
+{"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,EACb,aAAa,EACb,WAAW,EACX,OAAO,EACP,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAEV,mBAAmB,EAGnB,cAAc,EAEf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;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,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,IAAI,CAAsB;IAClC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAuB;gBAEjC,OAAO,GAAE,mBAAwB;IAS7C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAMnC;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IA2FjC;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAkCrC;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA+BlE;;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;IA2F/D;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAiBvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAIxD;AAED,eAAe,YAAY,CAAC"}

package/dist/lib/client/index.js

@@ -1,6 +1,6 @@
 import crypto from 'crypto';
 // SDK version - hardcoded since npm_package_version is unreliable when used as a library
-const SDK_VERSION = '0.4.0';
+const SDK_VERSION = '0.7.0';
 // Export stream client
 export { BotchaStreamClient } from './stream.js';
 /**
@@ -23,13 +23,18 @@ export class BotchaClient {
     agentIdentity;
     maxRetries;
     autoToken;
+    appId;
+    opts;
     cachedToken = null;
+    _refreshToken = null;
     tokenExpiresAt = null;
     constructor(options = {}) {
+        this.opts = 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;
+        this.appId = options.appId;
     }
     /**
      * Solve a BOTCHA speed challenge
@@ -43,23 +48,26 @@ export class BotchaClient {
     /**
      * 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).
+     * Token is cached until near expiry (refreshed at 4 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)
+        // Check if we have a valid cached token (refresh at 1 minute before expiry)
         if (this.cachedToken && this.tokenExpiresAt) {
             const now = Date.now();
             const timeUntilExpiry = this.tokenExpiresAt - now;
-            const refreshThreshold = 5 * 60 * 1000; // 5 minutes before expiry
+            const refreshThreshold = 1 * 60 * 1000; // 1 minute before expiry
             if (timeUntilExpiry > refreshThreshold) {
                 return this.cachedToken;
             }
         }
         // Step 1: Get challenge from GET /v1/token
-        const challengeRes = await fetch(`${this.baseUrl}/v1/token`, {
+        const tokenUrl = this.appId
+            ? `${this.baseUrl}/v1/token?app_id=${encodeURIComponent(this.appId)}`
+            : `${this.baseUrl}/v1/token`;
+        const challengeRes = await fetch(tokenUrl, {
             headers: { 'User-Agent': this.agentIdentity },
         });
         if (!challengeRes.ok) {
@@ -76,27 +84,80 @@ export class BotchaClient {
         }
         const answers = this.solve(problems);
         // Step 3: Submit solution to POST /v1/token/verify
+        const verifyBody = {
+            id: challengeData.challenge.id,
+            answers,
+        };
+        // Include audience if specified
+        if (this.opts.audience) {
+            verifyBody.audience = this.opts.audience;
+        }
+        // Include app_id if specified
+        if (this.appId) {
+            verifyBody.app_id = this.appId;
+        }
         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,
-            }),
+            body: JSON.stringify(verifyBody),
         });
         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) {
+        if (!verifyData.success && !verifyData.verified) {
+            throw new Error('Failed to obtain token from verification');
+        }
+        // Extract access token (prefer access_token field, fall back to token for backward compat)
+        const accessToken = verifyData.access_token || verifyData.token;
+        if (!accessToken) {
             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
+        // Store refresh token if provided
+        if (verifyData.refresh_token) {
+            this._refreshToken = verifyData.refresh_token;
+        }
+        // Cache the token - use expires_in from response (in seconds), default to 5 minutes
+        const expiresInSeconds = verifyData.expires_in || 300; // Default to 5 minutes
+        this.cachedToken = accessToken;
+        this.tokenExpiresAt = Date.now() + expiresInSeconds * 1000;
+        return this.cachedToken;
+    }
+    /**
+     * Refresh the access token using the refresh token.
+     * Only works if a refresh token was obtained from a previous getToken() call.
+     *
+     * @returns New JWT access token string
+     * @throws Error if refresh fails or no refresh token available
+     */
+    async refreshToken() {
+        if (!this._refreshToken) {
+            throw new Error('No refresh token available. Call getToken() first.');
+        }
+        const refreshRes = await fetch(`${this.baseUrl}/v1/token/refresh`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': this.agentIdentity,
+            },
+            body: JSON.stringify({
+                refresh_token: this._refreshToken,
+            }),
+        });
+        if (!refreshRes.ok) {
+            throw new Error(`Token refresh failed with status ${refreshRes.status} ${refreshRes.statusText}`);
+        }
+        const refreshData = await refreshRes.json();
+        if (!refreshData.access_token) {
+            throw new Error('Failed to obtain access token from refresh');
+        }
+        // Update cached token with new access token
+        this.cachedToken = refreshData.access_token;
+        const expiresInSeconds = refreshData.expires_in || 300; // Default to 5 minutes
+        this.tokenExpiresAt = Date.now() + expiresInSeconds * 1000;
         return this.cachedToken;
     }
     /**
@@ -104,13 +165,17 @@ export class BotchaClient {
      */
     clearToken() {
         this.cachedToken = null;
+        this._refreshToken = null;
         this.tokenExpiresAt = null;
     }
     /**
      * Get and solve a challenge from BOTCHA service
      */
     async solveChallenge() {
-        const res = await fetch(`${this.baseUrl}/api/speed-challenge`, {
+        const challengeUrl = this.appId
+            ? `${this.baseUrl}/api/speed-challenge?app_id=${encodeURIComponent(this.appId)}`
+            : `${this.baseUrl}/api/speed-challenge`;
+        const res = await fetch(challengeUrl, {
             headers: { 'User-Agent': this.agentIdentity },
         });
         if (!res.ok) {
@@ -180,16 +245,31 @@ export class BotchaClient {
             ...init,
             headers,
         });
-        // Handle 401 by refreshing token and retrying once
+        // Handle 401 by trying refresh first, then full re-verify if refresh fails
         if (response.status === 401 && this.autoToken) {
-            this.clearToken();
             try {
-                const token = await this.getToken();
+                // Try refresh token first if available
+                let token;
+                if (this._refreshToken) {
+                    try {
+                        token = await this.refreshToken();
+                    }
+                    catch (refreshError) {
+                        // Refresh failed, clear tokens and do full re-verify
+                        this.clearToken();
+                        token = await this.getToken();
+                    }
+                }
+                else {
+                    // No refresh token, clear and do full re-verify
+                    this.clearToken();
+                    token = await this.getToken();
+                }
                 headers.set('Authorization', `Bearer ${token}`);
                 response = await fetch(url, { ...init, headers });
             }
             catch (error) {
-                // Token refresh failed, return the 401 response
+                // Token refresh/acquisition failed, return the 401 response
             }
         }
         let retries = 0;
@@ -243,12 +323,17 @@ export class BotchaClient {
      */
     async createHeaders() {
         const { id, answers } = await this.solveChallenge();
-        return {
+        const headers = {
             'X-Botcha-Id': id,
             'X-Botcha-Challenge-Id': id,
             'X-Botcha-Answers': JSON.stringify(answers),
             'User-Agent': this.agentIdentity,
         };
+        // Include X-Botcha-App-Id header if appId is set
+        if (this.appId) {
+            headers['X-Botcha-App-Id'] = this.appId;
+        }
+        return headers;
     }
 }
 /**

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

@@ -16,6 +16,10 @@ export interface BotchaClientOptions {
     maxRetries?: number;
     /** Enable automatic token acquisition and management (default: true) */
     autoToken?: boolean;
+    /** Audience claim for token (optional) */
+    audience?: string;
+    /** Multi-tenant application ID (optional) */
+    appId?: string;
 }
 export interface ChallengeResponse {
     success: boolean;
@@ -44,6 +48,10 @@ export interface VerifyResponse {
 export interface TokenResponse {
     success: boolean;
     token: string | null;
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    refresh_expires_in?: number;
     expiresIn?: string;
     challenge?: {
         id: string;
@@ -52,6 +60,8 @@ export interface TokenResponse {
         instructions: string;
     };
     nextStep?: string;
+    verified?: boolean;
+    solveTimeMs?: number;
 }
 /**
  * Stream-related types for BotchaStreamClient

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

@@ -1 +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;AAED;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;IAClE,IAAI,EAAE,GAAG,CAAC;CACX;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;IACpE,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/client/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dupecom/botcha",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Prove you're a bot. Humans need not apply. Reverse CAPTCHA for AI-only APIs.",
   "workspaces": [
     "packages/*"