@dontcode2/backend 0.1.1 → 0.2.1

package/README.md

@@ -45,6 +45,100 @@ const client = dontcode({
 If no key is set in either place, requests fail naturally with the gateway's
 `401 Missing API key`.
 
+## Local development (the mock gateway)
+
+You don't need the hosted backend to build against this SDK. Because the SDK is a
+thin proxy over a fixed wire protocol, the package ships a local server that speaks
+that same protocol — auth, database, and storage — so you can develop fully offline:
+
+```bash
+npx dontcode-mock                 # http://localhost:4000, state persisted to ./.dontcode-mock
+```
+
+Then point your app at it — no code changes, just config:
+
+```bash
+DONTCODE_API_URL=http://localhost:4000
+DONTCODE_API_KEY=dc_local_dev     # any dc_… value is accepted by default
+```
+
+Apply your schema the same way you would in production, then use the client normally:
+
+```ts
+const client = dontcode() // reads the env vars above
+await client.db.migrate({ sql: 'CREATE TABLE IF NOT EXISTS notes (id serial primary key, body text);' })
+await client.db.notes.insert({ body: 'hello from the mock' })
+```
+
+How faithful is it? The database runs your real DDL and the SDK's real structured
+queries against in-process Postgres ([PGlite](https://pglite.dev)), including the
+`409` conflict signal; auth issues real JWT-shaped tokens that `decodeAccessToken`
+and `getSession` read exactly as in production; storage stores real files and serves
+them over the same server. It is a **development tool** — passwords are stored in
+plaintext, tokens are unsigned, and there is no rate limiting — so never expose it
+to an untrusted network.
+
+PGlite ships as an optional dependency, so `npx dontcode-mock` works out of the box.
+(If your install skipped optional deps, add it: `pnpm add -D @electric-sql/pglite`.)
+
+**Useful flags:** `--port <n>`, `--data-dir <dir>`, `--ephemeral` (in-memory, starts
+empty each run — ideal for tests), `--api-key <key>` (require exactly that key).
+Run `dontcode-mock --help` for the full list.
+
+You can also drive it programmatically — handy for integration tests that need a
+clean backend per run:
+
+```ts
+import { startMockServer } from '@dontcode2/backend/mock'
+import { dontcode } from '@dontcode2/backend'
+
+const mock = await startMockServer({ dataDir: null }) // ephemeral
+const client = dontcode({ baseUrl: mock.url, apiKey: 'dc_test' })
+// … exercise the client …
+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

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>;
+}