backd-js 0.1.15 → 0.2.0

package/types/auth.d.ts

@@ -0,0 +1,281 @@
+export type Client = import('./client.js').Client;
+export type RequestOptions = import('./client.js').RequestOptions;
+export type User = {
+    id: string;
+    email: string;
+    email_verified: boolean;
+    roles: string[];
+    /**
+     * The user's language, one the realm lists (used for their emails).
+     */
+    locale: string;
+    /**
+     * RFC3339 timestamp.
+     */
+    created_at: string;
+};
+export type Session = {
+    /**
+     * Session token (`bds_…`); already stored by the client.
+     */
+    token: string;
+    token_type: 'Bearer';
+    session_id: string;
+    /**
+     * RFC3339; pushed forward as the session is used.
+     */
+    expires_at: string;
+    user: User;
+};
+export type SessionInfo = {
+    id: string;
+    created_at: string;
+    last_used_at: string;
+    expires_at: string;
+    /**
+     * The session making this request.
+     */
+    current: boolean;
+};
+export type AuthEvent = 'SIGNED_IN' | 'SIGNED_OUT' | 'SESSION_EXPIRED';
+export type AuthListener = (event: AuthEvent, session: Session | null) => void;
+/** Sign-up, login and session management: `client.auth`. */
+export declare class Auth {
+    /** @internal */
+    client: import("./client.js").Client;
+    /** @internal */
+    listeners: Set<any>;
+    /** @param {Client} client */
+    constructor(client: Client);
+    /**
+     * Creates an account and signs in. Realms with `signup: invite` need an
+     * invitation token. `locale` (such as `es` or `es-MX`) is the language to
+     * use for the user; the server maps it silently to one the realm lists. A
+     * browser also sends its `Accept-Language`, which is used when no `locale`
+     * is given. `redirectTo` is where the page after the verification link may
+     * send the user (it must be within the realm's `email.allowed_redirects`).
+     *
+     * A realm that requires verified addresses (`account.require_verified_email`)
+     * creates the account but starts no session: this rejects with a
+     * {@link VerificationRequiredError}, nothing is stored, and the user signs
+     * in after following the link in the email they were sent.
+     * @param {{ email: string, password: string, invitation?: string, locale?: string, redirectTo?: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<Session>}
+     */
+    signup({ email, password, invitation, locale, redirectTo }: {
+        email: string;
+        password: string;
+        invitation?: string;
+        locale?: string;
+        redirectTo?: string;
+    }, opts?: RequestOptions): Promise<Session>;
+    /**
+     * Signs in with email and password.
+     * @param {{ email: string, password: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<Session>}
+     */
+    login({ email, password }: {
+        email: string;
+        password: string;
+    }, opts?: RequestOptions): Promise<Session>;
+    /**
+     * Asks for the verification email again. Always resolves, whatever the
+     * address is (unknown, disabled, already verified), so it can't be used to
+     * find out who is registered. `redirectTo` is where the page after the link
+     * may send the user (within the realm's `email.allowed_redirects`).
+     * @param {{ email: string, redirectTo?: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    resendVerification({ email, redirectTo }: {
+        email: string;
+        redirectTo?: string;
+    }, opts?: RequestOptions): Promise<void>;
+    /**
+     * Verifies an address with the token of the link in the email: for apps
+     * that host their own page (`email.links` in `realm.yaml`). Starts no
+     * session. An expired, used or unknown token rejects with a
+     * `ValidationError` whose `code` is `invalid_token`.
+     * @param {string} token
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    verifyEmail(token: string, opts?: RequestOptions): Promise<void>;
+    /**
+     * Asks for a password reset email. Always resolves, whatever the address is.
+     * Rejects with a `RetryableError` once the realm's limits for reset
+     * requests (per address and per client) are reached.
+     * @param {{ email: string, redirectTo?: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    requestPasswordReset({ email, redirectTo }: {
+        email: string;
+        redirectTo?: string;
+    }, opts?: RequestOptions): Promise<void>;
+    /**
+     * Sets a new password with the token of a reset link. Ends every session of
+     * the user, verifies their address and starts no session: log in afterwards.
+     * A password the policy refuses rejects with a `ValidationError` and leaves
+     * the token usable; a bad token has the `invalid_token` code.
+     * @param {{ token: string, password: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    resetPassword({ token, password }: {
+        token: string;
+        password: string;
+    }, opts?: RequestOptions): Promise<void>;
+    /**
+     * Asks to change the signed-in user's email address (realms with
+     * `account.allow_email_change`). Needs the current password. Resolves
+     * whether or not the new address is free; nothing changes until the link
+     * sent to the new address is used (see {@link Auth#confirmEmailChange}).
+     * @param {{ newEmail: string, password: string, redirectTo?: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    requestEmailChange({ newEmail, password, redirectTo }: {
+        newEmail: string;
+        password: string;
+        redirectTo?: string;
+    }, opts?: RequestOptions): Promise<void>;
+    /**
+     * Confirms an email change with the token sent to the new address: the
+     * address changes and every session of the user ends.
+     * @param {string} token
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    confirmEmailChange(token: string, opts?: RequestOptions): Promise<void>;
+    /**
+     * Undoes an email change with the token sent to the old address: restores
+     * it, ends every session and makes the password unusable until it is reset
+     * (a reset email is sent to the restored address).
+     * @param {string} token
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    revertEmailChange(token: string, opts?: RequestOptions): Promise<void>;
+    /**
+     * Accepts an invitation that was emailed (admin `invitations.send`), with
+     * the token of its link: creates the account for the invited address,
+     * already verified, and starts no session. `locale` is the user's language.
+     * @param {{ token: string, password: string, locale?: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    acceptInvitation({ token, password, locale }: {
+        token: string;
+        password: string;
+        locale?: string;
+    }, opts?: RequestOptions): Promise<void>;
+    /**
+     * A call that needs no session and answers with no body.
+     * @internal
+     * @param {string[]} path
+     * @param {Record<string, unknown>} body
+     * @param {RequestOptions} [opts]
+     */
+    accepted(path: string[], body: Record<string, unknown>, opts?: RequestOptions): Promise<void>;
+    /**
+     * Ends the current session. The stored token is removed even if the
+     * server can't be reached.
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    logout(opts?: RequestOptions): Promise<void>;
+    /**
+     * Ends every session of the user, on every device.
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    logoutAll(opts?: RequestOptions): Promise<void>;
+    /**
+     * The signed-in user.
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<User>}
+     */
+    me(opts?: RequestOptions): Promise<User>;
+    /**
+     * Changes the signed-in user's own settings: today their language, which
+     * must be one the realm lists (case is ignored). Anything else is a
+     * `ValidationError` with code `invalid_locale` and the allowed languages in
+     * `details`.
+     * @param {{ locale?: string }} changes
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<User>}
+     */
+    updateMe(changes: {
+        locale?: string;
+    }, opts?: RequestOptions): Promise<User>;
+    /**
+     * Deletes the signed-in user's account: it is **deactivated** (disabled, its
+     * sessions end) and all data is kept. Erasing a user's data is an
+     * administrator's action (`admin.users.delete`).
+     * @param {{ password: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    deleteAccount({ password }: {
+        password: string;
+    }, opts?: RequestOptions): Promise<void>;
+    /**
+     * Changes the password. This session stays valid; all others end.
+     * @param {{ currentPassword: string, newPassword: string }} input
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    changePassword({ currentPassword, newPassword }: {
+        currentPassword: string;
+        newPassword: string;
+    }, opts?: RequestOptions): Promise<void>;
+    /**
+     * The user's active sessions, newest first.
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<SessionInfo[]>}
+     */
+    sessions(opts?: RequestOptions): Promise<SessionInfo[]>;
+    /**
+     * Ends one of the user's sessions, for example a lost device.
+     * @param {string} id
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    revokeSession(id: string, opts?: RequestOptions): Promise<void>;
+    /**
+     * The stored session token, if any.
+     * @returns {Promise<string | null>}
+     */
+    token(): Promise<string | null>;
+    /**
+     * Calls listener on sign-in, sign-out and session expiry.
+     * @param {AuthListener} listener
+     * @returns {() => void} Stops listening.
+     */
+    onAuthChange(listener: AuthListener): () => void;
+    /**
+     * @internal
+     * @param {Session} session
+     * @returns {Promise<Session>}
+     */
+    signedIn(session: Session): Promise<Session>;
+    /**
+     * @internal
+     * @param {AuthEvent} event
+     */
+    signedOut(event: AuthEvent): Promise<void>;
+    /**
+     * Called by the client when the server refuses the stored token.
+     * @internal
+     */
+    _expired(): Promise<void>;
+    /**
+     * @internal
+     * @param {AuthEvent} event
+     * @param {Session | null} session
+     */
+    emit(event: AuthEvent, session: Session | null): void;
+}

