@dontcode2/backend 0.2.0 → 0.2.2

package/README.md

@@ -1,8 +1,9 @@
 # @dontcode2/backend
 
 The public SDK for the [DontCode](https://www.dontcode.co) backend: a thin, typed
-proxy over the v1 HTTP gateway. Auth, database, and file storage for an app you host
-yourself ("bring your own code"), behind a single project API key.
+proxy over the v1 HTTP gateway. Auth, database, file storage, a key-value cache, and
+realtime pub/sub for an app you host yourself ("bring your own code"), behind a single
+project API key.
 
 It speaks the exact wire protocol of the gateway, so you can move between the SDK and
 raw HTTP at any time without platform-side changes.
@@ -98,6 +99,47 @@ const client = dontcode({ baseUrl: mock.url, apiKey: 'dc_test' })
 await mock.close()
 ```
 
+## MCP server (Claude Code and other AI tools)
+
+This package ships an MCP server so an AI agent can work on a DontCode project
+directly: sign in from the terminal, query and update the database, run
+migrations, and manage files. It runs over stdio, so the tool launches it for
+you.
+
+```jsonc
+// .mcp.json (Claude Code)
+{
+  "mcpServers": {
+    "dontcode": {
+      "command": "npx",
+      "args": ["-y", "-p", "@dontcode2/backend", "dontcode", "mcp"]
+    }
+  }
+}
+```
+
+On first use the agent calls the `auth_login` tool, which opens your browser.
+You confirm a short code, pick a project, and approve; the browser hands a
+short-lived, project-scoped token back to the terminal (cached under
+`~/.dontcode`). The token is bound to your user, and the gateway enforces your
+project role on every request, so the agent can never do more than you can.
+
+CLI equivalents:
+
+```bash
+npx -p @dontcode2/backend dontcode login    # browser sign-in
+npx -p @dontcode2/backend dontcode status   # project + role + capabilities
+npx -p @dontcode2/backend dontcode logout   # forget the cached token
+```
+
+For non-interactive use (CI), set `DONTCODE_API_KEY` to a `dc_` project key and
+skip `login`. Set `DONTCODE_API_URL` to target a non-default gateway.
+
+Tools: `auth_login`, `auth_wait`, `auth_status`, `auth_logout`, `db_query`,
+`db_insert`, `db_update`, `db_delete`, `db_migrate`, `storage_list`,
+`storage_get_url`, `storage_temporary_url`, `storage_upload`, `storage_remove`,
+`storage_move`. Writes and deletes are annotated so the agent confirms first.
+
 ## Auth
 
 The API key (`Authorization: Bearer dc_…`) identifies your **project** and is sent on
@@ -187,6 +229,61 @@ await priv.move('a.pdf', 'archive/a.pdf')
 const { url: putUrl } = await priv.presignUpload('big.zip', 'application/zip')
 ```
 
+## Cache
+
+A key-value cache for ephemeral, high-churn, or session-scoped state, with optional TTL
+expiry. Keys are scoped to your project automatically. This is a cache, not a database:
+values may be evicted and are not durable, so keep your system of record in `db`.
+
+```ts
+const c = client.cache
+
+await c.set('session:42', { step: 2 }, { ttl: 3600 }) // ttl in seconds
+const session = await c.get<{ step: number }>('session:42') // null on miss or expiry
+await c.set('lock:job', '1', { nx: true }) // false if it already existed
+await c.expire('session:42', 600) // or null to clear the TTL
+await c.del('session:42')
+
+// hashes
+await c.hset('profile:9', { name: 'Zed', level: 7 })
+const profile = await c.hgetAll<{ name: string; level: number }>('profile:9') // null on miss
+
+// sets (string members)
+await c.sAdd('online', 'u1', 'u2')
+const online = await c.sMembers('online') // string[] ([] on miss)
+await c.sRem('online', 'u1')
+```
+
+A miss (or expiry) reads back as `null` for `get`/`hgetAll` and `[]` for `sMembers`,
+not an error.
+
+## Realtime
+
+Realtime pub/sub over WebSockets for live features (chat, presence, live updates). The
+SDK is the **server side**: mint a connection token for a browser, publish messages, and
+read presence. The browser opens the socket itself with the scoped token, so it never
+holds your API key. Delivery is fire-and-forget (no history/replay), so persist anything
+that needs durability to `db`.
+
+```ts
+const rt = client.realtime
+
+// In your token endpoint, after you've authenticated the user:
+const conn = await rt.mintToken({ channels: [`room:${id}`], identity: userId })
+// → send `conn` to the browser; it connects to `${conn.url}?token=${conn.token}`
+//   (use @dontcode/realtime's client `connect()` to handle the socket + reconnect)
+
+// From anywhere on your backend:
+const delivered = await rt.publish(`room:${id}`, { text: 'hello' })
+const members = await rt.presence(`room:${id}`) // [{ id, identity? }]
+```
+
+A browser connection may only use the channels named when its token was minted.
+
+> The local mock gateway (`dontcode-mock`) and the MCP server currently cover auth,
+> database, and storage. Cache and realtime are available on the hosted gateway; point
+> `DONTCODE_API_URL` at it to use them.
+
 ## Errors
 
 Every non-2xx response throws a `DontCodeError`:

package/dist/auth-device.d.ts

@@ -0,0 +1,43 @@
+import { type StoredCredential } from './credentials';
+export interface DeviceStartResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    interval: number;
+    expires_in: number;
+}
+export interface DeviceTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    project_id: string;
+}
+export declare function startDeviceAuth(baseUrl: string, clientName?: string): Promise<DeviceStartResponse>;
+export interface PollOptions {
+    onPending?: () => void;
+    /** Stop polling after this many ms (throws code `WaitTimeout`), so a caller
+     *  like an MCP tool can poll in bounded slices instead of blocking for the
+     *  full 10-minute window. Defaults to the request's own expiry. */
+    maxWaitMs?: number;
+}
+/**
+ * Poll until the request is approved (token), denied/expired (throws), or the
+ * wait budget closes (throws 408). Honors the server's interval and `slow_down`.
+ */
+export declare function pollDeviceToken(baseUrl: string, start: DeviceStartResponse, opts?: PollOptions): Promise<DeviceTokenResponse>;
+/** Best-effort: open the verification URL in the user's browser. */
+export declare function openBrowser(url: string): Promise<void>;
+export interface LoginOptions {
+    baseUrl: string;
+    clientName?: string;
+    /** Open the browser automatically. Default true. */
+    open?: boolean;
+    /** Where human-facing prompts go. Default: no-op. */
+    log?: (message: string) => void;
+}
+/**
+ * Run the full device flow and cache the resulting credential. Returns the
+ * stored credential (token, project, expiry).
+ */
+export declare function login(options: LoginOptions): Promise<StoredCredential>;

