@dontcode2/backend 0.1.1 → 0.2.1

package/dist/index.d.cts

@@ -1,588 +0,0 @@
-interface TransportConfig {
-    /** Project API key. When absent, no Authorization header is sent and the
-     *  gateway responds with its own "Missing API key" 401. */
-    apiKey?: string;
-    /** Gateway origin, already normalized (no trailing slash). */
-    baseUrl: string;
-    /** Per-request timeout in ms. Defaults to `DEFAULT_TIMEOUT_MS`; `0` (or any
-     *  non-positive value) disables it. */
-    timeoutMs?: number;
-}
-interface RequestOptions {
-    /** End-user access token, sent as `X-Access-Token` (separate from the
-     *  project API key). Required by signed-in auth calls. */
-    accessToken?: string;
-    /** Override the client's timeout for this one call (ms). `0` disables it. */
-    timeoutMs?: number;
-}
-/**
- * The single place network requests are made. Everything else in the SDK is a
- * typed shape around `json()` / `multipart()`. No retries, no caching, just a
- * faithful proxy of the v1 gateway.
- */
-declare class Transport {
-    private readonly config;
-    constructor(config: TransportConfig);
-    private headers;
-    private url;
-    private timeout;
-    /**
-     * One fetch, with a timeout that turns "hung socket" into a fast, typed
-     * failure. A timeout surfaces as `DontCodeError` with status 408 / code
-     * `Timeout`; any other transport failure (DNS, refused, offline) as status
-     * 0 / code `NetworkError`. Both are distinct from a real `401`, so an auth
-     * guard can tell "backend is down" apart from "user is signed out".
-     */
-    private send;
-    /** POST a JSON body and parse the JSON response. */
-    json<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
-    /** PUT a multipart form (file uploads). The runtime sets the boundary. */
-    multipart<T>(path: string, form: FormData, opts?: RequestOptions): Promise<T>;
-    private parse;
-}
-
-/**
- * Wire shapes for the v1 gateway. These mirror the platform contract; they are
- * intentionally loose where the platform is (claims, tokens) and additive-only.
- */
-interface WhereOperator {
-    equals?: unknown;
-    not?: unknown;
-    gt?: unknown;
-    gte?: unknown;
-    lt?: unknown;
-    lte?: unknown;
-    in?: unknown[];
-    notIn?: unknown[];
-    contains?: string;
-    startsWith?: string;
-    endsWith?: string;
-    mode?: 'default' | 'insensitive';
-}
-interface WhereClause {
-    [key: string]: unknown;
-    AND?: WhereClause[];
-    OR?: WhereClause[];
-    NOT?: WhereClause;
-}
-type OrderByClause = Record<string, 'asc' | 'desc'>;
-/** Options accepted by read operations (`find`, `findFirst`, `count`). */
-interface QueryOptions {
-    where?: WhereClause;
-    select?: string[];
-    orderBy?: OrderByClause;
-    limit?: number;
-    offset?: number;
-}
-interface UpdateInput {
-    where: WhereClause;
-    data: Record<string, unknown>;
-}
-interface DeleteInput {
-    where: WhereClause;
-}
-interface MigrateInput {
-    sql: string;
-}
-interface MigrateResult {
-    success: boolean;
-    executedStatements?: number;
-    warnings?: string[];
-    error?: string;
-}
-interface SignupInput {
-    email: string;
-    password: string;
-    name?: string;
-    role?: string;
-}
-interface SignupResult {
-    success: boolean;
-    userId?: string;
-    verified?: boolean;
-    verification_required?: boolean;
-    message?: string;
-}
-interface LoginInput {
-    email: string;
-    password: string;
-}
-interface AuthTokens {
-    AccessToken: string;
-    ExpiresIn: number;
-}
-interface LoginResult {
-    success: boolean;
-    userId?: string;
-    mfa_offered?: boolean;
-    mfa_enabled?: boolean;
-    tokens?: AuthTokens;
-    /** When true the caller holds a challenge, NOT a session; finish via mfa.challenge. */
-    mfa_required?: boolean;
-    challenge_token?: string;
-    challenge_expires_in?: number;
-}
-interface VerifyEmailInput {
-    code: string;
-    /** Accepted but ignored; the code alone resolves the user. */
-    email?: string;
-}
-interface ForgotPasswordInput {
-    email: string;
-}
-interface ResetPasswordInput {
-    code: string;
-    password: string;
-    email?: string;
-}
-interface CurrentUser {
-    id: string;
-    email: string;
-    role?: string;
-    claims?: Record<string, unknown>;
-}
-interface MeResult {
-    user: CurrentUser | null;
-}
-interface MfaChallengeInput {
-    challengeToken: string;
-    code?: string;
-    recoveryCode?: string;
-}
-interface MfaEnrollResult {
-    success: boolean;
-    secret?: string;
-    otpauth_url?: string;
-}
-interface MfaEnrollConfirmInput {
-    accessToken: string;
-    code: string;
-}
-interface MfaDisableInput {
-    accessToken: string;
-    code?: string;
-    recoveryCode?: string;
-}
-interface SimpleResult {
-    success: boolean;
-    message?: string;
-    [key: string]: unknown;
-}
-type StorageBucket = 'public' | 'private';
-interface StorageObject {
-    key: string;
-    name: string;
-    size: number;
-    contentType: string;
-    lastModified: string;
-    isFolder: boolean;
-}
-interface ListResult {
-    objects: StorageObject[];
-    folders: string[];
-    prefix: string;
-    truncated: boolean;
-    continuationToken: string | null;
-}
-interface DownloadResult {
-    /** base64-encoded file contents (inline downloads are capped at 8 MB). */
-    body: string;
-    contentType: string;
-    size: number;
-}
-interface PresignResult {
-    url: string;
-    key: string;
-    expiresIn: number;
-}
-interface TemporaryUrlResult {
-    url: string;
-    expiresIn: number;
-}
-/** Bytes the SDK can turn into an upload body. */
-type UploadBody = Blob | ArrayBuffer | ArrayBufferView | string;
-
-/**
- * Session helpers, framework-agnostic by design. They never touch a request or
- * response object; they take a token (or a cookie header) and return plain
- * data, so they slot into any framework's guard (Next middleware, SvelteKit
- * hooks, Express, a worker) without an adapter.
- *
- * The point of the module: an auth guard must not make a network round-trip on
- * every navigation, or a slow gateway stalls the page and a swallowed timeout
- * reads as "signed out". So there are two modes:
- *
- *   - optimistic — decode the token locally (no signature check, no network)
- *     and trust its claims for routing. Instant. Used for the common gate.
- *   - verified   — call the gateway's `me` once, cache the result for a short
- *     TTL, and hard-timeout the request. Used for sensitive actions.
- *
- * The trade-offs (no signature verification, revocation lag) are documented on
- * `getSession` and in the public BYOC docs; read them before choosing a mode.
- */
-/** A JWT payload decoded WITHOUT verifying its signature. Trust accordingly. */
-interface DecodedSession {
-    /** Subject — the user id. */
-    sub: string;
-    email?: string;
-    role?: string;
-    claims?: Record<string, unknown>;
-    /** Expiry, seconds since the epoch (standard JWT `exp`). */
-    exp?: number;
-    /** Issued-at, seconds since the epoch (standard JWT `iat`). */
-    iat?: number;
-    [key: string]: unknown;
-}
-type SessionStatus = 
-/** A usable session: a present, unexpired token (verified or optimistic). */
-'active'
-/** The token is present but past its `exp`. */
- | 'expired'
-/** No token, or an unparseable one. */
- | 'anonymous'
-/** Verified mode could not reach the gateway (timeout/network/5xx). The
- *  optimistically-decoded `user` is still returned so the caller can choose
- *  to fail open during an outage instead of logging everyone out. */
- | 'unavailable';
-interface SessionResult {
-    status: SessionStatus;
-    /** The signed-in user, or `null` when anonymous/expired. In `verified` mode
-     *  this came from the gateway; in `optimistic` (or `unavailable`) it was
-     *  decoded from the token's own claims. */
-    user: CurrentUser | null;
-    /** True only when `user` was confirmed by a gateway `me` call this request
-     *  (or from a fresh cache entry of one). False for optimistic decodes. */
-    verified: boolean;
-    /** The token's `exp` (seconds since epoch), when present. */
-    expiresAt?: number;
-}
-interface GetSessionInput {
-    accessToken: string;
-    /** `optimistic` (default): decode locally, zero network. `verified`: confirm
-     *  against the gateway with caching + a hard timeout. */
-    mode?: 'optimistic' | 'verified';
-}
-/** A place to cache verified sessions. Swap the default in-memory store for a
- *  shared one (Redis, KV) when running multiple instances. */
-interface SessionCache {
-    get(token: string): SessionResult | undefined;
-    set(token: string, value: SessionResult, ttlMs: number): void;
-    delete?(token: string): void;
-}
-interface SessionOptions {
-    /** Cache for verified sessions. Defaults to a per-process `InMemorySessionCache`. */
-    cache?: SessionCache;
-    /** How long a verified session stays cached. Default 60_000 (60s). Keep it
-     *  short: a cached session can outlive a server-side revocation by up to
-     *  this long. */
-    ttlMs?: number;
-    /** Timeout for the `me` call made by `verified` mode (ms). Default 5_000. */
-    verifyTimeoutMs?: number;
-}
-/** Default cache: a `Map` with per-entry TTL. Lives for the life of the process
- *  (and is shared across requests on a reused serverless instance). */
-declare class InMemorySessionCache implements SessionCache {
-    private readonly store;
-    get(token: string): SessionResult | undefined;
-    set(token: string, value: SessionResult, ttlMs: number): void;
-    delete(token: string): void;
-}
-/**
- * Decode a JWT access token's payload WITHOUT verifying its signature, or
- * return `null` if it is not a parseable JWT. This is deliberately cheap and
- * offline; it is not proof the token is genuine. DontCode tokens are signed
- * with a secret the gateway never shares, so the only authority on a token is
- * the gateway's `me` endpoint — use `getSession({ mode: 'verified' })` when you
- * need that authority.
- */
-declare function decodeAccessToken(token: string): DecodedSession | null;
-/** True when a token (or already-decoded payload) is past its `exp`. A token
- *  with no `exp` is treated as not expired (the caller cannot prove otherwise
- *  offline). `skewSeconds` widens the window to absorb clock drift. */
-declare function isSessionExpired(input: string | DecodedSession | null, opts?: {
-    skewSeconds?: number;
-}): 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.
- */
-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.
- */
-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>;
-    /** 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>;
-}
-
-/**
- * A handle to one table. Structured queries only; there is no raw-SQL escape
- * hatch (schema changes go through `db.migrate`). `update` and `delete`
- * require a `where` clause server-side, so the types make it mandatory.
- */
-declare class TableQuery {
-    private readonly transport;
-    private readonly tableName;
-    constructor(transport: Transport, tableName: string);
-    private run;
-    /** Rows matching the query (max 1000 per call). */
-    find<T = Record<string, unknown>>(options?: QueryOptions): Promise<T[]>;
-    /** Alias of `find`. */
-    findMany<T = Record<string, unknown>>(options?: QueryOptions): Promise<T[]>;
-    /** The first matching row, or `null`. */
-    findFirst<T = Record<string, unknown>>(options?: QueryOptions): Promise<T | null>;
-    /** Alias of `findFirst`. */
-    findOne<T = Record<string, unknown>>(options?: QueryOptions): Promise<T | null>;
-    /** Insert one row. Returns `{ id }`. Unique/FK conflicts throw a 409
-     *  DontCodeError, the supported idempotency signal. */
-    insert(data: Record<string, unknown>): Promise<{
-        id: unknown;
-    }>;
-    /** Update rows matching `where`. Returns `{ count }`. */
-    update(input: UpdateInput): Promise<{
-        count: number;
-    }>;
-    /** Delete rows matching `where`. Returns `{ count }`. */
-    delete(input: DeleteInput): Promise<{
-        count: number;
-    }>;
-    /** Count matching rows. */
-    count(options?: Pick<QueryOptions, 'where'>): Promise<number>;
-}
-/**
- * `db.users.find()` and `db('users').find()` both work; the bracket/callable
- * form is there for table names that aren't valid identifiers. `db.migrate()`
- * applies schema DDL (the one place migrations enter from outside).
- */
-type DbClient = {
-    readonly [tableName: string]: TableQuery;
-} & {
-    (tableName: string): TableQuery;
-    migrate(input: MigrateInput): Promise<MigrateResult>;
-};
-
-/** Operations available on both buckets. */
-declare class BucketClient {
-    protected readonly transport: Transport;
-    protected readonly bucket: StorageBucket;
-    constructor(transport: Transport, bucket: StorageBucket);
-    protected op<T>(operation: string, params?: Record<string, unknown>): Promise<T>;
-    /** List objects under `prefix`. */
-    list(prefix?: string): Promise<ListResult>;
-    /** Delete one or more objects. Returns `{ deleted }`. */
-    remove(paths: string[]): Promise<{
-        deleted: number;
-    }>;
-    /** Move/rename an object within the bucket. */
-    move(from: string, to: string): Promise<{
-        object: StorageObject;
-    }>;
-    createFolder(path: string): Promise<{
-        created: string;
-    }>;
-    /** Download an object inline (≤ 8 MB). Use `getTemporaryUrl` for larger files. */
-    download(path: string): Promise<DownloadResult>;
-    /** A short-lived signed URL (default 300s, max 7 days). */
-    getTemporaryUrl(path: string, expiresIn?: number): Promise<TemporaryUrlResult>;
-    /** A presigned PUT URL for direct, large uploads (≤ no inline limit). */
-    presignUpload(path: string, contentType?: string): Promise<PresignResult>;
-    /** Upload bytes directly (≤ 100 MB). For larger files, `presignUpload`
-     *  then PUT to the returned URL yourself. */
-    upload(path: string, body: UploadBody, contentType?: string): Promise<{
-        object: StorageObject;
-    }>;
-}
-/** The public bucket additionally exposes stable public URLs. */
-declare class PublicBucketClient extends BucketClient {
-    constructor(transport: Transport);
-    /** The permanent public URL for an object. */
-    getUrl(path: string): Promise<{
-        url: string;
-    }>;
-}
-interface StorageClient {
-    public: PublicBucketClient;
-    private: BucketClient;
-}
-declare function createStorage(transport: Transport): StorageClient;
-
-interface DontCodeClientOptions {
-    /** Project API key (`dc_…`). Defaults to `process.env.DONTCODE_API_KEY`.
-     *  If neither is set, requests fail naturally with the gateway's
-     *  "Missing API key" 401. */
-    apiKey?: string;
-    /** Gateway origin. Defaults to `process.env.DONTCODE_API_URL`, then to
-     *  `https://backend.dontcode.co`. */
-    baseUrl?: string;
-    /** Per-request network timeout in ms. Defaults to 10_000; `0` disables it.
-     *  Without one, a slow gateway can hang a request for the full socket
-     *  timeout, the worst case for an auth guard. */
-    timeoutMs?: number;
-    /** Caching + timeout policy for `auth.getSession` / `auth.sessionFromCookies`. */
-    session?: SessionOptions;
-}
-interface DontCodeClient {
-    auth: AuthApi;
-    db: DbClient;
-    storage: StorageClient;
-}
-/**
- * Create a DontCode backend client. A thin, typed proxy over the v1 HTTP
- * gateway: auth, database, and storage. The API key scopes every request to
- * a single project; there is nothing else to configure.
- *
- * ```ts
- * import { dontcode } from '@dontcode2/backend'
- * const client = dontcode() // reads DONTCODE_API_KEY
- * await client.auth.signup({ email, password, role: 'editor' })
- * ```
- */
-declare function dontcode(options?: DontCodeClientOptions): DontCodeClient;
-
-/**
- * Every non-2xx response from the gateway surfaces as a DontCodeError. The
- * platform's error envelope is `{ error, ... }`, sometimes with a machine
- * `code` (e.g. `EmailNotVerified`, `ChallengeExpired`, `MfaNotOffered`) or
- * rate-limit fields. We preserve the whole body so callers can branch on it.
- *
- * Note: many "one more step" auth states (signup needing email verification,
- * login returning `mfa_required`) are 2xx successes, NOT errors; inspect the
- * resolved value for those. Errors are reserved for actual failures.
- *
- * Transport failures (no HTTP response at all) also surface as a DontCodeError
- * so callers have one error type: a timeout is status 408 / code `Timeout`, and
- * any other network failure is status 0 / code `NetworkError`. Neither is a
- * `401`, so a guard can distinguish "backend unavailable" from "signed out".
- */
-interface DontCodeErrorBody {
-    error?: string;
-    /** Stable machine code, when the platform sends one. */
-    code?: string;
-    /** Present on 429 responses. */
-    rate_limit?: boolean;
-    /** Seconds until the rate limit resets, on 429 responses. */
-    timeleft?: number;
-    [key: string]: unknown;
-}
-declare class DontCodeError extends Error {
-    /** HTTP status code of the failing response. */
-    readonly status: number;
-    /** Stable machine code, when present (e.g. `EmailNotVerified`). */
-    readonly code?: string;
-    /** The raw parsed response body. */
-    readonly body: DontCodeErrorBody;
-    constructor(status: number, body: DontCodeErrorBody);
-    /** True when the request was rejected by the per-key rate limiter. */
-    get rateLimited(): boolean;
-}
-/** Cross-bundle-safe check; works even if two copies of the SDK are loaded. */
-declare function isDontCodeError(err: unknown): err is DontCodeError;
-
-/**
- * Cookie helpers, framework-agnostic by design. They return strings: a
- * `Set-Cookie` header value to write, or a parsed token to read. Your framework
- * applies them (`headers.append('Set-Cookie', …)`, SvelteKit `cookies.set`, a
- * Next `Response` cookie, etc.). The SDK never owns a request or response.
- *
- * Defaults match how DontCode's own apps store the session: an httpOnly cookie
- * so JavaScript can't read the token, `Secure`, `SameSite=Lax`, path `/`, and a
- * 7-day max age. Cross-site setups (your app and the gateway on different sites)
- * need `sameSite: 'none'`, which forces `Secure` on.
- */
-/** Default cookie name for the end-user access token. */
-declare const DEFAULT_SESSION_COOKIE_NAME = "dc_access_token";
-interface SessionCookieOptions {
-    /** Cookie name. Default `dc_access_token`. */
-    name?: string;
-    /** Lifetime in seconds. Default one week. Pass the token's `ExpiresIn` to
-     *  keep the cookie and the token in lockstep. */
-    maxAge?: number;
-    /** Default `/`. */
-    path?: string;
-    domain?: string;
-    /** Default `true`. */
-    secure?: boolean;
-    /** Default `true`. Keep the token unreadable from client JavaScript. */
-    httpOnly?: boolean;
-    /** Default `'lax'`. Use `'none'` for cross-site (it forces `Secure`). */
-    sameSite?: 'lax' | 'strict' | 'none';
-}
-/** Build a `Set-Cookie` value that stores the access token. */
-declare function serializeSessionCookie(token: string, options?: SessionCookieOptions): string;
-/** Build a `Set-Cookie` value that clears the access token (logout). */
-declare function clearSessionCookie(options?: SessionCookieOptions): string;
-/** Read the access token out of a `Cookie` request header, or `null`. Pass the
- *  raw header string (`name=value; name2=value2`). */
-declare function readSessionToken(cookieHeader: string | null | undefined, name?: string): string | null;
-
-export { AuthApi, type AuthTokens, BucketClient, type CurrentUser, DEFAULT_SESSION_COOKIE_NAME, type DbClient, type DecodedSession, type DeleteInput, type DontCodeClient, type DontCodeClientOptions, DontCodeError, type DontCodeErrorBody, type DownloadResult, type ForgotPasswordInput, type GetSessionInput, InMemorySessionCache, type ListResult, type LoginInput, type LoginResult, type MeResult, MfaApi, type MfaChallengeInput, type MfaDisableInput, type MfaEnrollConfirmInput, type MfaEnrollResult, type MigrateInput, type MigrateResult, type OrderByClause, type PresignResult, PublicBucketClient, type QueryOptions, type ResetPasswordInput, type SessionCache, type SessionCookieOptions, type SessionOptions, type SessionResult, type SessionStatus, type SignupInput, type SignupResult, type SimpleResult, type StorageBucket, type StorageClient, type StorageObject, TableQuery, type TemporaryUrlResult, type UpdateInput, type UploadBody, type VerifyEmailInput, type WhereClause, type WhereOperator, clearSessionCookie, createStorage, decodeAccessToken, dontcode, isDontCodeError, isSessionExpired, readSessionToken, serializeSessionCookie };