@mybase-dev/sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @mybase-dev/sdk
 
-Helpers for apps that run on [mybase](https://github.com/landonharter/mybase), a self-hosted backend.
+Helpers for apps that run on [mybase](https://github.com/LandonHarter/mybase), a self-hosted backend.
 
 ```sh
 npm install @mybase-dev/sdk   # or bun add / pnpm add
@@ -8,6 +8,31 @@ npm install @mybase-dev/sdk   # or bun add / pnpm add
 
 No runtime dependencies. Uses Web Crypto, so it works in Node 20+, Bun, Deno, Next.js route handlers, Hono, and edge runtimes.
 
+| Import | Use |
+| --- | --- |
+| `@mybase-dev/sdk/analytics` | Record page views, custom events, and errors |
+| `@mybase-dev/sdk/cache` | Read and write the project's cache over HTTP |
+| `@mybase-dev/sdk/ratelimit` | Check rate limits |
+| `@mybase-dev/sdk/queue` | Send, receive, and consume queue messages |
+| `@mybase-dev/sdk/search` | Search the web and read pages, plus tools for LLM agents |
+| `@mybase-dev/sdk/vector` | Vector, full-text, and hybrid search over documents |
+| `@mybase-dev/sdk/cron` | Verify cron calls, handle jobs, and schedule one-off tasks |
+| `@mybase-dev/sdk/better-auth` | Better Auth on mybase: database URL, session storage, audit plugin, captcha |
+| `@mybase-dev/sdk/captcha` | Solve captcha challenges in the browser, verify tokens on the server |
+| `@mybase-dev/sdk/config` | Declare cron jobs, rate limit rules, queues, and vector indexes in `mybase.config.ts` |
+
+## API keys
+
+Cache, rate limits, queues, and one-off tasks authenticate with a mybase API key (`mb_…`). Each key has per-service permissions (`cache:write`, `ratelimit:write`, `queue:write`, `cron:write`, … or `admin`) and can be limited to some projects, so one key can cover everything an app uses. Create one in the dashboard (Settings → API keys) or with the CLI:
+
+```sh
+mybase token create shop-app --project shop --perm cache:write,ratelimit:write,queue:write,cron:write
+```
+
+Put it in your app's server-side environment as `MYBASE_API_KEY`. Never expose it to browser code: analytics has its own public write key for that.
+
+Getting started guide: [docs/getting-started.md](docs/getting-started.md). Your mybase instance also serves every guide at `/docs` and `/llms.txt`.
+
 ## Analytics (`@mybase-dev/sdk/analytics`)
 
 Page views, custom events, and errors, shown on the project's Analytics page. Turn analytics on for the project (dashboard, or `mybase analytics enable <project>`) to get its public write key, then:
@@ -51,7 +76,7 @@ Full guide: [docs/cache.md](docs/cache.md).
 
 ## Rate limits (`@mybase-dev/sdk/ratelimit`)
 
-Limits shared by every instance of your app. Turn them on (dashboard, or `mybase ratelimit enable <project>`), create an API key with `ratelimit:write`, define rules on the dashboard or in `mybase.config.ts`, then:
+Limits shared by every instance of your app. Turn them on (dashboard, or `mybase ratelimit enable <project>`), use an API key with `ratelimit:write`, define rules on the dashboard or in [`mybase.config.ts`](#define-jobs-rules-and-queues-in-code), then:
 
 ```ts
 import { createRateLimiter, rateLimitHeaders } from "@mybase-dev/sdk/ratelimit";
@@ -65,7 +90,7 @@ If mybase can't be reached, it allows the request (pass `failClosed: true` to de
 
 ## Queues (`@mybase-dev/sdk/queue`)
 
-SQS-style standard and FIFO queues. Turn them on (dashboard, or `mybase queue enable <project>`), create an API key with `queue:write`, then:
+SQS-style standard and FIFO queues. Turn them on (dashboard, or `mybase queue enable <project>`), use an API key with `queue:write`, create queues on the dashboard, in [`mybase.config.ts`](#define-jobs-rules-and-queues-in-code), or with `queue.createQueue(...)`, then:
 
 ```ts
 import { createQueueClient } from "@mybase-dev/sdk/queue";
@@ -75,7 +100,73 @@ await queue.send("emails", { to: "ada@example.com" });
 queue.consume("emails", async (message) => sendEmail(message.json()));
 ```
 
-Delivery is at least once; failed messages are retried and can go to a dead-letter queue. Full guide: [docs/queues.md](docs/queues.md).
+Delivery is at least once; `consume` deletes a message when its handler resolves, failed messages are retried and can go to a dead-letter queue. Full guide: [docs/queues.md](docs/queues.md).
+
+## Web search (`@mybase-dev/sdk/search`)
+
+Web search and page reading for your app's AI agent, through mybase's own SearXNG (no search API to pay for). Turn it on (dashboard, or `mybase search enable <project>`), use an API key with `search:read`, then:
+
+```ts
+import { createSearchClient, searchTools } from "@mybase-dev/sdk/search";
+
+const web = createSearchClient({ apiUrl: "https://mybase.example.com", project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+const { results } = await web.search("bun sql postgres");
+const page = await web.fetch(results[0]!.url); // main content as markdown
+const tools = searchTools(web); // web_search + web_fetch for an LLM tool-use loop
+```
+
+Full guide: [docs/search.md](docs/search.md).
+
+## Vector search (`@mybase-dev/sdk/vector`)
+
+Index documents and search them by meaning (pgvector), keywords (Postgres full-text search), or both (hybrid). They live in your project's own database. Turn it on (dashboard, or `mybase vector enable <project>`), use an API key with `vector:write` (`vector:read` to only search), then:
+
+```ts
+import { createVectorClient, retrievalTool } from "@mybase-dev/sdk/vector";
+
+const vector = createVectorClient({ apiUrl: "https://mybase.example.com", project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+const docs = vector.index<{ lang: string }>("docs");
+await docs.upsert([{ id: "faq-1", title: "Reset your password", text: "…", metadata: { lang: "en" } }]);
+const { matches } = await docs.query("forgot my password", { topK: 5, filter: { lang: "en" } });
+const tool = retrievalTool(docs, { about: "the help center" }); // for an LLM tool-use loop
+```
+
+Send your own vectors, or set an embedding model for the project (any OpenAI-compatible endpoint) and mybase embeds text for you. Full guide: [docs/vector.md](docs/vector.md).
+
+## Better Auth (`@mybase-dev/sdk/better-auth`)
+
+Sign your app's users in with [Better Auth](https://better-auth.com), backed by mybase. Turn on the users service (`mybase users enable <project>`) and the cache, use an API key with `users:write` and `cache:write`, then:
+
+```ts
+import { betterAuth } from "better-auth";
+import { Pool } from "pg";
+import { createCache } from "@mybase-dev/sdk/cache";
+import { authDatabaseUrl, mybaseAuth, mybaseSecondaryStorage } from "@mybase-dev/sdk/better-auth";
+
+const mybase = { apiUrl: "https://mybase.example.com", project: "shop", apiKey: process.env.MYBASE_API_KEY! };
+export const auth = betterAuth({
+  database: new Pool({ connectionString: authDatabaseUrl(process.env.DATABASE_URL!) }), // tables in the "auth" schema
+  secondaryStorage: mybaseSecondaryStorage(createCache(mybase)), // sessions in the mybase cache
+  session: { storeSessionInDatabase: true }, // so the dashboard can list and revoke them
+  emailAndPassword: { enabled: true },
+  plugins: [mybaseAuth(mybase)], // sign-ins in the audit log
+});
+```
+
+No dependency on Better Auth itself. Full guide: [docs/better-auth.md](docs/better-auth.md).
+
+## Captcha (`@mybase-dev/sdk/captcha`)
+
+Self-hosted, proof-of-work bot checks: no puzzles, cookies, or third party. Turn it on (`mybase captcha enable <project>`), solve in the browser, verify on the server with an API key that has `captcha:write`:
+
+```ts
+import { createCaptchaClient, solveCaptcha } from "@mybase-dev/sdk/captcha";
+
+const token = await solveCaptcha({ apiUrl: "https://mybase.example.com", project: "shop" }); // browser
+const { success } = await createCaptchaClient({ apiUrl, project: "shop", apiKey }).verify(token); // server
+```
+
+Or the script tag `<script defer src="https://mybase.example.com/captcha.js" data-project="shop">` on forms marked `data-mybase-captcha`. With Better Auth: `captcha(mybaseCaptcha({ …, secretKey }))`. Full guide: [docs/captcha.md](docs/captcha.md).
 
 ## Cron (`@mybase-dev/sdk/cron`)
 
@@ -101,6 +192,8 @@ Responses: `200` when the job finishes, `401` for a bad or stale signature, `404
 
 **Rotating the secret:** pass both secrets, new first, while you deploy: `secret: [process.env.MYBASE_CRON_SECRET!, process.env.MYBASE_CRON_SECRET_OLD!]`.
 
+Full guide: [docs/cron-handler.md](docs/cron-handler.md). Jobs are created on the dashboard, with `mybase cron create`, or [in code](#define-jobs-rules-and-queues-in-code).
+
 ### Lower level
 
 ```ts
@@ -113,35 +206,6 @@ const run = await verifyCronRequest(request, process.env.MYBASE_CRON_SECRET!);
 await verifyCronSignature({ body: req.body, signature: req.get("X-Mybase-Signature"), secret });
 ```
 
-### Define jobs in code
-
-Declare jobs next to your app and push them with the mybase CLI. Keep this file free of app code: the CLI imports only this file.
-
-```ts
-// mybase.config.ts
-import { defineConfig } from "@mybase-dev/sdk/config";
-
-export default defineConfig({
-  project: "shop",
-  cron: {
-    baseUrl: "https://shop.example.com", // must be reachable from the mybase server
-    jobs: {
-      cleanup: { schedule: "0 3 * * *" }, // POSTs to baseUrl + /api/cron
-      digest: { schedule: "0 8 * * 1", timezone: "America/Chicago", path: "/api/cron", payload: { kind: "weekly" } },
-    },
-  },
-});
-```
-
-```sh
-mybase cron sync --dry-run   # show what would change
-mybase cron sync             # create, update, and delete code-defined jobs to match
-```
-
-Jobs created in the dashboard are never touched by a sync. For typed job names in the handler, pass the config type: `cronHandler<typeof config>({ ... })`.
-
-Job options: `schedule` (5-field cron, minute precision), `path` (default `/api/cron`), `timezone` (IANA, default `UTC`), `payload` (JSON, up to 16 KB), `retries` (0–5, default 2), `timeoutMs` (1000–120000, default 30000).
-
 ### One-off tasks
 
 Schedule a single call to a handler from your app code, e.g. a reminder a day after an order. The task calls the same `cronHandler` as cron jobs: `run.job` is the name you pass, `run.trigger` is `"task"`, and `run.runId` is the task id.
@@ -185,7 +249,7 @@ export const POST = cronHandler({
 - Finished and cancelled tasks are kept for 7 days. A project can have 10,000 pending tasks.
 - Errors from the API throw `MybaseApiError` (with `status`); `get`/`cancel` resolve to `null` for an unknown task.
 
-The client sends an API key with `cron:write` (not an admin one) as `Authorization: Bearer`.
+The client sends an API key with `cron:write` (not an admin one) as `Authorization: Bearer`. Full guide: [docs/one-off-tasks.md](docs/one-off-tasks.md).
 
 ### Signature format
 
@@ -204,3 +268,52 @@ Reject the call if `t` is more than 5 minutes from now, then compare `v1` in con
 `X-Mybase-Job` and `X-Mybase-Run` headers carry the job name and run id too. Task calls add `"key"`, and `trigger` is `"task"`.
 
 Requests from your app to the mybase API (`createCronClient`) carry an API key as `Authorization: Bearer`. Routes: `POST /cron/<project>/tasks`, `GET|DELETE /cron/<project>/tasks/<id>`, `GET|DELETE /cron/<project>/tasks/by-key/<key>`.
+
+Full reference: [docs/signatures.md](docs/signatures.md).
+
+## Define jobs, rules, and queues in code
+
+Declare cron jobs, rate limit rules, and queues next to your app and push them with the mybase CLI. Keep this file free of app code: the CLI imports only this file.
+
+```ts
+// mybase.config.ts
+import { defineConfig } from "@mybase-dev/sdk/config";
+
+export default defineConfig({
+  project: "shop",
+  cron: {
+    baseUrl: "https://shop.example.com", // must be reachable from the mybase server
+    jobs: {
+      cleanup: { schedule: "0 3 * * *" }, // POSTs to baseUrl + /api/cron
+      digest: { schedule: "0 8 * * 1", timezone: "America/Chicago", path: "/api/cron", payload: { kind: "weekly" } },
+    },
+  },
+  ratelimit: {
+    rules: {
+      login: { limit: 5, window: "1m" },
+      api: { algorithm: "token", limit: 100, window: "1m", burst: 200 },
+    },
+  },
+  queue: {
+    queues: {
+      "emails-dlq": {},
+      emails: { visibilityTimeout: "2m", deadLetter: { queue: "emails-dlq", maxReceives: 5 } },
+    },
+  },
+});
+```
+
+```sh
+mybase cron sync --dry-run   # show what would change
+mybase cron sync             # create, update, and delete code-defined jobs to match
+mybase ratelimit sync        # same for rate limit rules
+mybase queue sync            # same for queues (asks before deleting a queue: its messages go too)
+```
+
+Each sync only touches what came from code; jobs, rules, and queues created on the dashboard are left alone. For typed job names in the handler, pass the config type: `cronHandler<typeof config>({ ... })`.
+
+- **Job options:** `schedule` (5-field cron, minute precision), `path` (default `/api/cron`), `timezone` (IANA, default `UTC`), `payload` (JSON, up to 16 KB), `retries` (0–5, default 2), `timeoutMs` (1000–120000, default 30000).
+- **Rule options:** `algorithm` (`sliding` default, `fixed`, `token`), `limit`, `window` (ms or `"10s"`, `"1m"`, `"1h"`, `"1d"`; 1s–30d), `burst` (token bucket only).
+- **Queue options:** `fifo` (fixed at creation), `visibilityTimeout` (default 30s), `delay`, `retention` (default 4d), `receiveWait`, `maxMessageBytes`, `contentDedup` (FIFO), `deadLetter` (`{ queue, maxReceives }`).
+
+Full guide: [docs/jobs-in-code.md](docs/jobs-in-code.md).

package/dist/analytics-script.d.ts

@@ -6,6 +6,9 @@ declare global {
             track?: Analytics["track"];
             pageview?: Analytics["pageview"];
             captureError?: Analytics["captureError"];
+            captcha?: {
+                solve: () => Promise<string>;
+            };
         };
     }
 }

package/dist/better-auth.d.ts

@@ -0,0 +1,123 @@
+import type { Cache } from "./cache";
+/** Better Auth's tables live in this schema of the project's database (the `users` service creates it). */
+export declare const AUTH_SCHEMA = "auth";
+/**
+ * The project's connection string with `search_path` set to the auth schema, so Better Auth's
+ * tables (and its migrations) land there instead of next to your app's tables in `public`.
+ * Pass `extra` schemas to also see them unqualified (e.g. `["public"]`).
+ */
+export declare function authDatabaseUrl(url: string, extra?: string[]): string;
+/** What Better Auth's `secondaryStorage` option takes. TTLs are in seconds. */
+export interface SecondaryStorage {
+    get(key: string): Promise<string | null>;
+    getAndDelete(key: string): Promise<string | null>;
+    increment(key: string, ttl: number): Promise<number>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Better Auth's `secondaryStorage` on the project's mybase cache (Valkey): sessions and rate
+ * limit counters stay in memory instead of hitting Postgres (and the SD card) on every request.
+ * Keys go under `<project>:auth:`, inside the project's cache ACL. Needs the cache service and an
+ * API key with `cache:write`. The dashboard's Users page revokes sessions here too.
+ */
+export declare function mybaseSecondaryStorage(cache: Cache, { prefix }?: {
+    prefix?: string;
+}): SecondaryStorage;
+export interface MybaseAuthOptions {
+    /** Where the mybase API is reachable from your app. */
+    apiUrl: string;
+    project: string;
+    /** A mybase API key with `users:write` for this project. Server-side only. */
+    apiKey: string;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Called when an event can't be sent (it's dropped, never retried). Default: console.warn. */
+    onError?: (err: unknown) => void;
+}
+/** What the app reports to mybase's audit log (`POST /users/:project/events`). */
+export type UserEventType = "user.created" | "user.deleted" | "session.created" | "session.revoked";
+export interface UserEvent {
+    type: UserEventType;
+    userId: string;
+    /** The end user's IP and user agent, as Better Auth saw them. */
+    ip?: string | null;
+    userAgent?: string | null;
+}
+interface SessionLike {
+    userId: string;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+}
+/**
+ * A Better Auth plugin that reports sign-ups, sign-ins, sign-outs, and deleted users to the
+ * project's mybase audit log, where they show up next to everything else (and on the
+ * dashboard's Users page). No passwords, emails, or tokens are sent: user ids, IPs, user agents.
+ * Sending never blocks or fails a sign-in.
+ */
+export declare function mybaseAuth(options: MybaseAuthOptions): {
+    id: "mybase";
+    init(): {
+        options: {
+            databaseHooks: {
+                user: {
+                    create: {
+                        after: (user: {
+                            id: string;
+                        }) => Promise<void>;
+                    };
+                    delete: {
+                        after: (user: {
+                            id: string;
+                        }) => Promise<void>;
+                    };
+                };
+                session: {
+                    create: {
+                        after: (session: SessionLike) => Promise<void>;
+                    };
+                    delete: {
+                        after: (session: SessionLike) => Promise<void>;
+                    };
+                };
+            };
+        };
+    };
+};
+export interface MybaseCaptchaOptions {
+    apiUrl: string;
+    project: string;
+    /** The project's captcha secret (dashboard → Captcha, or `mybase captcha key`). Server-side only. */
+    secretKey: string;
+    /** Better Auth routes that need a solved captcha. Default: sign-up, sign-in, and password reset. */
+    endpoints?: string[];
+}
+/**
+ * Options for Better Auth's `captcha()` plugin that check tokens with mybase's self-hosted
+ * captcha instead of Cloudflare's: mybase answers in Turnstile's siteverify format. Put the
+ * widget (`<script src="<mybase>/captcha.js">`) on your forms and send its token in the
+ * `x-captcha-response` header, as Better Auth expects.
+ */
+export declare function mybaseCaptcha(options: MybaseCaptchaOptions): {
+    endpoints?: string[] | undefined;
+    provider: "cloudflare-turnstile";
+    secretKey: string;
+    siteVerifyURLOverride: string;
+};
+/**
+ * The statement that tells Postgres who the signed-in user is, for row-level security policies
+ * on `mybase_auth.uid()`. Run it inside the same transaction as your queries:
+ *
+ *   await sql.begin(async (tx) => {
+ *     const q = userContextQuery(session.user.id);
+ *     await tx.unsafe(q.text, q.values);
+ *     return tx`select * from orders`; // policy: using (user_id = mybase_auth.uid())
+ *   });
+ *
+ * Policies only apply to the table owner (your app's role) with `force row level security`.
+ */
+export declare function userContextQuery(userId: string): {
+    text: string;
+    values: [string];
+};
+export {};

package/dist/better-auth.js

@@ -0,0 +1,81 @@
+// src/better-auth.ts
+var AUTH_SCHEMA = "auth";
+function authDatabaseUrl(url, extra = []) {
+  const u = new URL(url);
+  const path = [AUTH_SCHEMA, ...extra].join(",");
+  u.searchParams.set("options", `-c search_path=${path}`);
+  return u.toString();
+}
+function mybaseSecondaryStorage(cache, { prefix = "auth:" } = {}) {
+  const k = (key) => cache.key(prefix + key);
+  return {
+    get: (key) => cache.command(["GET", k(key)]),
+    getAndDelete: (key) => cache.command(["GETDEL", k(key)]),
+    async increment(key, ttl) {
+      const [, incr] = await cache.pipeline().command(["SET", k(key), 0, "EX", Math.max(1, Math.ceil(ttl)), "NX"]).command(["INCR", k(key)]).exec({ atomic: true });
+      if (!incr || "error" in incr)
+        throw new Error(`mybase cache: ${incr && "error" in incr ? incr.error : "no reply"}`);
+      return Number(incr.result);
+    },
+    async set(key, value, ttl) {
+      await cache.command(ttl && ttl > 0 ? ["SET", k(key), value, "EX", Math.ceil(ttl)] : ["SET", k(key), value]);
+    },
+    async delete(key) {
+      await cache.command(["DEL", k(key)]);
+    }
+  };
+}
+function mybaseAuth(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/users/${encodeURIComponent(options.project)}/events`;
+  const onError = options.onError ?? ((err) => console.warn("mybase: auth event not sent:", err));
+  const send = (event) => {
+    doFetch(url, {
+      method: "POST",
+      body: JSON.stringify({ events: [event] }),
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` }
+    }).then(async (res) => {
+      if (!res.ok)
+        onError(new Error(`mybase API answered ${res.status}: ${await res.text().catch(() => "")}`));
+    }).catch(onError);
+  };
+  const fromSession = (type, s) => send({ type, userId: s.userId, ip: s.ipAddress ?? null, userAgent: s.userAgent ?? null });
+  return {
+    id: "mybase",
+    init() {
+      return {
+        options: {
+          databaseHooks: {
+            user: {
+              create: { after: async (user) => send({ type: "user.created", userId: user.id }) },
+              delete: { after: async (user) => send({ type: "user.deleted", userId: user.id }) }
+            },
+            session: {
+              create: { after: async (session) => fromSession("session.created", session) },
+              delete: { after: async (session) => fromSession("session.revoked", session) }
+            }
+          }
+        }
+      };
+    }
+  };
+}
+function mybaseCaptcha(options) {
+  return {
+    provider: "cloudflare-turnstile",
+    secretKey: options.secretKey,
+    siteVerifyURLOverride: `${options.apiUrl.replace(/\/+$/, "")}/captcha/${encodeURIComponent(options.project)}/siteverify`,
+    ...options.endpoints ? { endpoints: options.endpoints } : {}
+  };
+}
+function userContextQuery(userId) {
+  return { text: "select set_config('mybase.user_id', $1, true)", values: [userId] };
+}
+export {
+  AUTH_SCHEMA,
+  authDatabaseUrl,
+  mybaseAuth,
+  mybaseCaptcha,
+  mybaseSecondaryStorage,
+  userContextQuery
+};

package/dist/captcha-widget.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/captcha.d.ts

@@ -0,0 +1,54 @@
+import { MybaseApiError } from "./cron";
+export { MybaseApiError };
+export declare const CAPTCHA_LIMITS: {
+    /** How long a challenge (and so its token) stays valid. */
+    readonly expiresMs: number;
+    /** The work: the browser tries up to this many numbers (half on average). */
+    readonly maxNumber: {
+        readonly min: 1000;
+        readonly max: 1000000;
+        readonly default: 50000;
+    };
+    readonly tokenLength: 2000;
+};
+/** `GET /captcha/:project/challenge`. `salt` carries its expiry (`…?expires=<unix seconds>`). */
+export interface CaptchaChallenge {
+    algorithm: "SHA-256";
+    challenge: string;
+    salt: string;
+    maxnumber: number;
+    signature: string;
+}
+/** What `verify` answers. `error` says why a token was refused. */
+export interface CaptchaVerifyResponse {
+    success: boolean;
+    error?: "invalid" | "expired" | "used" | "unavailable";
+}
+export declare function sha256Hex(text: string): Promise<string>;
+/** The token for a solved challenge: base64 of the challenge plus the number found. */
+export declare function encodeToken(c: CaptchaChallenge, number: number): string;
+/** Finds the number. Rejects if none up to `maxnumber` matches, or when `signal` aborts. */
+export declare function solveChallenge(c: CaptchaChallenge, { signal }?: {
+    signal?: AbortSignal;
+}): Promise<string>;
+export interface SolveOptions {
+    /** Where the mybase API is reachable from the browser. */
+    apiUrl: string;
+    project: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}
+/** Fetches a challenge and solves it. Returns the token to send with the form. */
+export declare function solveCaptcha(options: SolveOptions): Promise<string>;
+export interface CaptchaClientOptions {
+    apiUrl: string;
+    project: string;
+    /** A mybase API key with `captcha:write` for this project. Server-side only. */
+    apiKey: string;
+    fetch?: typeof fetch;
+}
+export interface CaptchaClient {
+    /** Checks a token once. A second check of the same token fails with `used`. */
+    verify(token: string): Promise<CaptchaVerifyResponse>;
+}
+export declare function createCaptchaClient(options: CaptchaClientOptions): CaptchaClient;