package/types/client.d.ts

@@ -0,0 +1,132 @@
+import { Admin } from './admin.js';
+import { Auth } from './auth.js';
+import { Database } from './data.js';
+export type TokenStorage = import('./storage.js').TokenStorage;
+export type RetryOptions = {
+    /**
+     * Extra attempts after the first (0 disables).
+     */
+    attempts: number;
+    /**
+     * Longest wait between attempts; default 30000.
+     */
+    maxDelayMs?: number;
+};
+export type ClientOptions = {
+    /**
+     * Base URL of backd, e.g. "https://api.example.com".
+     */
+    url: string;
+    /**
+     * The realm to talk to.
+     */
+    realm: string;
+    /**
+     * Server-side only: an API key (`bdk_…`). Full access to the realm.
+     */
+    apiKey?: string;
+    /**
+     * Allow `apiKey` in a browser. Anyone who loads the page gets the key.
+     */
+    dangerouslyAllowBrowser?: boolean;
+    /**
+     * Where the session token lives; memory by default.
+     */
+    storage?: TokenStorage;
+    /**
+     * Retries for 429/503; off by default.
+     */
+    retry?: RetryOptions;
+    /**
+     * A fetch implementation; the global one by default.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Extra headers for every request.
+     */
+    headers?: Record<string, string>;
+};
+export type RequestOptions = {
+    signal?: AbortSignal;
+    retry?: RetryOptions;
+    headers?: Record<string, string>;
+};
+export type RequestInit = {
+    method: string;
+    /**
+     * Path segments after /v1/{realm}, encoded here.
+     */
+    path: string[];
+    query?: Record<string, string | number | boolean | undefined>;
+    /**
+     * Sent as JSON.
+     */
+    body?: unknown;
+    /**
+     * Defaults to application/json when there's a body.
+     */
+    contentType?: string;
+    headers?: Record<string, string>;
+    /**
+     * Send credentials; default true.
+     */
+    auth?: boolean;
+    /**
+     * Treat a refused session token as expired; default true.
+     */
+    expire?: boolean;
+    signal?: AbortSignal;
+    retry?: RetryOptions;
+};
+export type RawResponse = {
+    status: number;
+    headers: Headers;
+    /**
+     * Parsed JSON, or undefined for empty bodies.
+     */
+    data: any;
+};
+/**
+ * Creates a client for one realm.
+ * @param {ClientOptions} options
+ * @returns {Client}
+ */
+export declare function createClient(options: ClientOptions): Client;
+export declare class Client {
+    /** @readonly */
+    url: string;
+    /** @readonly */
+    realm: string;
+    /** @internal */
+    apiKey: string | undefined;
+    /** @internal */
+    fetchImpl: typeof fetch;
+    /** @internal */
+    retry: RetryOptions;
+    /** @internal */
+    headers: Record<string, string>;
+    /** @readonly */
+    storage: import("./storage.js").TokenStorage;
+    /** Sign-up, login and sessions. */
+    auth: Auth;
+    /** Users, roles, invitations and API keys; needs an admin `apiKey` or an admin user's session. */
+    admin: Admin;
+    /** @param {ClientOptions} options */
+    constructor(options: ClientOptions);
+    /** Whether the client was created with an API key. */
+    get hasApiKey(): boolean;
+    /**
+     * A database of the realm, to reach its collections:
+     * `client.db('main').collection('posts')`.
+     * @param {string} name
+     * @returns {Database}
+     */
+    db(name: string): Database;
+    /**
+     * Sends a request to /v1/{realm}/…, adding credentials, and returns the
+     * parsed answer. Non-2xx answers throw a BackdError.
+     * @param {RequestInit} req
+     * @returns {Promise<RawResponse>}
+     */
+    request(req: RequestInit): Promise<RawResponse>;
+}

