@polyphron/viper-react 0.2.1 → 0.4.0

package/README.md

@@ -71,6 +71,17 @@ function SignIn() {
 
 ## The hooks
 
+With personal tokens or device sign-in enabled, `useAuth().auth` exposes
+`createToken`, `tokens`, `revokeToken`, `startDeviceSignIn`, `authorizeDevice`
+and `pollDeviceSignIn`. Polling an approved device saves its normal session,
+so `useUser()` updates. Only display the user code and verification URI;
+keep the device code private and honor each polling result's interval.
+
+With email change confirmation enabled, `useAuth()` exposes
+`auth.requestEmailChange(newEmail)` and `auth.confirmEmailChange(token)`.
+Both need the current user's session. After confirming, call `auth.me()`
+to refresh the email shown by `useUser()`.
+
 | Hook | What it gives you |
 | --- | --- |
 | `useViper()` | The `Viper` client — writes go through it: `viper.collection("posts").create(…)` |
@@ -78,6 +89,13 @@ function SignIn() {
 | `useRecord(collection, id, options)` | One record, same shape |
 | `useAuth(collection)` | `{ user, auth }` for an auth collection |
 | `useSession()` / `useUser()` | The session / the logged-in user, re-rendering on change |
+| `useSessionOf(client, read)` | The same for any client with `onSessionChange` (the admin client, say); `read` returns what to show, like `() => admin.user` |
+| `useAuthMethods({ collection?, enabled? })` | How to sign in here (methods, sign-up, sub-app branding), or `null` while it loads |
+| `useSessions()` | The user's active sessions: `{ sessions, error, loading, refresh, revoke, logoutEverywhere }` |
+| `useInvites()` | Invites the user sent: `{ invites, error, loading, refresh, invite, cancel }` |
+| `useTenants(name)` | The user's memberships of tenant collection `name`; never the last user's list |
+| `useRun(name, started, { every? })` | Follows a background workflow's run until it ends: `{ data, error, pending }` |
+| `useAppIdentity()` / `useAppManagement()` | The user's app role and ceilings; opt-in role and member edits. Both give `{ identity, error, loading, refresh }`, management adds `roles`, `members` and the writes. A 403 on the management calls keeps `identity` |
 | `useRealtime(topics, onEvent)` | Watch changes yourself; returns the connection status |
 | `useRealtimeStatus()` | `"closed"`, `"connecting"` or `"live"` |
 
@@ -95,6 +113,14 @@ flight, so lists don't flash.
 - With `live: true`, the list is also re-fetched once after the socket comes
   back from a drop, since events may have been missed while it was down.
 
+`useSessions`, `useInvites` and `useAppIdentity` all give `loading` (true
+until the first answer for this user), `error` (an `Error` or `null`) and
+`refresh()`, which resolves once the new answer is in. They key their state on
+the signed-in user, so after a user switch you never see the last user's data.
+`useLoaded(subject, load)` is the helper they and `useRecords` are built on;
+use it to write your own fetching hook. It returns the same `Query` shape as
+`useRecords`.
+
 `@polyphron/viper-client` is a peer dependency: install it next to this
 package, so the app and the hooks share one client.
 
@@ -200,6 +226,50 @@ collection.utils.refetch() // ask for the page again
 - `collection.utils.apply(event)` shows a change you made yourself (a save)
   without waiting for its realtime event.
 
+### Any endpoint as a collection
+
+For data that isn't records (settings, keys, logs, anything an endpoint hands
+back whole), `fetched(owner, options)` makes a TanStack DB collection from a
+fetch, and `useFetched(collection)` reads it as
+`{ data, error, isPending, isFetching, updatedAt, refetch }`.
+
+```tsx
+import { fetched, refetchFetched, useFetched } from "@polyphron/viper-react/db"
+
+const settings = (p: string) =>
+  fetched<Settings>(client, {
+    key: ["projects", p, "settings"],
+    fetch: (signal) => api.settings(p, { signal }),
+  })
+
+const { data } = useFetched(settings(projectId))
+
+await save(input)
+await refetchFetched(client, ["projects", projectId]) // every key under it
+```
+
+- The same `owner` and `key` always give the same collection, so every
+  reader shares one load. A list (pass `getKey`) keeps the server's order; a
+  single object is one row.
+- It loads again when told to (`refetchFetched` by key prefix, or
+  `collection.utils.refetch()`), on `refetchInterval` while read, and when
+  the window comes back after `staleTime` (30 seconds by default). Only
+  changed rows are rewritten, so the rest keep their identity.
+- `collection.utils.set(data)` puts in a save's answer with no request.
+  `await collection.utils.ready()` waits for the first load, from a route
+  loader say. `forgetFetched(owner, prefix)` drops collections (after a
+  delete).
+- Network errors retry twice; a "no" or "not found" doesn't. The error is
+  in `error`, and the last good data stays.
+- `useFetched(collection, { keepPrevious: true })` keeps the last data on
+  screen while a new collection (the next page, a new filter) loads.
+  `useFetchedAll(collections)` reads several, one per project say.
+
+The Viper dashboard reads the whole admin API this way, through
+`@polyphron/viper-react/db/admin` (`adminCollections(admin)`). That entry
+stays in the workspace, like the admin client it wraps, and isn't
+published.
+
 ### Recipe: typed collections, a join and an optimistic insert
 
 1. Write the types once with `viper typegen --out src/viper-types.ts` (see

package/dist/auth.d.ts

@@ -1,17 +1,79 @@
-import type { AuthService, RecordModel, Session } from "@polyphron/viper-client";
+import type { AuthMethods, AuthService, Invite, InviteInput, RecordModel, Session, UserSession } from "@polyphron/viper-client";
+/**
+ * The session of any client that announces changes (`Viper`, `ViperAdmin`),
+ * re-rendering when it changes. `read` returns what to show from the client,
+ * like `() => admin.user`. It must be stable between changes.
+ */
+export declare function useSessionOf<S>(client: {
+    onSessionChange(listener: () => void): () => void;
+}, read: () => S | null): S | null;
 /** The current session, re-rendering on login, logout and refresh. */
 export declare function useSession(): Session | null;
+/** The signed-in user's active sessions, with revoke and log-out actions. */
+export declare function useSessions(): {
+    sessions: UserSession[] | null;
+    error: Error | null;
+    loading: boolean;
+    refresh: () => Promise<void>;
+    revoke: (sessionId: string) => Promise<void>;
+    logoutEverywhere: () => Promise<void>;
+};
+/** The invites the signed-in user sent, with send and take-back actions. */
+export declare function useInvites(): {
+    invites: Invite[] | null;
+    error: Error | null;
+    loading: boolean;
+    refresh: () => Promise<void>;
+    invite: (input: InviteInput) => Promise<Invite>;
+    cancel: (id: string) => Promise<void>;
+};
 /** The logged-in user, or null when signed out. */
 export declare function useUser<T extends RecordModel = RecordModel>(): T | null;
 /**
- * The logins of one auth collection, plus the user they belong to.
+ * The project's sign-in, plus the user it belongs to. Without a
+ * collection it is the users table's (`viper.auth`); an old project with
+ * several auth collections names one.
  *
  * ```tsx
- * const { user, auth } = useAuth("users")
+ * const { user, auth } = useAuth()
  * await auth.loginWithPassword(email, password)
+ * await auth.requestEmailChange(newEmail)
+ * await auth.confirmEmailChange(token)
+ * await auth.me() // refresh the user after confirmation
+ * const proof = await auth.beginOAuth2("google", location.href)
+ * // Keep proof.codeVerifier across navigation to proof.url.
+ * const links = await auth.oauth2Links()
  * ```
  */
-export declare function useAuth<T extends RecordModel = RecordModel>(collection: string): {
+export declare function useAuth<T extends RecordModel = RecordModel>(collection?: string): {
     user: T | null;
     auth: AuthService<T>;
 };
+/**
+ * How to sign in here: the ways on offer, sign-up, and the sub-app's name
+ * and branding when the client has one (`new Viper({ app })`). Null while
+ * it loads, and when the load fails: the sign-in calls report their own
+ * errors. Name an auth `collection` when the project has several, and pass
+ * `enabled: false` to hold the request back. For a sign-in page.
+ *
+ * ```tsx
+ * const methods = useAuthMethods()
+ * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * ```
+ */
+export declare function useAuthMethods(options?: {
+    collection?: string;
+    enabled?: boolean;
+}): AuthMethods | null;
+/**
+ * The signed-in user's memberships of tenant collection `name` (like
+ * "orgs"), each with its role and the tenant under `expand.tenant`. Empty
+ * while signed out, null while it loads (and when the load fails). It
+ * loads again when the user changes, and never shows the last user's list.
+ *
+ * ```tsx
+ * const orgs = useTenants("orgs")
+ * return orgs?.map((m) => <li key={m.id}>{m.expand?.tenant?.name}</li>)
+ * ```
+ */
+export declare function useTenants(name: string): RecordModel[] | null;

package/dist/auth.js

@@ -1,24 +1,121 @@
-import { useSyncExternalStore } from "react";
+import { useCallback, useSyncExternalStore } from "react";
+import { asError, useLoaded } from "./loaded.js";
 import { useViper } from "./provider.js";
+/**
+ * The session of any client that announces changes (`Viper`, `ViperAdmin`),
+ * re-rendering when it changes. `read` returns what to show from the client,
+ * like `() => admin.user`. It must be stable between changes.
+ */
+export function useSessionOf(client, read) {
+    return useSyncExternalStore((listener) => client.onSessionChange(listener), read, () => null);
+}
 /** The current session, re-rendering on login, logout and refresh. */
 export function useSession() {
     const viper = useViper();
-    return useSyncExternalStore((listener) => viper.onSessionChange(listener), () => viper.session, () => null);
+    return useSessionOf(viper, () => viper.session);
+}
+/** The signed-in user's active sessions, with revoke and log-out actions. */
+export function useSessions() {
+    const viper = useViper();
+    const userId = useUser()?.id ?? null;
+    const { data, error, loading, reload } = useLoaded(userId, useCallback((signal) => userId ? viper.auth.sessions({ signal }) : Promise.resolve(null), [viper, userId]));
+    return {
+        sessions: data,
+        error: error ? asError(error) : null,
+        loading,
+        refresh: reload,
+        revoke: async (sessionId) => {
+            await viper.auth.revokeSession(sessionId);
+            await reload();
+        },
+        logoutEverywhere: () => viper.auth.logoutEverywhere(),
+    };
+}
+/** The invites the signed-in user sent, with send and take-back actions. */
+export function useInvites() {
+    const viper = useViper();
+    const userId = useUser()?.id ?? null;
+    const { data, error, loading, reload } = useLoaded(userId, useCallback((signal) => userId ? viper.auth.invites({ signal }) : Promise.resolve(null), [viper, userId]));
+    return {
+        invites: data,
+        error: error ? asError(error) : null,
+        loading,
+        refresh: reload,
+        invite: async (input) => {
+            const made = await viper.auth.invite(input);
+            await reload();
+            return made;
+        },
+        cancel: async (id) => {
+            await viper.auth.cancelInvite(id);
+            await reload();
+        },
+    };
 }
 /** The logged-in user, or null when signed out. */
 export function useUser() {
     return useSession()?.record ?? null;
 }
 /**
- * The logins of one auth collection, plus the user they belong to.
+ * The project's sign-in, plus the user it belongs to. Without a
+ * collection it is the users table's (`viper.auth`); an old project with
+ * several auth collections names one.
  *
  * ```tsx
- * const { user, auth } = useAuth("users")
+ * const { user, auth } = useAuth()
  * await auth.loginWithPassword(email, password)
+ * await auth.requestEmailChange(newEmail)
+ * await auth.confirmEmailChange(token)
+ * await auth.me() // refresh the user after confirmation
+ * const proof = await auth.beginOAuth2("google", location.href)
+ * // Keep proof.codeVerifier across navigation to proof.url.
+ * const links = await auth.oauth2Links()
  * ```
  */
 export function useAuth(collection) {
     const viper = useViper();
     const user = useUser();
-    return { user, auth: viper.collection(collection).auth };
+    const auth = collection
+        ? viper.collection(collection).auth
+        : viper.auth;
+    return { user, auth };
+}
+/**
+ * How to sign in here: the ways on offer, sign-up, and the sub-app's name
+ * and branding when the client has one (`new Viper({ app })`). Null while
+ * it loads, and when the load fails: the sign-in calls report their own
+ * errors. Name an auth `collection` when the project has several, and pass
+ * `enabled: false` to hold the request back. For a sign-in page.
+ *
+ * ```tsx
+ * const methods = useAuthMethods()
+ * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * ```
+ */
+export function useAuthMethods(options = {}) {
+    const viper = useViper();
+    const { collection, enabled = true } = options;
+    const { data } = useLoaded(`${collection ?? ""}/${enabled}`, useCallback((signal) => enabled
+        ? (collection
+            ? viper.collection(collection).auth
+            : viper.auth).methods({ signal })
+        : Promise.resolve(null), [viper, collection, enabled]));
+    return data;
+}
+/**
+ * The signed-in user's memberships of tenant collection `name` (like
+ * "orgs"), each with its role and the tenant under `expand.tenant`. Empty
+ * while signed out, null while it loads (and when the load fails). It
+ * loads again when the user changes, and never shows the last user's list.
+ *
+ * ```tsx
+ * const orgs = useTenants("orgs")
+ * return orgs?.map((m) => <li key={m.id}>{m.expand?.tenant?.name}</li>)
+ * ```
+ */
+export function useTenants(name) {
+    const viper = useViper();
+    const userId = useUser()?.id ?? "";
+    const { data } = useLoaded(`${name}/${userId}`, useCallback((signal) => viper.tenants(name, { signal }), [viper, name]));
+    return data;
 }

package/dist/db-fetch.d.ts

@@ -0,0 +1,121 @@
+import type { Collection, CollectionConfig } from "@tanstack/db";
+type Key = string | number;
+/** Names what a fetch is, like `["projects", id, "keys"]`. */
+export type FetchKey = readonly unknown[];
+/** Where a fetch stands. */
+export type FetchState = {
+    /** The row keys, in the server's order. */
+    order: Key[];
+    /** The last load's error, or null when it worked. */
+    error: unknown;
+    /** When the last good load finished (ms), or 0 before one. */
+    loadedAt: number;
+    /** True while a load is under way. */
+    fetching: boolean;
+};
+/** What a fetched collection adds under `collection.utils`. */
+export type FetchUtils<D> = {
+    /** Where the fetch stands now. */
+    state: () => FetchState;
+    /** Calls `listener` whenever `state()` changes. Returns the unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    /** Asks the server again. */
+    refetch: () => Promise<void>;
+    /** Resolves once a load has worked, or rejects if the first one failed. */
+    ready: () => Promise<void>;
+    /**
+     * Puts `data` in as if the server had sent it, with no request: the
+     * answer of a save, say.
+     */
+    set: (data: D) => void;
+    /** Counts a reader, so the timer and focus checks run. Returns the undo. */
+    watch: () => () => void;
+    /**
+     * Marks it stale: it loads again now if something reads it, else when
+     * something next does.
+     */
+    stale: () => Promise<void>;
+};
+/** A fetched collection: one list (or one object) from an endpoint. */
+export type Fetched<D> = Collection<Row<D>, Key, FetchUtils<D>> & {
+    /** "list" for an array, "one" for a single object held as one row. */
+    kind: "list" | "one";
+    key: FetchKey;
+};
+/** The row type of a fetch: an item of a list, or the one object. */
+export type Row<D> = D extends readonly (infer R extends object)[] ? R : D extends object ? D : never;
+/** How to fetch, and how fresh to keep it. */
+export type FetchOptions<D> = {
+    key: FetchKey;
+    fetch: (signal: AbortSignal) => Promise<D>;
+    /** Load again this often while read (ms), or from the data. */
+    refetchInterval?: number | false | ((data: D) => number | false);
+    /** How long a load counts as fresh (ms). Default 30 seconds. */
+    staleTime?: number;
+    /** Load a stale one again when the window comes back. Default true. */
+    refetchOnFocus?: boolean;
+};
+/**
+ * Options for `createCollection()`: what `fetch` gives, as rows. A list is
+ * keyed by `getKey`; a single object (leave `getKey` out) is one row.
+ */
+export declare function fetchCollectionOptions<D>(options: FetchOptions<D> & {
+    getKey?: (row: Row<D>) => Key;
+}): CollectionConfig<Row<D>, Key, never, FetchUtils<D>> & {
+    utils: FetchUtils<D>;
+};
+/**
+ * The fetched collection for `options.key` under `owner` (a client, say),
+ * made once and shared. For a list pass `getKey`; leave it out for one object.
+ */
+export declare function fetched<D>(owner: object, options: FetchOptions<D> & {
+    getKey?: (row: Row<D>) => Key;
+}): Fetched<D>;
+/**
+ * Loads again every fetched collection under `owner` whose key starts with
+ * `prefix`: the ones on screen now, the rest when next read. Call it after a
+ * change, the way you'd invalidate a query.
+ */
+export declare function refetchFetched(owner: object, prefix: FetchKey): Promise<void>;
+/**
+ * Drops every fetched collection under `owner` whose key starts with
+ * `prefix`, so nothing shows its data again (after a project is deleted).
+ */
+export declare function forgetFetched(owner: object, prefix: FetchKey): void;
+/** What `useFetched` gives back. */
+export type FetchedResult<D> = {
+    /** The list (or the one object), or undefined until it loads. */
+    data: D | undefined;
+    /** The last load's error, or null. */
+    error: Error | null;
+    isError: boolean;
+    /** True until the first load works or fails. */
+    isPending: boolean;
+    isSuccess: boolean;
+    /** True while any load is under way, the first or a later one. */
+    isFetching: boolean;
+    /** When the data last loaded (ms), or 0 before it has. */
+    updatedAt: number;
+    refetch: () => Promise<void>;
+};
+/**
+ * A fetched collection read as a list (or its one object), in the server's
+ * order. Pass null to read nothing yet. With `keepPrevious`, the last data
+ * stays on screen while a new collection (the next page, a new filter) loads.
+ *
+ * ```tsx
+ * const keys = useFetched(fetched(client, { key: ["keys"], fetch, getKey }))
+ * ```
+ */
+export declare function useFetched<D>(collection: Fetched<D> | null | undefined, options?: {
+    keepPrevious?: boolean;
+}): FetchedResult<D>;
+/**
+ * Several fetched collections at once (one per project, say), in the same
+ * order: `{ data, error }` each, with `data` undefined until it loads.
+ */
+export declare function useFetchedAll<D>(collections: readonly Fetched<D>[]): {
+    data: D | undefined;
+    error: Error | null;
+}[];
+export {};