package/dist/auth.d.ts

@@ -0,0 +1,102 @@
+import { Transport } from './http';
+import { type DecodedSession, type GetSessionInput, type SessionOptions, type SessionResult } from './session';
+import type { ForgotPasswordInput, LoginInput, LoginResult, MeResult, MfaChallengeInput, MfaDisableInput, MfaEnrollConfirmInput, MfaEnrollResult, ResetPasswordInput, SignupInput, SignupResult, SimpleResult, VerifyEmailInput } from './types';
+/** Shape of `GET /api/v1/info`: validates the credential and reports what it
+ *  can do. For device tokens, capabilities follow the signed-in user's role. */
+export interface InfoResult {
+    project: {
+        id: string;
+        name: string | null;
+    };
+    credential: {
+        type: 'api_key' | 'device';
+        role: string | null;
+        user_id: string | null;
+    };
+    capabilities: Record<string, boolean>;
+}
+/**
+ * MFA is per-user and opt-in. `enroll`/`enrollConfirm`/`disable` act as the
+ * signed-in user, so they need the end-user access token. `challenge` does
+ * not; it completes a login that returned `mfa_required`, exchanging the
+ * short-lived challenge token for real session tokens.
+ */
+export declare class MfaApi {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Complete an MFA login. Pass the `challenge_token` from `login`, plus
+     *  either the authenticator `code` or a `recoveryCode`. */
+    challenge(input: MfaChallengeInput): Promise<LoginResult>;
+    /** Begin enrollment. Render the returned `otpauth_url` as a QR code.
+     *  Enrollment stays pending until `enrollConfirm`. */
+    enroll(input: {
+        accessToken: string;
+    }): Promise<MfaEnrollResult>;
+    /** Confirm enrollment with the first authenticator code. The returned
+     *  `recovery_codes` are shown once and never again. */
+    enrollConfirm(input: MfaEnrollConfirmInput): Promise<SimpleResult>;
+    /** Turn MFA off. Proves possession of the second factor via `code` or
+     *  `recoveryCode`. */
+    disable(input: MfaDisableInput): Promise<SimpleResult>;
+}
+/**
+ * Fronts DontCode Auth with the same shapes as the gateway. Two behaviours are
+ * project settings (not API flags) and your code must handle both states:
+ * email verification (signup may not return tokens) and MFA (login may be two
+ * steps). Branch on the resolved value; never assume one round-trip.
+ */
+export declare class AuthApi {
+    private readonly transport;
+    readonly mfa: MfaApi;
+    private readonly sessions;
+    constructor(transport: Transport, sessionOptions?: SessionOptions);
+    /** Create an account. If the project requires email verification the
+     *  response has `verification_required: true` and NO tokens; collect a
+     *  code and call `verifyEmail`, then `login`. */
+    signup(input: SignupInput): Promise<SignupResult>;
+    /** Authenticate. Branch on `mfa_required`: when true you hold only a
+     *  challenge (finish via `mfa.challenge`); otherwise `tokens` is your
+     *  session. A 403 `EmailNotVerified` means the email step isn't done. */
+    login(input: LoginInput): Promise<LoginResult>;
+    /** Validate the current credential (API key or device token) and report the
+     *  project, the caller's role, and which capabilities that role grants.
+     *  Backs the MCP "is my session still good" check. */
+    info(): Promise<InfoResult>;
+    /** Resolve the signed-in user from their access token, or `{ user: null }`.
+     *  This is a network round-trip; for a per-navigation guard prefer
+     *  `getSession`, which can answer offline and caches verified results. */
+    me(input: {
+        accessToken: string;
+        timeoutMs?: number;
+    }): Promise<MeResult>;
+    /**
+     * Resolve an access token into a session for a route guard, the one call
+     * that replaces "hit `me` on every navigation". Two modes:
+     *
+     *   - `'optimistic'` (default): decode the token locally and trust its
+     *     claims. Zero network, zero stall. The right default for gating page
+     *     loads. It does NOT verify the signature and will not notice a
+     *     server-side revocation until the token's own `exp`.
+     *   - `'verified'`: confirm against the gateway's `me`, cached for a short
+     *     TTL with a hard timeout. Use it before sensitive actions. On a
+     *     timeout/outage it returns `status: 'unavailable'` with the optimistic
+     *     user, so you choose whether to fail open rather than the SDK guessing.
+     *
+     * See the BYOC docs ("Sessions") for the full reasoning and best practices.
+     */
+    getSession(input: GetSessionInput): Promise<SessionResult>;
+    /** Read the access token from a `Cookie` request header and resolve it, in
+     *  one call. `name` defaults to `dc_access_token`. Returns the anonymous
+     *  session when no cookie is present. */
+    sessionFromCookies(cookieHeader: string | null | undefined, options?: {
+        mode?: GetSessionInput['mode'];
+        cookieName?: string;
+    }): Promise<SessionResult>;
+    /** Decode an access token's claims locally without a network call or any
+     *  signature check. Convenience re-export of `decodeAccessToken`. */
+    decodeToken(token: string): DecodedSession | null;
+    /** Confirm the 6-digit code emailed at signup. */
+    verifyEmail(input: VerifyEmailInput): Promise<SimpleResult>;
+    forgotPassword(input: ForgotPasswordInput): Promise<SimpleResult>;
+    resetPassword(input: ResetPasswordInput): Promise<SimpleResult>;
+}