package/types/data.d.ts

@@ -0,0 +1,260 @@
+import { Job } from './functions.js';
+export type Client = import('./client.js').Client;
+export type RequestOptions = import('./client.js').RequestOptions;
+export type JobData = import('./functions.js').JobData;
+export type Meta = {
+    /**
+     * RFC3339 timestamp.
+     */
+    created_at: string;
+    /**
+     * RFC3339 timestamp.
+     */
+    updated_at: string;
+    /**
+     * Increases on every write; missing only on very old documents.
+     */
+    version?: number;
+    /**
+     * Id of the user who created it (realms with auth enabled).
+     */
+    owner?: string | null;
+    /**
+     * `user:<id>`, `key:<name>` or `anonymous`.
+     */
+    created_by?: string;
+    /**
+     * `user:<id>`, `key:<name>` or `anonymous`.
+     */
+    updated_by?: string;
+};
+export type Doc<T extends object = Record<string, any>> = T & {
+    id: string;
+    _meta: Meta;
+};
+export type ListParams = {
+    /**
+     * Filter in backd's query language, e.g. `{ price: { $lt: 20 } }`
+     * or `{ $or: [{ title: { $icontains: 'go' } }, { body: { $icontains: 'go' } }] }`.
+     */
+    where?: object | string;
+    /**
+     * Fields, `-` prefix for descending, e.g. `'-_meta.created_at'`.
+     */
+    orderBy?: string | string[];
+    /**
+     * 1–100; default 20.
+     */
+    limit?: number;
+    skip?: number;
+    /**
+     * Also return `total`.
+     */
+    count?: boolean;
+};
+export type Page<T extends object = Record<string, any>> = {
+    items: Doc<T>[];
+    limit: number;
+    skip: number;
+    has_more: boolean;
+    /**
+     * With `count: true`.
+     */
+    total?: number;
+};
+export type WriteOptions = RequestOptions & {
+    ifMatch?: number | string;
+};
+export type BatchOperation = {
+    op: 'create' | 'replace' | 'patch' | 'delete';
+    collection: string;
+    id?: string;
+    document?: Record<string, any>;
+    patch?: Record<string, any>;
+    ifMatch?: number | string;
+};
+/**
+ * @typedef {import('./client.js').Client} Client
+ * @typedef {import('./client.js').RequestOptions} RequestOptions
+ * @typedef {import('./functions.js').JobData} JobData
+ */
+/**
+ * Server-owned fields of a document.
+ * @typedef {object} Meta
+ * @property {string} created_at   RFC3339 timestamp.
+ * @property {string} updated_at   RFC3339 timestamp.
+ * @property {number} [version]    Increases on every write; missing only on very old documents.
+ * @property {string | null} [owner]  Id of the user who created it (realms with auth enabled).
+ * @property {string} [created_by] `user:<id>`, `key:<name>` or `anonymous`.
+ * @property {string} [updated_by] `user:<id>`, `key:<name>` or `anonymous`.
+ */
+/**
+ * A stored document: the collection's fields plus `id` and `_meta`.
+ * @template {object} [T=Record<string, any>]
+ * @typedef {T & { id: string, _meta: Meta }} Doc
+ */
+/**
+ * @typedef {object} ListParams
+ * @property {object | string} [where]      Filter in backd's query language, e.g. `{ price: { $lt: 20 } }`
+ *   or `{ $or: [{ title: { $icontains: 'go' } }, { body: { $icontains: 'go' } }] }`.
+ * @property {string | string[]} [orderBy]  Fields, `-` prefix for descending, e.g. `'-_meta.created_at'`.
+ * @property {number} [limit]               1–100; default 20.
+ * @property {number} [skip]
+ * @property {boolean} [count]              Also return `total`.
+ */
+/**
+ * A page of documents, as the API returns it.
+ * @template {object} [T=Record<string, any>]
+ * @typedef {object} Page
+ * @property {Doc<T>[]} items
+ * @property {number} limit
+ * @property {number} skip
+ * @property {boolean} has_more
+ * @property {number} [total]   With `count: true`.
+ */
+/**
+ * Options for writes. `ifMatch` makes the write fail with a
+ * VersionMismatchError unless the document is still at that version.
+ * @typedef {RequestOptions & { ifMatch?: number | string }} WriteOptions
+ */
+/**
+ * One write for `db.batch(...)`, applied atomically with the others.
+ * `create` and `replace` need `document`; `patch` needs `patch` (a JSON
+ * Merge Patch). `replace`, `patch` and `delete` need `id`, and accept
+ * `ifMatch` (like `WriteOptions`).
+ * @typedef {object} BatchOperation
+ * @property {'create' | 'replace' | 'patch' | 'delete'} op
+ * @property {string} collection
+ * @property {string} [id]
+ * @property {Record<string, any>} [document]
+ * @property {Record<string, any>} [patch]
+ * @property {number | string} [ifMatch]
+ */
+/** A database of the realm: `client.db(name)`. */
+export declare class Database {
+    /** @internal */
+    client: import("./client.js").Client;
+    /** @readonly */
+    name: string;
+    /**
+     * @param {Client} client
+     * @param {string} name
+     */
+    constructor(client: Client, name: string);
+    /**
+     * A collection of this database.
+     * @template {object} [T=Record<string, any>]
+     * @param {string} name
+     * @returns {Collection<T>}
+     */
+    collection<T extends object = Record<string, any>>(name: string): Collection<T>;
+    /**
+     * Creates, replaces, patches and deletes documents across this
+     * database's collections in one MongoDB transaction: either every
+     * operation applies, or none does (up to 100 operations). Rejects with
+     * a `BackdError` naming the first operation that failed; a version
+     * mismatch (`ifMatch`) is a `VersionMismatchError`, same as a single
+     * write.
+     * @param {BatchOperation[]} operations
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<(Doc | { id: string })[]>} one entry per operation, in order
+     */
+    batch(operations: BatchOperation[], opts?: RequestOptions): Promise<(Doc | {
+        id: string;
+    })[]>;
+    /**
+     * Calls a function. Returns its output directly for a `sync`
+     * function; for `async`, a `Job` handle to poll instead of the
+     * output (`job.status()`, or `job.wait()` for the output). A
+     * function's own error (`ctx.error(status, code, message)`) arrives
+     * as a `BackdError` with that status and code — for `async`, only
+     * once `job.wait()` resolves, not from this call itself.
+     *
+     * `webhook` functions can't be called through this method: their
+     * caller is whatever service sends the webhook, never this client.
+     * @param {string} name
+     * @param {unknown} [input] Any JSON value; omitted is sent as `null`.
+     * @param {RequestOptions & { idempotencyKey?: string }} [opts]
+     * @returns {Promise<unknown | Job>}
+     */
+    fn(name: string, input?: unknown, opts?: RequestOptions & {
+        idempotencyKey?: string;
+    }): Promise<unknown | Job>;
+}
+/**
+ * A collection: `client.db(db).collection(name)`. `T` describes the
+ * documents' own fields.
+ * @template {object} [T=Record<string, any>]
+ */
+export declare class Collection<T extends object = Record<string, any>> {
+    /** @internal */
+    client: import("./client.js").Client;
+    /** @internal */
+    path: string[];
+    /**
+     * @param {Client} client
+     * @param {string} database
+     * @param {string} name
+     */
+    constructor(client: Client, database: string, name: string);
+    /**
+     * One page of documents the caller may read.
+     * @param {ListParams} [params]
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<Page<T>>}
+     */
+    list(params?: ListParams, opts?: RequestOptions): Promise<Page<T>>;
+    /**
+     * Every matching document, fetching pages as needed:
+     * `for await (const doc of posts.iterate({ where }))`. Pages are
+     * fetched by offset, so documents created or deleted meanwhile can be
+     * skipped or repeated.
+     * @param {Omit<ListParams, 'skip' | 'count'>} [params] `limit` is the page size (default 100).
+     * @param {RequestOptions} [opts]
+     * @returns {AsyncGenerator<Doc<T>, void, undefined>}
+     */
+    iterate(params?: Omit<ListParams, 'skip' | 'count'>, opts?: RequestOptions): AsyncGenerator<Doc<T>, void, undefined>;
+    /**
+     * One document; NotFoundError if it doesn't exist or the caller may not read it.
+     * @param {string} id
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<Doc<T>>}
+     */
+    get(id: string, opts?: RequestOptions): Promise<Doc<T>>;
+    /**
+     * Creates a document. `id` and `_meta` are set by the server.
+     * @param {T} doc
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<Doc<T>>}
+     */
+    create(doc: T, opts?: RequestOptions): Promise<Doc<T>>;
+    /**
+     * Replaces the whole document: fields not in `doc` are removed.
+     * @param {string} id
+     * @param {T} doc
+     * @param {WriteOptions} [opts]
+     * @returns {Promise<Doc<T>>}
+     */
+    replace(id: string, doc: T, opts?: WriteOptions): Promise<Doc<T>>;
+    /**
+     * Updates some fields (JSON Merge Patch): fields in `patch` are set,
+     * nested objects are merged, and `null` removes a field.
+     * @param {string} id
+     * @param {Partial<T> | Record<string, unknown>} patch
+     * @param {WriteOptions} [opts]
+     * @returns {Promise<Doc<T>>}
+     */
+    patch(id: string, patch: Partial<T> | Record<string, unknown>, opts?: WriteOptions): Promise<Doc<T>>;
+    /**
+     * Deletes a document.
+     * @param {string} id
+     * @param {WriteOptions} [opts]
+     * @returns {Promise<void>}
+     */
+    delete(id: string, opts?: WriteOptions): Promise<void>;
+}
+/**
+ * `3` → `"3"`; strings (`*`, `"3"`, `"2", "3"`) are sent as given.
+ * @param {number | string} v
+ */
+export declare function ifMatchValue(v: number | string): string;