@rebasepro/client 0.22.0 → 0.24.0

package/dist/admin.d.ts

@@ -1,20 +1,25 @@
 import type { Transport } from "./transport.js";
-import { AdminUser } from "@rebasepro/types";
+import type { AdminUser, RoleSummary } from "@rebasepro/types";
 export type { AdminUser };
 export interface CreateAdminOptions {
     adminPath?: string;
 }
+/** The window and filter `GET /admin/users` takes. */
+export interface ListUsersOptions {
+    search?: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+}
 export declare function createAdmin(transport: Transport, options?: CreateAdminOptions): {
-    listUsers: () => Promise<{
+    listUsers: (options?: ListUsersOptions) => Promise<{
         users: AdminUser[];
+        total: number;
+        limit: number;
+        offset: number;
     }>;
-    listUsersPaginated: (options?: {
-        search?: string;
-        limit?: number;
-        offset?: number;
-        orderBy?: string;
-        orderDir?: "asc" | "desc";
-    }) => Promise<{
+    listUsersPaginated: (options?: ListUsersOptions) => Promise<{
         users: AdminUser[];
         total: number;
         limit: number;
@@ -36,12 +41,17 @@ export declare function createAdmin(transport: Transport, options?: CreateAdminO
         displayName?: string;
         password?: string;
         roles?: string[];
+        disabled?: boolean;
     }) => Promise<{
         user: AdminUser;
     }>;
     deleteUser: (userId: string) => Promise<{
         success: boolean;
     }>;
+    resetMfa: (userId: string) => Promise<{
+        success: boolean;
+        removedFactors: number;
+    }>;
     resetPassword: (userId: string, options?: {
         password?: string;
     }) => Promise<{
@@ -51,10 +61,7 @@ export declare function createAdmin(transport: Transport, options?: CreateAdminO
         emailDeliveryFailed?: boolean;
     }>;
     listRoles: () => Promise<{
-        roles: Array<{
-            id: string;
-            name: string;
-        }>;
+        roles: RoleSummary[];
     }>;
     bootstrap: () => Promise<{
         success: boolean;

package/dist/api-keys.d.ts

@@ -1,20 +1,13 @@
 import type { Transport } from "./transport.js";
-/**
- * These were re-declared here, under a comment saying they lived in the server
- * package rather than in `@rebasepro/types`. That stopped being true, and the
- * copy drifted: it never gained `admin`, the flag that grants a key the `admin`
- * role — admin routes plus the RLS `default_admin` policies — so the SDK could
- * describe every kind of key except a privileged one, and
- * `createKey({ …, admin: true })` was an excess-property error.
- */
-export type { ApiKeyPermission, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "@rebasepro/types";
-import type { ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "@rebasepro/types";
+export type { ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreatePersonalKeyRequest, UpdateApiKeyRequest } from "@rebasepro/types";
+import type { ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreatePersonalKeyRequest, ScopeSummary, UpdateApiKeyRequest } from "@rebasepro/types";
 /** Options for the `createApiKeys` factory. */
 export interface CreateApiKeysOptions {
     apiKeysPath?: string;
 }
 /**
- * Creates a client for managing API keys via the admin routes.
+ * Creates a client for the project's service keys, via the admin routes.
+ * Needs `keys:read` / `keys:write`.
  *
  * @param transport - The shared HTTP transport created by `createTransport`.
  * @param options   - Optional overrides (e.g. a custom base path).
@@ -36,3 +29,28 @@ export declare function createApiKeys(transport: Transport, options?: CreateApiK
         success: boolean;
     }>;
 };
+/** Options for the `createPersonalKeys` factory. */
+export interface CreatePersonalKeysOptions {
+    personalKeysPath?: string;
+    scopesPath?: string;
+}
+/**
+ * Creates a client for the signed-in account's own API keys — each acts as the
+ * account and holds no scope it does not. Answers `PERSONAL_KEYS_DISABLED`
+ * unless the backend sets `personalKeys: true` on the users collection.
+ */
+export declare function createPersonalKeys(transport: Transport, options?: CreatePersonalKeysOptions): {
+    listKeys: () => Promise<{
+        keys: ApiKeyMasked[];
+    }>;
+    createKey: (data: CreatePersonalKeyRequest) => Promise<{
+        key: ApiKeyWithSecret;
+    }>;
+    revokeKey: (id: string) => Promise<{
+        success: boolean;
+    }>;
+    listScopes: () => Promise<{
+        scopes: ScopeSummary[];
+        held: string[];
+    }>;
+};

package/dist/auth.d.ts

@@ -1,5 +1,5 @@
 import { Transport } from "./transport.js";
-import type { AuthAdapterCapabilities, AuthChangeEvent, RebaseSession, DeviceSession, User } from "@rebasepro/types";
+import type { AuthConfigDocument, AuthChangeEvent, RebaseSession, DeviceSession, User } from "@rebasepro/types";
 export type { RebaseSession, AuthTokens, AuthChangeEvent, DeviceSession } from "@rebasepro/types";
 /** Minimal, non-sensitive user profile returned by {@link findUserByEmail}. */
 export interface PublicUserProfile {
@@ -8,14 +8,15 @@ export interface PublicUserProfile {
     photoURL: string | null;
 }
 /**
- * What `GET /auth/config` answers: the backend's auth capability document.
+ * What `GET /auth/config` answers: the backend's auth capability document, and
+ * whether it serves storage.
  *
  * Declared once, in `@rebasepro/types`, and re-exported here under the name the
  * endpoint uses. The SDK used to carry its own near-copy of it, which listed an
  * `emailServiceEnabled` flag no backend has ever sent and omitted half of what
  * every backend does send.
  */
-export type AuthConfig = AuthAdapterCapabilities;
+export type AuthConfig = AuthConfigDocument;
 export interface AuthStorage {
     getItem: (key: string) => string | null;
     setItem: (key: string, value: string) => void;
@@ -34,6 +35,17 @@ export interface CreateAuthOptions {
      */
     authFlowMode?: "json" | "cookie";
 }
+/**
+ * Finishing a sign-in that the server refused with `MFA_REQUIRED`.
+ *
+ * That refusal carries `details.mfaToken` — proof the first factor was
+ * accepted, good for five minutes and for nothing but the two challenge routes
+ * — and `details.factors`, the factors the account can answer with.
+ */
+export interface MfaPendingOptions {
+    /** `details.mfaToken` of the `MFA_REQUIRED` refusal. */
+    mfaToken?: string;
+}
 export declare function createAuth(transport: Transport, options?: CreateAuthOptions): {
     signInWithEmail: (email: string, password: string) => Promise<{
         user: User;
@@ -41,6 +53,12 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
         refreshToken: string;
     }>;
     signUp: (email: string, password: string, displayName?: string) => Promise<{
+        confirmationRequired: true;
+        user: null;
+        accessToken: null;
+        refreshToken: null;
+    } | {
+        confirmationRequired: false;
         user: User;
         accessToken: string;
         refreshToken: string;
@@ -138,8 +156,11 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
          * Start enrolling a TOTP factor.
          *
          * Returns the secret and an `otpauth://` URI to render as a QR code,
-         * plus ten single-use recovery codes. **Show the recovery codes once
-         * and never again** — only their hashes are stored.
+         * plus — with the account's first factor — ten single-use recovery
+         * codes. **Show the recovery codes once and never again**: only their
+         * hashes are stored. Adding another factor keeps the codes the account
+         * has, and `recoveryCodes` is then `null`; `regenerateRecoveryCodes()`
+         * replaces them.
          *
          * The factor is not usable until `verify` confirms the user's
          * authenticator produced a correct code from it.
@@ -158,7 +179,7 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
                 uri: string;
                 qrUri: string;
             };
-            recoveryCodes: string[];
+            recoveryCodes: string[] | null;
         }>;
         /** Confirm an enrolment with a code from the authenticator app. */
         verify(factorId: string, code: string): Promise<{
@@ -180,12 +201,27 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
          * Remove a factor. Requires an `aal2` session — one that has already
          * answered a challenge — so a stolen `aal1` token cannot turn MFA off.
          */
+        /**
+         * Replace the account's recovery codes with ten new ones, shown once.
+         * Needs an `aal2` session. Adding a second factor keeps the codes the
+         * account already has; this is how to get new ones.
+         */
+        regenerateRecoveryCodes(): Promise<{
+            recoveryCodes: string[];
+        }>;
         unenroll(factorId: string): Promise<{
             success: boolean;
             message: string;
         }>;
-        /** Open a challenge against a verified factor. Expires in five minutes. */
-        challenge(factorId: string): Promise<{
+        /**
+         * Open a challenge against a verified factor. Expires in five minutes.
+         *
+         * Pass `mfaToken` to finish a sign-in that was refused with
+         * `MFA_REQUIRED`: it is the `details.mfaToken` of that refusal, and the
+         * challenge is opened with it as this one request's credential. Without
+         * it, the challenge steps up the session this client already holds.
+         */
+        challenge(factorId: string, options?: MfaPendingOptions): Promise<{
             challengeId: string;
             factorId: string;
             expiresAt: string;
@@ -194,10 +230,11 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
          * Answer a challenge with a TOTP code or a recovery code.
          *
          * This is where an MFA-enrolled account's real session is minted, at
-         * `aal2` — so the returned tokens replace the ones the sign-in handed
-         * back, and this client adopts them.
+         * `aal2` — so this client adopts the returned tokens and announces
+         * `SIGNED_IN`, exactly as any other sign-in does. Pass the same
+         * `mfaToken` the challenge was opened with when finishing a sign-in.
          */
-        verifyChallenge(challengeId: string, code: string): Promise<{
+        verifyChallenge(challengeId: string, code: string, options?: MfaPendingOptions): Promise<{
             user: User;
             accessToken: string;
             refreshToken: string;
@@ -239,9 +276,23 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
         success: boolean;
         message: string;
     }>;
-    verifyEmail: (token: string) => Promise<{
+    verifyEmail: (token: string, options?: {
+        password?: string;
+        removeUnproven?: boolean;
+    }) => Promise<{
         success: boolean;
-        message: string;
+        passwordRemoved: boolean;
+        removedProviders: string[];
+        session: RebaseSession | null;
+    }>;
+    changeEmail: (newEmail: string) => Promise<{
+        pendingEmail: string;
+        expiresAt: string;
+    }>;
+    confirmEmailChange: (token: string) => Promise<{
+        uid: string;
+        email: string;
+        removedProviders: string[];
     }>;
     sendMagicLink: (email: string) => Promise<{
         success: boolean;
@@ -269,7 +320,7 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
     revokeAllSessions: () => Promise<{
         success: boolean;
     }>;
-    getAuthConfig: () => Promise<AuthAdapterCapabilities>;
+    getAuthConfig: () => Promise<AuthConfigDocument>;
     getSession: () => RebaseSession | null;
     onAuthStateChange: (callback: (event: AuthChangeEvent, session: RebaseSession | null) => void) => () => boolean;
     canRestoreSession: () => boolean;

package/dist/backups.d.ts

@@ -1,13 +1,9 @@
 import { Transport } from "./transport.js";
-import type { BackupInfo, BackupDestinationKind } from "@rebasepro/types";
+import { type BackupListing } from "@rebasepro/types";
 export interface CreateBackupsOptions {
     backupsPath?: string;
 }
 export declare function createBackups(transport: Transport, options?: CreateBackupsOptions): {
-    list: () => Promise<{
-        backups: BackupInfo[];
-        destinationKind: BackupDestinationKind;
-        configured: boolean;
-    }>;
+    list: () => Promise<BackupListing>;
     download: (key: string) => Promise<Blob>;
 };

package/dist/collection.d.ts

@@ -1,6 +1,6 @@
 import { FindParams, Transport } from "./transport.js";
 import { RebaseWebSocketClient } from "./websocket.js";
-import { FindResult, SDKCollectionClient } from "@rebasepro/types";
+import { FindResult, SDKCollectionClient, type IncludeSpec } from "@rebasepro/types";
 /**
  * The version of a row, when it came straight from a read that reported one.
  *
@@ -61,8 +61,8 @@ export interface ObserveOptions {
  * `count()` and the reactive `observe()` pair. Program against
  * {@link SDKCollectionClient} when you want a transport-agnostic type.
  */
-export interface CollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>> extends SDKCollectionClient<M, I, U> {
-    count(params?: FindParams<M>): Promise<number>;
+export interface CollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>, Inc = IncludeSpec> extends SDKCollectionClient<M, I, U, Inc> {
+    count(params?: FindParams<M, Inc>): Promise<number>;
     /**
      * Subscribe to a query's results.
      *
@@ -78,7 +78,7 @@ export interface CollectionClient<M extends Record<string, unknown> = Record<str
      *
      * @returns An unsubscribe function.
      */
-    observe(params: FindParams<M> | undefined, onResult: (result: LiveResult<M>) => void, onError?: (error: Error) => void, options?: ObserveOptions): () => void;
+    observe(params: FindParams<M, Inc> | undefined, onResult: (result: LiveResult<M>) => void, onError?: (error: Error) => void, options?: ObserveOptions): () => void;
     /** {@link CollectionClient.observe} for a single row. */
     observeById(id: string | number, onResult: (row: M | undefined, meta: RowSnapshotMeta) => void, onError?: (error: Error) => void, options?: ObserveOptions): () => void;
 }

package/dist/cron.d.ts

@@ -1,12 +1,10 @@
 import { Transport } from "./transport.js";
-import type { CronJobStatus, CronJobLogEntry } from "@rebasepro/types";
+import type { CronJobStatus, CronJobLogEntry, CronJobListing } from "@rebasepro/types";
 export interface CreateCronOptions {
     cronPath?: string;
 }
 export declare function createCron(transport: Transport, options?: CreateCronOptions): {
-    listJobs: () => Promise<{
-        jobs: CronJobStatus[];
-    }>;
+    listJobs: () => Promise<CronJobListing>;
     getJob: (jobId: string) => Promise<{
         job: CronJobStatus;
     }>;

package/dist/index.d.ts

@@ -3,13 +3,13 @@ import { createAuth, CreateAuthOptions } from "./auth.js";
 import { createAdmin, CreateAdminOptions } from "./admin.js";
 import { createCron, CreateCronOptions } from "./cron.js";
 import { createBackups } from "./backups.js";
-import { createApiKeys, CreateApiKeysOptions } from "./api-keys.js";
+import { createApiKeys, CreateApiKeysOptions, createPersonalKeys, CreatePersonalKeysOptions } from "./api-keys.js";
 import { CollectionClient } from "./collection.js";
 import { createFunctionsClient } from "./functions.js";
 import { RebaseWebSocketClient } from "./websocket.js";
 import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel.js";
 import { type OfflineApi, type OfflineConfig } from "./offline.js";
-import { type BatchOperation, type BatchResult, InsertOf, RebaseClient, RebaseSdkData, RowOf, StorageSource, StorageSourceDefinition, StorageSourceRegistry, UpdateOf, type WriteOptions } from "@rebasepro/types";
+import { type BatchOperation, type BatchResult, type IncludeOf, InsertOf, RebaseClient, RebaseSdkData, RowOf, StorageSource, StorageSourceDefinition, StorageSourceRegistry, UpdateOf, type WriteOptions } from "@rebasepro/types";
 export { RebaseApiError } from "./transport.js";
 export { RebaseClientError } from "./errors.js";
 export type { RebaseErrorCode } from "@rebasepro/types";
@@ -20,20 +20,22 @@ export type { IterateParams, FindAllParams, PageWalkOptions, CursorSpec } from "
 export { RebasePaginationError } from "@rebasepro/common";
 export type { PaginationErrorCode } from "@rebasepro/common";
 export { QueryBuilder, or, and, not, cond } from "@rebasepro/common";
+export { resolveStorageReferences, storageReference, parseStorageReference, isStorageReference, STORAGE_REFERENCE_SCHEME } from "@rebasepro/types";
+export type { StorageReferenceTarget, StorageReferenceResolver } from "@rebasepro/types";
 export { createCookieStorage, createMemoryStorage } from "./auth.js";
 export type { AuthConfig, AuthStorage, CookieStorageOptions, CreateAuthOptions } from "./auth.js";
 export type { User, RebaseSession, AuthTokens, AuthChangeEvent, DeviceSession } from "@rebasepro/types";
-export type { CreateAdminOptions } from "./admin.js";
+export type { CreateAdminOptions, ListUsersOptions } from "./admin.js";
 export type { AdminUser } from "./admin.js";
 export type { CreateCronOptions } from "./cron.js";
 export { createBackups } from "./backups.js";
 export type { CreateBackupsOptions } from "./backups.js";
-export type { ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, CreateApiKeysOptions, UpdateApiKeyRequest } from "./api-keys.js";
+export type { ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreateApiKeysOptions, CreatePersonalKeyRequest, CreatePersonalKeysOptions, UpdateApiKeyRequest } from "./api-keys.js";
 export type { FunctionInvokeOptions, FunctionsClient } from "./functions.js";
 export { RebaseWebSocketClient } from "./websocket.js";
 export { RebaseRealtimeChannel } from "./realtime-channel.js";
 export type { PresenceState, PresenceDiff, BroadcastEvent, ChannelTransport, ChannelOptions, ChannelHistoryEntry, ChannelHistoryResult } from "./realtime-channel.js";
-export type { OfflineApi, OfflineConfig, OfflineStatus } from "./offline.js";
+export type { OfflineApi, OfflineConfig, OfflineQueueOptions, OfflineStatus } from "./offline.js";
 export { isOfflineError } from "./offline.js";
 export type { LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection.js";
 export { etagOf } from "./collection.js";
@@ -45,6 +47,7 @@ export interface CreateRebaseClientOptions extends RebaseClientConfig {
     admin?: CreateAdminOptions;
     cron?: CreateCronOptions;
     apiKeys?: CreateApiKeysOptions;
+    personalKeys?: CreatePersonalKeysOptions;
     /**
      * Declared storage sources for multi-backend support. Server-transport
      * entries are auto-wired into `client.storageRegistry`; `direct` sources
@@ -77,12 +80,20 @@ export interface CreateRebaseClientOptions extends RebaseClientConfig {
     offline?: boolean | OfflineConfig;
 }
 type KebabToCamelCase<S extends string> = S extends `${infer T}-${infer U}` ? `${T}${Capitalize<KebabToCamelCase<U>>}` : S;
-type DBEntry<DB, S extends string> = KebabToCamelCase<S> extends keyof DB ? DB[KebabToCamelCase<S>] : unknown;
+/** The accessor whose generated entry declares `Slug: S`, or `never`. */
+type AccessorOfSlug<DB, S extends string> = {
+    [K in keyof DB]: DB[K] extends {
+        Slug: S;
+    } ? K : never;
+}[keyof DB];
+type DBEntry<DB, S extends string> = [
+    AccessorOfSlug<DB, S>
+] extends [never] ? (KebabToCamelCase<S> extends keyof DB ? DB[KebabToCamelCase<S>] : unknown) : DB[AccessorOfSlug<DB, S>];
 type TypedDataLayer<DB> = {
-    collection<S extends string>(slug: S): CollectionClient<RowOf<DBEntry<DB, S>>, InsertOf<DBEntry<DB, S>>, UpdateOf<DBEntry<DB, S>>>;
+    collection<S extends string>(slug: S): CollectionClient<RowOf<DBEntry<DB, S>>, InsertOf<DBEntry<DB, S>>, UpdateOf<DBEntry<DB, S>>, IncludeOf<DBEntry<DB, S>, DB>>;
 } & {
-    [K in keyof DB]: CollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>>;
-} & RebaseSdkData;
+    [K in keyof DB]: CollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>, IncludeOf<DB[K], DB>>;
+} & (string extends keyof DB ? RebaseSdkData : Pick<RebaseSdkData, "collection">);
 /**
  * The return type of `createRebaseClient<DB>()`.
  *
@@ -100,6 +111,7 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
     cron: ReturnType<typeof createCron>;
     backups: ReturnType<typeof createBackups>;
     apiKeys: ReturnType<typeof createApiKeys>;
+    personalKeys: ReturnType<typeof createPersonalKeys>;
     functions: ReturnType<typeof createFunctionsClient>;
     ws?: RebaseWebSocketClient;
     /**
@@ -147,7 +159,15 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
      * Neither reaches into the response for a `data` key.
      */
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
-    collection: <M extends Record<string, unknown> = Record<string, unknown>>(slug: string) => CollectionClient<M>;
+    /**
+     * A collection by slug — the same client `data.collection(slug)` returns,
+     * typed from the generated `Database` when the slug is one of its
+     * collections, or by the row type passed explicitly.
+     */
+    collection: {
+        <S extends string>(slug: S): CollectionClient<RowOf<DBEntry<DB, S>>, InsertOf<DBEntry<DB, S>>, UpdateOf<DBEntry<DB, S>>, IncludeOf<DBEntry<DB, S>, DB>>;
+        <M extends Record<string, unknown> = Record<string, unknown>>(slug: string): CollectionClient<M>;
+    };
     /**
      * Write across collections in one transaction.
      *
@@ -170,12 +190,17 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
      * `data` is aligned to `operations`: the written row for a create, upsert
      * or update, and `null` for a delete.
      *
+     * `collection` is the accessor `client.data.<accessor>` takes — `orderItems`
+     * for the slug `order_items` — and is sent as the slug through the
+     * `collections` dictionary. A name that is not an accessor goes out as
+     * written, so an untyped client can still pass the slug.
+     *
      * @example
      * ```ts
      * await client.batch([
      *     { op: "create", collection: "orders", values: { total: 40 }, ref: "order" },
-     *     { op: "create", collection: "order_items",
-     *       values: { order_id: { $ref: "order.id" }, sku: "A-1" } },
+     *     { op: "create", collection: "orderItems",
+     *       values: { orderId: { $ref: "order.id" }, sku: "A-1" } },
      *     { op: "update", collection: "stock", id: "A-1", values: { count: { $inc: -1 } } }
      * ]);
      * ```