backd-js 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backd-js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "JavaScript client for backd: auth, sessions and data for browsers, Node and edge runtimes.",
   "keywords": [
     "backd",

package/src/admin.js

@@ -27,6 +27,7 @@ import { Job } from './functions.js'
  * @property {number} limit
  * @property {number} skip
  * @property {boolean} has_more
+ * @property {string} [next_cursor]   With `has_more`: pass it as `after` for the next page.
  */
 
 /**
@@ -65,6 +66,7 @@ import { Job } from './functions.js'
  * @property {'data' | 'admin'} role
  * @property {string} prefix          First characters of the key.
  * @property {string[]} networks      Where it may be used from; empty: anywhere.
+ * @property {string[]} scopes        What it reaches (`read:blog/posts`, `call:main/export`…); empty: everything.
  * @property {string} created_at
  * @property {string | null} last_used_at
  * @property {string | null} expires_at
@@ -225,13 +227,14 @@ class AdminUsers {
   }
 
   /**
-   * A page of users, sorted by email.
-   * @param {{ limit?: number, skip?: number }} [params]
+   * A page of users, sorted by email. `after` is the `next_cursor` of the
+   * previous page (not combinable with `skip`).
+   * @param {{ limit?: number, skip?: number, after?: string }} [params]
    * @param {RequestOptions} [opts]
    * @returns {Promise<UserPage>}
    */
   async list(params = {}, opts) {
-    return (await this.admin._request({ method: 'GET', path: ['users'], query: { limit: params.limit, skip: params.skip }, ...opts })).data
+    return (await this.admin._request({ method: 'GET', path: ['users'], query: { limit: params.limit, skip: params.skip, after: params.after }, ...opts })).data
   }
 
   /**
@@ -388,17 +391,20 @@ class AdminAPIKeys {
 
   /**
    * Creates a key; store its `key` now, it is never shown again.
-   * @param {{ name: string, role?: 'data' | 'admin', expiresIn?: string, networks?: string[] }} input
-   *   `role` defaults to data; `expiresIn`: days (`90d`) or Go durations (`12h`).
+   * @param {{ name: string, role?: 'data' | 'admin', expiresIn?: string, networks?: string[], scopes?: string[] }} input
+   *   `role` defaults to data; `expiresIn`: days (`90d`) or Go durations (`12h`). `scopes` limit what a
+   *   data key reaches: `read`, `write` or `call`, optionally followed by `:<database>` or
+   *   `:<database>/<collection or function>`; none means everything.
    * @param {RequestOptions} [opts]
    * @returns {Promise<NewAPIKey>}
    */
-  async create({ name, role, expiresIn, networks }, opts) {
+  async create({ name, role, expiresIn, networks, scopes }, opts) {
     /** @type {Record<string, unknown>} */
     const body = { name }
     if (role !== undefined) body.role = role
     if (expiresIn !== undefined) body.expires_in = expiresIn
     if (networks !== undefined) body.networks = networks
+    if (scopes !== undefined) body.scopes = scopes
     return (await this.admin._request({ method: 'POST', path: ['apikeys'], body, ...opts })).data
   }
 

package/src/auth.js

@@ -1,4 +1,5 @@
 import { AuthenticationError, VerificationRequiredError } from './errors.js'
+import { COOKIE_SESSION } from './storage.js'
 
 /**
  * @typedef {import('./client.js').Client} Client
@@ -19,8 +20,9 @@ import { AuthenticationError, VerificationRequiredError } from './errors.js'
 /**
  * A new session.
  * @typedef {object} Session
- * @property {string} token       Session token (`bds_…`); already stored by the client.
- * @property {'Bearer'} token_type
+ * @property {string} [token]     Session token (`bds_…`); already stored by the client. Absent with `cookies: true`:
+ *   the session is in an HttpOnly cookie, out of reach of scripts.
+ * @property {'Bearer'} [token_type]
  * @property {string} session_id
  * @property {string} expires_at  RFC3339; pushed forward as the session is used.
  * @property {User} user
@@ -81,8 +83,9 @@ export class Auth {
    * @returns {Promise<Session>}
    */
   async signup({ email, password, invitation, locale, redirectTo }, opts) {
-    /** @type {Record<string, string>} */
+    /** @type {Record<string, string | boolean>} */
     const body = { email, password }
+    if (this.client.cookies) body.cookie = true
     if (invitation) body.invitation = invitation
     if (locale) body.locale = locale
     if (redirectTo) body.redirect_to = redirectTo
@@ -100,7 +103,8 @@ export class Auth {
    * @returns {Promise<Session>}
    */
   async login({ email, password }, opts) {
-    const { data } = await this.client.request({ method: 'POST', path: ['_auth', 'login'], body: { email, password }, auth: false, ...opts })
+    const body = this.client.cookies ? { email, password, cookie: true } : { email, password }
+    const { data } = await this.client.request({ method: 'POST', path: ['_auth', 'login'], body, auth: false, ...opts })
     return this.signedIn(data)
   }
 
@@ -311,11 +315,23 @@ export class Auth {
   }
 
   /**
-   * The stored session token, if any.
+   * The stored session token, if any. Always null with `cookies: true`: the
+   * token is in a cookie that scripts can't read.
    * @returns {Promise<string | null>}
    */
   async token() {
-    return (await this.client.storage.get()) ?? null
+    const token = (await this.client.storage.get()) ?? null
+    return token === COOKIE_SESSION ? null : token
+  }
+
+  /**
+   * Whether this client believes it is signed in: it holds a token, or (with
+   * `cookies: true`) it signed in and hasn't signed out or been refused since.
+   * A page that has just loaded knows nothing: ask the server with {@link Auth#me}.
+   * @returns {Promise<boolean>}
+   */
+  async hasSession() {
+    return Boolean(await this.client.storage.get())
   }
 
   /**
@@ -334,7 +350,7 @@ export class Auth {
    * @returns {Promise<Session>}
    */
   async signedIn(session) {
-    await this.client.storage.set(session.token)
+    await this.client.storage.set(session.token ?? COOKIE_SESSION)
     this.emit('SIGNED_IN', session)
     return session
   }

package/src/client.js

@@ -2,7 +2,7 @@ import { Admin } from './admin.js'
 import { Auth } from './auth.js'
 import { Database } from './data.js'
 import { NetworkError, RetryableError, errorFromResponse } from './errors.js'
-import { memoryStorage } from './storage.js'
+import { COOKIE_SESSION, memoryStorage } from './storage.js'
 
 /**
  * @typedef {import('./storage.js').TokenStorage} TokenStorage
@@ -23,6 +23,9 @@ import { memoryStorage } from './storage.js'
  * @property {string} [apiKey]            Server-side only: an API key (`bdk_…`). Full access to the realm.
  * @property {boolean} [dangerouslyAllowBrowser] Allow `apiKey` in a browser. Anyone who loads the page gets the key.
  * @property {TokenStorage} [storage]     Where the session token lives; memory by default.
+ * @property {boolean} [cookies]          Browser apps: keep the session in an HttpOnly cookie that scripts can't read,
+ *   instead of a token. The realm must enable `sessions.cookie` and list the app's origin in `cors.origins`; the
+ *   app's page (or the API) must be on a site the cookie's SameSite setting allows. The admin API doesn't take cookies.
  * @property {RetryOptions} [retry]       Retries for 429/503; off by default.
  * @property {typeof fetch} [fetch]       A fetch implementation; the global one by default.
  * @property {Record<string, string>} [headers] Extra headers for every request.
@@ -81,11 +84,16 @@ export class Client {
           '`dangerouslyAllowBrowser: true` if you really mean it.',
       )
     }
+    if (options.cookies && options.apiKey) {
+      throw new TypeError('createClient: `cookies` is for sessions in a browser; an API key is sent in a header')
+    }
     /** @readonly */
     this.url = options.url.replace(/\/+$/, '')
     /** @readonly */
     this.realm = options.realm
     /** @internal */
+    this.cookies = Boolean(options.cookies)
+    /** @internal */
     this.apiKey = options.apiKey
     /** @internal */
     this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
@@ -138,14 +146,15 @@ export class Client {
       } else {
         const token = await this.storage.get()
         if (token) {
-          headers.Authorization = 'Bearer ' + token
+          if (token !== COOKIE_SESSION) headers.Authorization = 'Bearer ' + token // a cookie session is sent by the browser
           sentSession = true
         }
       }
     }
 
     const retry = req.retry ?? this.retry
-    const safe = req.method === 'GET' || Object.keys(headers).some((h) => h.toLowerCase() === 'if-match')
+    // Safe to repeat: reads, writes conditional on a version, and requests the server deduplicates by key.
+    const safe = req.method === 'GET' || Object.keys(headers).some((h) => ['if-match', 'idempotency-key'].includes(h.toLowerCase()))
     const attempts = safe ? Math.max(0, retry.attempts) : 0
     for (let attempt = 0; ; attempt++) {
       /** @type {Response} */
@@ -156,6 +165,7 @@ export class Client {
           headers,
           body: req.body === undefined ? undefined : JSON.stringify(req.body),
           signal: req.signal,
+          credentials: this.cookies ? 'include' : undefined,
         })
       } catch (cause) {
         throw new NetworkError({

package/src/data.js

@@ -54,6 +54,15 @@ import { Job } from './functions.js'
  * @typedef {RequestOptions & { ifMatch?: number | string }} WriteOptions
  */
 
+/**
+ * Options for creates and batches. `idempotencyKey` makes a retry safe: the
+ * server remembers the answer of the first request with a key for 24 hours and
+ * returns it again for the same key and body, instead of creating a second
+ * document. The client also retries such a request itself after a network
+ * error, `429` or `503` (see `retry`).
+ * @typedef {RequestOptions & { idempotencyKey?: string }} CreateOptions
+ */
+
 /**
  * One write for `db.batch(...)`, applied atomically with the others.
  * `create` and `replace` need `document`; `patch` needs `patch` (a JSON
@@ -99,14 +108,14 @@ export class Database {
    * mismatch (`ifMatch`) is a `VersionMismatchError`, same as a single
    * write.
    * @param {BatchOperation[]} operations
-   * @param {RequestOptions} [opts]
+   * @param {CreateOptions} [opts]
    * @returns {Promise<(Doc | { id: string })[]>} one entry per operation, in order
    */
   async batch(operations, opts) {
     const body = {
       operations: operations.map(({ ifMatch, ...op }) => (ifMatch === undefined ? op : { ...op, if_match: ifMatchValue(ifMatch) })),
     }
-    const { data } = await this.client.request({ method: 'POST', path: [this.name, '_batch'], body, ...opts })
+    const { data } = await this.client.request({ method: 'POST', path: [this.name, '_batch'], body, ...keyed(opts) })
     return data.results
   }
 
@@ -208,13 +217,15 @@ export class Collection {
   }
 
   /**
-   * Creates a document. `id` and `_meta` are set by the server.
+   * Creates a document. `id` and `_meta` are set by the server. With an
+   * `idempotencyKey`, a repeated request returns the document created by the
+   * first one.
    * @param {T} doc
-   * @param {RequestOptions} [opts]
+   * @param {CreateOptions} [opts]
    * @returns {Promise<Doc<T>>}
    */
   async create(doc, opts) {
-    return (await this.client.request({ method: 'POST', path: this.path, body: doc, ...opts })).data
+    return (await this.client.request({ method: 'POST', path: this.path, body: doc, ...keyed(opts) })).data
   }
 
   /**
@@ -274,6 +285,16 @@ function listQuery(p) {
   }
 }
 
+/**
+ * Turns `idempotencyKey` into an Idempotency-Key header.
+ * @param {CreateOptions} [opts]
+ * @returns {RequestOptions}
+ */
+function keyed(opts = {}) {
+  const { idempotencyKey, ...rest } = opts
+  return idempotencyKey === undefined ? rest : { ...rest, headers: { ...rest.headers, 'Idempotency-Key': idempotencyKey } }
+}
+
 /**
  * Turns `ifMatch` into an If-Match header.
  * @param {WriteOptions} opts

package/src/index.js

@@ -30,6 +30,7 @@ export { memoryStorage, localStorageStorage } from './storage.js'
  * @typedef {import('./data.js').Meta} Meta
  * @typedef {import('./data.js').ListParams} ListParams
  * @typedef {import('./data.js').WriteOptions} WriteOptions
+ * @typedef {import('./data.js').CreateOptions} CreateOptions
  * @typedef {import('./admin.js').AdminUser} AdminUser
  * @typedef {import('./admin.js').UserPage} UserPage
  * @typedef {import('./admin.js').Invitation} Invitation

package/src/storage.js

@@ -6,6 +6,13 @@
  * @property {() => void | Promise<void>} remove
  */
 
+/**
+ * What the client stores, instead of a token, when the session lives in an
+ * HttpOnly cookie (`cookies: true`): a hint that there is a session, with
+ * nothing secret in it.
+ */
+export const COOKIE_SESSION = 'cookie-session'
+
 /**
  * Keeps the token in memory: it is lost on reload, and scripts on the page
  * can't read it from storage. The default.

package/types/admin.d.ts

@@ -28,6 +28,10 @@ export type UserPage = {
     limit: number;
     skip: number;
     has_more: boolean;
+    /**
+     * With `has_more`: pass it as `after` for the next page.
+     */
+    next_cursor?: string;
 };
 export type Invitation = {
     id: string;
@@ -79,6 +83,10 @@ export type APIKeyInfo = {
      * Where it may be used from; empty: anywhere.
      */
     networks: string[];
+    /**
+     * What it reaches (`read:blog/posts`, `call:main/export`…); empty: everything.
+     */
+    scopes: string[];
     created_at: string;
     last_used_at: string | null;
     expires_at: string | null;
@@ -241,6 +249,7 @@ export type JobsPage = {
  * @property {number} limit
  * @property {number} skip
  * @property {boolean} has_more
+ * @property {string} [next_cursor]   With `has_more`: pass it as `after` for the next page.
  */
 /**
  * @typedef {object} Invitation
@@ -274,6 +283,7 @@ export type JobsPage = {
  * @property {'data' | 'admin'} role
  * @property {string} prefix          First characters of the key.
  * @property {string[]} networks      Where it may be used from; empty: anywhere.
+ * @property {string[]} scopes        What it reaches (`read:blog/posts`, `call:main/export`…); empty: everything.
  * @property {string} created_at
  * @property {string | null} last_used_at
  * @property {string | null} expires_at
@@ -408,14 +418,16 @@ declare class AdminUsers {
     /** @param {Admin} admin */
     constructor(admin: Admin);
     /**
-     * A page of users, sorted by email.
-     * @param {{ limit?: number, skip?: number }} [params]
+     * A page of users, sorted by email. `after` is the `next_cursor` of the
+     * previous page (not combinable with `skip`).
+     * @param {{ limit?: number, skip?: number, after?: string }} [params]
      * @param {RequestOptions} [opts]
      * @returns {Promise<UserPage>}
      */
     list(params?: {
         limit?: number;
         skip?: number;
+        after?: string;
     }, opts?: RequestOptions): Promise<UserPage>;
     /**
      * The user with this email (case-insensitive), or null.
@@ -536,16 +548,19 @@ declare class AdminAPIKeys {
     list(opts?: RequestOptions): Promise<APIKeyInfo[]>;
     /**
      * Creates a key; store its `key` now, it is never shown again.
-     * @param {{ name: string, role?: 'data' | 'admin', expiresIn?: string, networks?: string[] }} input
-     *   `role` defaults to data; `expiresIn`: days (`90d`) or Go durations (`12h`).
+     * @param {{ name: string, role?: 'data' | 'admin', expiresIn?: string, networks?: string[], scopes?: string[] }} input
+     *   `role` defaults to data; `expiresIn`: days (`90d`) or Go durations (`12h`). `scopes` limit what a
+     *   data key reaches: `read`, `write` or `call`, optionally followed by `:<database>` or
+     *   `:<database>/<collection or function>`; none means everything.
      * @param {RequestOptions} [opts]
      * @returns {Promise<NewAPIKey>}
      */
-    create({ name, role, expiresIn, networks }: {
+    create({ name, role, expiresIn, networks, scopes }: {
         name: string;
         role?: 'data' | 'admin';
         expiresIn?: string;
         networks?: string[];
+        scopes?: string[];
     }, opts?: RequestOptions): Promise<NewAPIKey>;
     /**
      * Revokes a key: it stops working at once.

package/types/auth.d.ts

@@ -16,10 +16,11 @@ export type User = {
 };
 export type Session = {
     /**
-     * Session token (`bds_…`); already stored by the client.
+     * Session token (`bds_…`); already stored by the client. Absent with `cookies: true`:
+     * the session is in an HttpOnly cookie, out of reach of scripts.
      */
-    token: string;
-    token_type: 'Bearer';
+    token?: string;
+    token_type?: 'Bearer';
     session_id: string;
     /**
      * RFC3339; pushed forward as the session is used.
@@ -246,10 +247,18 @@ export declare class Auth {
      */
     revokeSession(id: string, opts?: RequestOptions): Promise<void>;
     /**
-     * The stored session token, if any.
+     * The stored session token, if any. Always null with `cookies: true`: the
+     * token is in a cookie that scripts can't read.
      * @returns {Promise<string | null>}
      */
     token(): Promise<string | null>;
+    /**
+     * Whether this client believes it is signed in: it holds a token, or (with
+     * `cookies: true`) it signed in and hasn't signed out or been refused since.
+     * A page that has just loaded knows nothing: ask the server with {@link Auth#me}.
+     * @returns {Promise<boolean>}
+     */
+    hasSession(): Promise<boolean>;
     /**
      * Calls listener on sign-in, sign-out and session expiry.
      * @param {AuthListener} listener

package/types/client.d.ts

@@ -33,6 +33,12 @@ export type ClientOptions = {
      * Where the session token lives; memory by default.
      */
     storage?: TokenStorage;
+    /**
+     * Browser apps: keep the session in an HttpOnly cookie that scripts can't read,
+     * instead of a token. The realm must enable `sessions.cookie` and list the app's origin in `cors.origins`; the
+     * app's page (or the API) must be on a site the cookie's SameSite setting allows. The admin API doesn't take cookies.
+     */
+    cookies?: boolean;
     /**
      * Retries for 429/503; off by default.
      */
@@ -98,6 +104,8 @@ export declare class Client {
     /** @readonly */
     realm: string;
     /** @internal */
+    cookies: boolean;
+    /** @internal */
     apiKey: string | undefined;
     /** @internal */
     fetchImpl: typeof fetch;

package/types/data.d.ts

@@ -75,6 +75,9 @@ export type Page<T extends object = Record<string, any>> = {
 export type WriteOptions = RequestOptions & {
     ifMatch?: number | string;
 };
+export type CreateOptions = RequestOptions & {
+    idempotencyKey?: string;
+};
 export type BatchOperation = {
     op: 'create' | 'replace' | 'patch' | 'delete';
     collection: string;
@@ -131,6 +134,14 @@ export type BatchOperation = {
  * VersionMismatchError unless the document is still at that version.
  * @typedef {RequestOptions & { ifMatch?: number | string }} WriteOptions
  */
+/**
+ * Options for creates and batches. `idempotencyKey` makes a retry safe: the
+ * server remembers the answer of the first request with a key for 24 hours and
+ * returns it again for the same key and body, instead of creating a second
+ * document. The client also retries such a request itself after a network
+ * error, `429` or `503` (see `retry`).
+ * @typedef {RequestOptions & { idempotencyKey?: string }} CreateOptions
+ */
 /**
  * One write for `db.batch(...)`, applied atomically with the others.
  * `create` and `replace` need `document`; `patch` needs `patch` (a JSON
@@ -170,10 +181,10 @@ export declare class Database {
      * mismatch (`ifMatch`) is a `VersionMismatchError`, same as a single
      * write.
      * @param {BatchOperation[]} operations
-     * @param {RequestOptions} [opts]
+     * @param {CreateOptions} [opts]
      * @returns {Promise<(Doc | { id: string })[]>} one entry per operation, in order
      */
-    batch(operations: BatchOperation[], opts?: RequestOptions): Promise<(Doc | {
+    batch(operations: BatchOperation[], opts?: CreateOptions): Promise<(Doc | {
         id: string;
     })[]>;
     /**
@@ -239,12 +250,14 @@ export declare class Collection<T extends object = Record<string, any>> {
      */
     get(id: string, opts?: RequestOptions): Promise<Doc<T>>;
     /**
-     * Creates a document. `id` and `_meta` are set by the server.
+     * Creates a document. `id` and `_meta` are set by the server. With an
+     * `idempotencyKey`, a repeated request returns the document created by the
+     * first one.
      * @param {T} doc
-     * @param {RequestOptions} [opts]
+     * @param {CreateOptions} [opts]
      * @returns {Promise<Doc<T>>}
      */
-    create(doc: T, opts?: RequestOptions): Promise<Doc<T>>;
+    create(doc: T, opts?: CreateOptions): Promise<Doc<T>>;
     /**
      * Replaces the whole document: fields not in `doc` are removed.
      * @param {string} id

package/types/index.d.ts

@@ -17,6 +17,7 @@ export type ErrorDetail = import('./errors.js').ErrorDetail;
 export type Meta = import('./data.js').Meta;
 export type ListParams = import('./data.js').ListParams;
 export type WriteOptions = import('./data.js').WriteOptions;
+export type CreateOptions = import('./data.js').CreateOptions;
 export type AdminUser = import('./admin.js').AdminUser;
 export type UserPage = import('./admin.js').UserPage;
 export type Invitation = import('./admin.js').Invitation;
@@ -40,6 +41,7 @@ export type Page<T extends object = Record<string, any>> = import('./data.js').P
  * @typedef {import('./data.js').Meta} Meta
  * @typedef {import('./data.js').ListParams} ListParams
  * @typedef {import('./data.js').WriteOptions} WriteOptions
+ * @typedef {import('./data.js').CreateOptions} CreateOptions
  * @typedef {import('./admin.js').AdminUser} AdminUser
  * @typedef {import('./admin.js').UserPage} UserPage
  * @typedef {import('./admin.js').Invitation} Invitation

package/types/storage.d.ts

@@ -10,6 +10,12 @@ export type TokenStorage = {
     set: (token: string) => void | Promise<void>;
     remove: () => void | Promise<void>;
 };
+/**
+ * What the client stores, instead of a token, when the session lives in an
+ * HttpOnly cookie (`cookies: true`): a hint that there is a session, with
+ * nothing secret in it.
+ */
+export declare const COOKIE_SESSION = "cookie-session";
 /**
  * Keeps the token in memory: it is lost on reload, and scripts on the page
  * can't read it from storage. The default.