@ragable/sdk 0.8.0 → 0.8.1

package/dist/index.d.mts

@@ -708,7 +708,7 @@ declare class AuthBroadcastChannel {
     close(): void;
 }
 
-type AuthChangeEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "USER_UPDATED";
+type AuthChangeEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "TOKEN_REFRESH_FAILED" | "USER_UPDATED";
 type AuthUserMetadata = Record<string, unknown>;
 interface DefaultAuthUser<Metadata extends AuthUserMetadata = AuthUserMetadata> {
     id: string;
@@ -783,10 +783,26 @@ declare class RagableAuth<U extends object = DefaultAuthUser> {
     private listeners;
     private broadcast;
     private visibilityHandler;
-    private initialized;
+    /** Memoizes the one-shot restore so concurrent callers (constructor eager init,
+     *  every `onAuthStateChange` subscriber, `getSession`) share a single result.
+     *  Non-null also means "restore has started", replacing the old boolean flag. */
+    private initializePromise;
+    /** Bumped on every explicit session change (sign-in/out, refresh). The async
+     *  restore captures this and refuses to overwrite a newer session op that
+     *  landed while it was reading storage (e.g. a sign-out during page load). */
+    private sessionEpoch;
     constructor(config: RagableAuthConfig);
     private log;
+    /**
+     * Restore a persisted session (once). Memoized: every caller awaits the same
+     * promise, so the eager constructor init, `getSession`, and each
+     * `onAuthStateChange` subscriber's INITIAL_SESSION replay never race or
+     * double-restore. Does NOT emit `INITIAL_SESSION` globally — that event is
+     * delivered per-subscriber by `onAuthStateChange` (Supabase-parity), so a
+     * listener attached after restore still sees the existing session.
+     */
     initialize(): Promise<AuthSession<U> | null>;
+    private _initialize;
     signUp(credentials: AuthSignUpCredentials<MetadataForUser<U>>): Promise<PostgrestResult<{
         user: U;
         session: AuthSession<U>;
@@ -835,7 +851,14 @@ declare class RagableAuth<U extends object = DefaultAuthUser> {
         };
     };
     getAccessToken(): string | null;
-    getValidAccessToken(): Promise<string | null>;
+    /**
+     * Returns an access token guaranteed fresh for at least `refreshSkewSeconds`,
+     * refreshing (single-flight) if needed. Pass `force: true` to bypass the skew
+     * check and refresh now — used by the transport's 401 handler so a token the
+     * server rejected (key rotation, clock skew, early revocation) self-heals on
+     * retry instead of failing the call.
+     */
+    getValidAccessToken(force?: boolean): Promise<string | null>;
     getCurrentSession(): AuthSession<U> | null;
     register(body: {
         email: string;
@@ -891,7 +914,17 @@ declare class RagableAuth<U extends object = DefaultAuthUser> {
     private emit;
     private scheduleRefresh;
     private clearRefreshTimer;
+    /**
+     * Refresh the session, deduplicating concurrent callers onto one in-flight
+     * request. Side effects (persisting the new session, or clearing it and
+     * emitting SIGNED_OUT / TOKEN_REFRESH_FAILED) run exactly once inside the
+     * shared promise, so two callers can't double-emit. Resolves to the new
+     * session, or `null` when the refresh failed.
+     */
     singleFlightRefresh(refreshToken: string): Promise<AuthSession<U> | null>;
+    /** Clear the session locally and emit SIGNED_OUT after a definitively-rejected
+     *  refresh, so onAuthStateChange-driven UI redirects to login. */
+    private handleTerminalRefreshFailure;
     private _doRefresh;
     private setupVisibilityListener;
 }
@@ -1340,13 +1373,23 @@ type FunctionInvoker<F extends RagableFunctions = DefaultRagableFunctions> = {
 
 /** Canonical browser/server API base (`…/api`, no trailing slash). */
 declare function normalizeBrowserApiBase(): string;
-type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
+type BrowserDataAuthMode = "user" | "publicAnon" | "admin" | "auto";
 /**
- * Resolves how database requests are authorized. If `dataAuth` is omitted and a
- * static browser data key is configured (`dataStaticKey` / `getDataStaticKey`),
- * defaults to **`publicAnon`** so public apps can use shared collections without
- * sign-in. Use explicit **`dataAuth: "user"`** when you need JWT sessions; use
- * **`"admin"`** when the static key is a data-admin key.
+ * Resolves how database / storage requests are authorized.
+ *
+ * Default (when `dataAuth` is omitted):
+ * - **`auto`** when BOTH a static data key AND user auth (an `authGroupId` or a
+ *   `getAccessToken` callback) are configured — the generated-site case. This is
+ *   the Supabase model: send the signed-in user's JWT when a session exists, and
+ *   fall back to the public anon key for logged-out visitors. Without this, a
+ *   shipped anon key permanently shadows the user session, so owner/group/claim/
+ *   authenticated collection grants can never match a signed-in user.
+ * - **`publicAnon`** when only a static key is configured (no auth group) — a
+ *   purely public app.
+ * - **`user`** when neither — JWT-only.
+ *
+ * Set `dataAuth` explicitly to override: `"user"` (JWT required), `"publicAnon"`
+ * (anon key only, never upgrade), or `"admin"` (the static key is a data-admin key).
  */
 declare function effectiveDataAuth(options: RagableBrowserClientOptions): BrowserDataAuthMode;
 interface RagableBrowserClientOptions {
@@ -1461,6 +1504,12 @@ declare class RagableBrowserAuthClient<AuthUser extends object = DefaultAuthUser
     getSession(): Promise<PostgrestResult<{
         session: AuthSession<AuthUser> | null;
     }>>;
+    /**
+     * Returns a valid (auto-refreshed) access token for the current session, or
+     * `null` if signed out. The sanctioned way to obtain a token for a hand-rolled
+     * `fetch` to a custom endpoint — never read tokens out of storage yourself.
+     */
+    getValidAccessToken(): Promise<string | null>;
 }
 interface BrowserSqlQueryParams {
     databaseInstanceId?: string;
@@ -1556,6 +1605,15 @@ type CollectionRowWithMeta<Row extends Record<string, unknown> = Record<string,
 };
 declare function collectionRecordToRowWithMeta<Row extends Record<string, unknown>>(record: BrowserCollectionRecord<Row>): CollectionRowWithMeta<Row>;
 declare function collectionRecordsToRowWithMeta<Row extends Record<string, unknown>>(records: BrowserCollectionRecord<Row>[]): CollectionRowWithMeta<Row>[];
+/**
+ * Rows returned by a find: {@link CollectionRowWithMeta} when the params carry
+ * a literal `return: "flat"`, envelope {@link BrowserCollectionRecord}s
+ * otherwise. Keeps the default (envelope) call sites free of union-narrowing —
+ * `res.data[0].data` typechecks without a cast.
+ */
+type CollectionFindResult<Row extends Record<string, unknown>, Params> = Params extends {
+    return: "flat";
+} ? CollectionRowWithMeta<Row>[] : BrowserCollectionRecord<Row>[];
 type BrowserCollectionFindParams<Row extends Record<string, unknown> = Record<string, unknown>> = {
     where?: WhereInput<Row>;
     filters?: Array<{
@@ -1586,11 +1644,11 @@ declare class BrowserCollectionApi<Row extends Record<string, unknown> = Record<
      * Query collection rows. Prefer this over the deprecated `find` alias.
      * Use `return: "flat"` to get {@link CollectionRowWithMeta} without nested `.data`.
      */
-    findMany: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    findMany: <Params extends WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>>(whereOrParams?: Params) => Promise<PostgrestResult<CollectionFindResult<RowD<Row>, Params>>>;
     /**
      * @deprecated Use {@link BrowserCollectionApi.findMany} — same behavior.
      */
-    find: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    find: <Params extends WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>>(whereOrParams?: Params) => Promise<PostgrestResult<CollectionFindResult<RowD<Row>, Params>>>;
     /**
      * At most one row, `data` is the record or `null` if none match (not an error).
      */
@@ -1811,10 +1869,24 @@ declare class BrowserStorageBucketClient {
     private readonly options;
     private readonly fetchImpl;
     private readonly bucketId;
-    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch, bucketId: string);
+    private readonly ragableAuth;
+    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch, bucketId: string, ragableAuth?: RagableAuth | null);
     private get authGroupId();
     private base;
+    /**
+     * Same credential resolution as the database client (see resolveDatabaseAuthBearer):
+     * in the generated-site default (`auto`), a signed-in user's auto-refreshed JWT
+     * is used so storage calls carry the user's identity; logged-out visitors fall
+     * back to the anon key. Previously storage ignored the managed session entirely.
+     */
     private bearerToken;
+    /**
+     * The storage backend has historically returned HTTP 200 with an `{ error }`
+     * body on some failures; without this guard the SDK would resolve those as
+     * successful uploads/deletes. Treat any 2xx whose body carries a non-empty
+     * `error` as a failure.
+     */
+    private assertNoEmbeddedError;
     private req;
     list(params?: {
         prefix?: string;
@@ -1883,7 +1955,8 @@ declare class BrowserStorageBucketClient {
 declare class RagableBrowserStorageClient {
     private readonly options;
     private readonly fetchImpl;
-    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch);
+    private readonly ragableAuth;
+    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch, ragableAuth?: RagableAuth | null);
     from(bucketId: string): BrowserStorageBucketClient;
 }
 interface MailSendParams {
@@ -2156,6 +2229,13 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
     constructor(options: RagableBrowserClientOptions);
     /** Delegates to `database.from()`. Kept for back-compat — prefer `database.from()`. */
     from: <TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string) => PostgrestTableApi<Database, TableName>;
+    /**
+     * Resolves once the persisted session has been restored (and refreshed if it
+     * was expired). Await this before reading auth state at startup to avoid a
+     * logged-out flash, e.g. `const session = await client.ready()`. Resolves
+     * `null` when no auth group is configured or no session is stored.
+     */
+    ready(): Promise<AuthSession<AuthUser> | null>;
     destroy(): void;
 }
 declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;

package/dist/index.d.ts

@@ -708,7 +708,7 @@ declare class AuthBroadcastChannel {
     close(): void;
 }
 
-type AuthChangeEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "USER_UPDATED";
+type AuthChangeEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "TOKEN_REFRESH_FAILED" | "USER_UPDATED";
 type AuthUserMetadata = Record<string, unknown>;
 interface DefaultAuthUser<Metadata extends AuthUserMetadata = AuthUserMetadata> {
     id: string;
@@ -783,10 +783,26 @@ declare class RagableAuth<U extends object = DefaultAuthUser> {
     private listeners;
     private broadcast;
     private visibilityHandler;
-    private initialized;
+    /** Memoizes the one-shot restore so concurrent callers (constructor eager init,
+     *  every `onAuthStateChange` subscriber, `getSession`) share a single result.
+     *  Non-null also means "restore has started", replacing the old boolean flag. */
+    private initializePromise;
+    /** Bumped on every explicit session change (sign-in/out, refresh). The async
+     *  restore captures this and refuses to overwrite a newer session op that
+     *  landed while it was reading storage (e.g. a sign-out during page load). */
+    private sessionEpoch;
     constructor(config: RagableAuthConfig);
     private log;
+    /**
+     * Restore a persisted session (once). Memoized: every caller awaits the same
+     * promise, so the eager constructor init, `getSession`, and each
+     * `onAuthStateChange` subscriber's INITIAL_SESSION replay never race or
+     * double-restore. Does NOT emit `INITIAL_SESSION` globally — that event is
+     * delivered per-subscriber by `onAuthStateChange` (Supabase-parity), so a
+     * listener attached after restore still sees the existing session.
+     */
     initialize(): Promise<AuthSession<U> | null>;
+    private _initialize;
     signUp(credentials: AuthSignUpCredentials<MetadataForUser<U>>): Promise<PostgrestResult<{
         user: U;
         session: AuthSession<U>;
@@ -835,7 +851,14 @@ declare class RagableAuth<U extends object = DefaultAuthUser> {
         };
     };
     getAccessToken(): string | null;
-    getValidAccessToken(): Promise<string | null>;
+    /**
+     * Returns an access token guaranteed fresh for at least `refreshSkewSeconds`,
+     * refreshing (single-flight) if needed. Pass `force: true` to bypass the skew
+     * check and refresh now — used by the transport's 401 handler so a token the
+     * server rejected (key rotation, clock skew, early revocation) self-heals on
+     * retry instead of failing the call.
+     */
+    getValidAccessToken(force?: boolean): Promise<string | null>;
     getCurrentSession(): AuthSession<U> | null;
     register(body: {
         email: string;
@@ -891,7 +914,17 @@ declare class RagableAuth<U extends object = DefaultAuthUser> {
     private emit;
     private scheduleRefresh;
     private clearRefreshTimer;
+    /**
+     * Refresh the session, deduplicating concurrent callers onto one in-flight
+     * request. Side effects (persisting the new session, or clearing it and
+     * emitting SIGNED_OUT / TOKEN_REFRESH_FAILED) run exactly once inside the
+     * shared promise, so two callers can't double-emit. Resolves to the new
+     * session, or `null` when the refresh failed.
+     */
     singleFlightRefresh(refreshToken: string): Promise<AuthSession<U> | null>;
+    /** Clear the session locally and emit SIGNED_OUT after a definitively-rejected
+     *  refresh, so onAuthStateChange-driven UI redirects to login. */
+    private handleTerminalRefreshFailure;
     private _doRefresh;
     private setupVisibilityListener;
 }
@@ -1340,13 +1373,23 @@ type FunctionInvoker<F extends RagableFunctions = DefaultRagableFunctions> = {
 
 /** Canonical browser/server API base (`…/api`, no trailing slash). */
 declare function normalizeBrowserApiBase(): string;
-type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
+type BrowserDataAuthMode = "user" | "publicAnon" | "admin" | "auto";
 /**
- * Resolves how database requests are authorized. If `dataAuth` is omitted and a
- * static browser data key is configured (`dataStaticKey` / `getDataStaticKey`),
- * defaults to **`publicAnon`** so public apps can use shared collections without
- * sign-in. Use explicit **`dataAuth: "user"`** when you need JWT sessions; use
- * **`"admin"`** when the static key is a data-admin key.
+ * Resolves how database / storage requests are authorized.
+ *
+ * Default (when `dataAuth` is omitted):
+ * - **`auto`** when BOTH a static data key AND user auth (an `authGroupId` or a
+ *   `getAccessToken` callback) are configured — the generated-site case. This is
+ *   the Supabase model: send the signed-in user's JWT when a session exists, and
+ *   fall back to the public anon key for logged-out visitors. Without this, a
+ *   shipped anon key permanently shadows the user session, so owner/group/claim/
+ *   authenticated collection grants can never match a signed-in user.
+ * - **`publicAnon`** when only a static key is configured (no auth group) — a
+ *   purely public app.
+ * - **`user`** when neither — JWT-only.
+ *
+ * Set `dataAuth` explicitly to override: `"user"` (JWT required), `"publicAnon"`
+ * (anon key only, never upgrade), or `"admin"` (the static key is a data-admin key).
  */
 declare function effectiveDataAuth(options: RagableBrowserClientOptions): BrowserDataAuthMode;
 interface RagableBrowserClientOptions {
@@ -1461,6 +1504,12 @@ declare class RagableBrowserAuthClient<AuthUser extends object = DefaultAuthUser
     getSession(): Promise<PostgrestResult<{
         session: AuthSession<AuthUser> | null;
     }>>;
+    /**
+     * Returns a valid (auto-refreshed) access token for the current session, or
+     * `null` if signed out. The sanctioned way to obtain a token for a hand-rolled
+     * `fetch` to a custom endpoint — never read tokens out of storage yourself.
+     */
+    getValidAccessToken(): Promise<string | null>;
 }
 interface BrowserSqlQueryParams {
     databaseInstanceId?: string;
@@ -1556,6 +1605,15 @@ type CollectionRowWithMeta<Row extends Record<string, unknown> = Record<string,
 };
 declare function collectionRecordToRowWithMeta<Row extends Record<string, unknown>>(record: BrowserCollectionRecord<Row>): CollectionRowWithMeta<Row>;
 declare function collectionRecordsToRowWithMeta<Row extends Record<string, unknown>>(records: BrowserCollectionRecord<Row>[]): CollectionRowWithMeta<Row>[];
+/**
+ * Rows returned by a find: {@link CollectionRowWithMeta} when the params carry
+ * a literal `return: "flat"`, envelope {@link BrowserCollectionRecord}s
+ * otherwise. Keeps the default (envelope) call sites free of union-narrowing —
+ * `res.data[0].data` typechecks without a cast.
+ */
+type CollectionFindResult<Row extends Record<string, unknown>, Params> = Params extends {
+    return: "flat";
+} ? CollectionRowWithMeta<Row>[] : BrowserCollectionRecord<Row>[];
 type BrowserCollectionFindParams<Row extends Record<string, unknown> = Record<string, unknown>> = {
     where?: WhereInput<Row>;
     filters?: Array<{
@@ -1586,11 +1644,11 @@ declare class BrowserCollectionApi<Row extends Record<string, unknown> = Record<
      * Query collection rows. Prefer this over the deprecated `find` alias.
      * Use `return: "flat"` to get {@link CollectionRowWithMeta} without nested `.data`.
      */
-    findMany: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    findMany: <Params extends WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>>(whereOrParams?: Params) => Promise<PostgrestResult<CollectionFindResult<RowD<Row>, Params>>>;
     /**
      * @deprecated Use {@link BrowserCollectionApi.findMany} — same behavior.
      */
-    find: (whereOrParams?: WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[] | CollectionRowWithMeta<RowD<Row>>[]>>;
+    find: <Params extends WhereInput<RowD<Row>> | BrowserCollectionFindParams<RowD<Row>>>(whereOrParams?: Params) => Promise<PostgrestResult<CollectionFindResult<RowD<Row>, Params>>>;
     /**
      * At most one row, `data` is the record or `null` if none match (not an error).
      */
@@ -1811,10 +1869,24 @@ declare class BrowserStorageBucketClient {
     private readonly options;
     private readonly fetchImpl;
     private readonly bucketId;
-    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch, bucketId: string);
+    private readonly ragableAuth;
+    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch, bucketId: string, ragableAuth?: RagableAuth | null);
     private get authGroupId();
     private base;
+    /**
+     * Same credential resolution as the database client (see resolveDatabaseAuthBearer):
+     * in the generated-site default (`auto`), a signed-in user's auto-refreshed JWT
+     * is used so storage calls carry the user's identity; logged-out visitors fall
+     * back to the anon key. Previously storage ignored the managed session entirely.
+     */
     private bearerToken;
+    /**
+     * The storage backend has historically returned HTTP 200 with an `{ error }`
+     * body on some failures; without this guard the SDK would resolve those as
+     * successful uploads/deletes. Treat any 2xx whose body carries a non-empty
+     * `error` as a failure.
+     */
+    private assertNoEmbeddedError;
     private req;
     list(params?: {
         prefix?: string;
@@ -1883,7 +1955,8 @@ declare class BrowserStorageBucketClient {
 declare class RagableBrowserStorageClient {
     private readonly options;
     private readonly fetchImpl;
-    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch);
+    private readonly ragableAuth;
+    constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch, ragableAuth?: RagableAuth | null);
     from(bucketId: string): BrowserStorageBucketClient;
 }
 interface MailSendParams {
@@ -2156,6 +2229,13 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
     constructor(options: RagableBrowserClientOptions);
     /** Delegates to `database.from()`. Kept for back-compat — prefer `database.from()`. */
     from: <TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string) => PostgrestTableApi<Database, TableName>;
+    /**
+     * Resolves once the persisted session has been restored (and refreshed if it
+     * was expired). Await this before reading auth state at startup to avoid a
+     * logged-out flash, e.g. `const session = await client.ready()`. Resolves
+     * `null` when no auth group is configured or no session is stored.
+     */
+    ready(): Promise<AuthSession<AuthUser> | null>;
     destroy(): void;
 }
 declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;