@dontcode2/backend 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,395 @@
+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;
+}
+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;
+}
+/**
+ * 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;
+    /** 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;
+
+/**
+ * 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;
+    constructor(transport: Transport);
+    /** 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 }`. */
+    me(input: {
+        accessToken: string;
+    }): Promise<MeResult>;
+    /** 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;
+}
+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.
+ */
+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;
+
+export { AuthApi, type AuthTokens, BucketClient, type CurrentUser, type DbClient, type DeleteInput, type DontCodeClient, type DontCodeClientOptions, DontCodeError, type DontCodeErrorBody, type DownloadResult, type ForgotPasswordInput, 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 SignupInput, type SignupResult, type SimpleResult, type StorageBucket, type StorageClient, type StorageObject, TableQuery, type TemporaryUrlResult, type UpdateInput, type UploadBody, type VerifyEmailInput, type WhereClause, type WhereOperator, createStorage, dontcode, isDontCodeError };