package/dist/cache.d.ts

@@ -0,0 +1,36 @@
+import { Transport } from './http';
+import type { CacheSetOptions } from './types';
+/**
+ * Key-value cache: a typed proxy over `/api/v1/cache`. Keys are namespaced to
+ * your project by the gateway; values are JSON. This is ephemeral storage —
+ * use `db` for anything that must be durable.
+ *
+ * ```ts
+ * await client.cache.set('session:42', { step: 2 }, { ttl: 3600 })
+ * const s = await client.cache.get<{ step: number }>('session:42') // null if expired
+ * ```
+ */
+export declare class CacheClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Read a value. Returns `null` on a miss or expiry. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Set a value, optionally with a TTL (seconds) or set-if-absent (`nx`).
+     *  Returns `false` when `nx` is set and the key already existed. */
+    set(key: string, value: unknown, options?: CacheSetOptions): Promise<boolean>;
+    /** Delete a key. Returns whether it existed. */
+    del(key: string): Promise<boolean>;
+    /** Set or clear (`null`) the TTL on an existing key. Returns `false` if absent. */
+    expire(key: string, ttl: number | null): Promise<boolean>;
+    /** Set fields on a hash. Returns the number of fields written. */
+    hset(key: string, fields: Record<string, unknown>): Promise<number>;
+    /** Read a whole hash. Returns `null` on a miss. */
+    hgetAll<T = Record<string, unknown>>(key: string): Promise<T | null>;
+    /** Add members to a set. Returns the number newly added. */
+    sAdd(key: string, ...members: string[]): Promise<number>;
+    /** List set members. Returns `[]` on a miss. */
+    sMembers(key: string): Promise<string[]>;
+    /** Remove members from a set. Returns the number removed. */
+    sRem(key: string, ...members: string[]): Promise<number>;
+}
+export declare function createCache(transport: Transport): CacheClient;