permdock 0.1.0 → 0.3.0

package/dist/provider-CSQd7m92.js

@@ -0,0 +1,52 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { t as emptySnapshot } from "./from-snapshot-CTLijvdm.js";
+import { t as adapterStore } from "./store-options-ByhZq1jV.js";
+import { i as PermDockStoreContext, n as useKeyed, r as PermDockSnapshotPromiseContext, t as useLiveOptions } from "./live-options-H2eG8dfJ.js";
+import { useLayoutEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/provider.tsx
+function PermDockProvider(props) {
+	const promise = props.snapshotPromise ?? null;
+	const suspend = props.suspend === true;
+	const awaiting = promise !== null && !suspend;
+	const live = useLiveOptions(props);
+	const store = useKeyed(() => adapterStore(compact({
+		endpoint: props.endpoint,
+		snapshotUrl: props.snapshotUrl,
+		approvals: props.approvals,
+		tenant: props.tenant,
+		fetch: live.fetch,
+		headers: live.headers,
+		maxAge: props.maxAge,
+		verifier: live.verifier,
+		awaiting,
+		passCache: true
+	}), props.snapshot ?? emptySnapshot()), [
+		props.snapshot,
+		props.endpoint,
+		props.snapshotUrl,
+		props.approvals,
+		props.tenant,
+		live.fetch,
+		live.headers,
+		props.maxAge,
+		live.verifier,
+		awaiting
+	]);
+	useLayoutEffect(() => {
+		if (promise !== null && !suspend) store.track(promise);
+	}, [
+		store,
+		promise,
+		suspend
+	]);
+	return /* @__PURE__ */ jsx(PermDockStoreContext, {
+		value: store,
+		children: /* @__PURE__ */ jsx(PermDockSnapshotPromiseContext, {
+			value: suspend ? promise : null,
+			children: props.children
+		})
+	});
+}
+//#endregion
+export { PermDockProvider as t };

package/dist/{provider-wTAUda2v.d.ts → provider-DZY281jO.d.ts}

@@ -1,4 +1,4 @@
-import { o as PermDockProviderProps } from "./types-DbWdEfcm.js";
+import { t as PermDockProviderProps } from "./types-BnIEz1sU.js";
 import { ReactElement } from "react";
 //#region src/react/provider.d.ts
 declare function PermDockProvider(props: PermDockProviderProps): ReactElement;

package/dist/provider-store-Cfbvo4DE.js

@@ -0,0 +1,43 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { t as emptySnapshot } from "./from-snapshot-CTLijvdm.js";
+import { i as isPromiseLike, t as adapterStore } from "./store-options-ByhZq1jV.js";
+//#region src/client/provider-store.ts
+/**
+* Store options that read `read()` on every request, so a rotated token, a
+* new `fetch` or a new verifier applies without rebuilding the store. A
+* verifier is wired only when one is present at creation: it switches the
+* store to signed snapshots.
+*/
+function liveOptions(read) {
+	return compact({
+		headers: () => read().headers,
+		fetch: (...args) => (read().fetch ?? fetch)(...args),
+		verifier: read().verifier === void 0 ? void 0 : { verify: (token, expectations) => {
+			const current = read().verifier;
+			return current === void 0 ? Promise.reject(/* @__PURE__ */ new Error("PermDock: the verifier option was removed.")) : current.verify(token, expectations);
+		} }
+	});
+}
+/**
+* The store a Vue, Svelte or Solid provider owns. A promised snapshot keeps
+* it `pending` until the promise settles; `undefined` starts empty.
+*/
+function providerStore(options, read, snapshot) {
+	const promised = isPromiseLike(snapshot);
+	const store = adapterStore(compact({
+		endpoint: options.endpoint,
+		snapshotUrl: options.snapshotUrl,
+		approvals: options.approvals,
+		tenant: options.tenant,
+		maxAge: options.maxAge,
+		...liveOptions(read)
+	}), promised || snapshot === void 0 ? emptySnapshot() : snapshot);
+	if (promised) store.follow(snapshot);
+	return store;
+}
+/** Refreshes for the tenant a reactive `tenant` option switched to; a failed refresh keeps the current answers. */
+function switchTenant(store, tenant) {
+	if (tenant !== void 0) store.get().refresh({ tenant }).catch(() => void 0);
+}
+//#endregion
+export { switchTenant as n, providerStore as t };

package/dist/react/index.d.ts

@@ -1,6 +1,8 @@
-import { a as requiredPlans, i as describe } from "../describe-DernyItf.js";
-import { t as approvalHeaders } from "../headers-C8SHQccD.js";
-import { a as FilterResult, c as PermissionState, d as TenantView, i as ClientStatus, l as ProtectedProps, n as ApprovalState, o as PermDockProviderProps, r as ClientPermDock, s as PermissionSet, t as ApprovalHandle, u as SubjectView } from "../types-DbWdEfcm.js";
-import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-BuPAycJT.js";
-import { t as PermDockProvider } from "../provider-wTAUda2v.js";
+import { n as requiredPlans } from "../problem-details-DX075l9V.js";
+import { i as describe } from "../describe-DMYiCjJV.js";
+import { t as approvalHeaders } from "../headers-Cf-zWvsO.js";
+import { a as FilterResult, c as SubjectView, i as ClientStatus, l as TenantView, n as ApprovalState, o as PermissionSet, r as ClientPermDock, s as PermissionState, t as ApprovalHandle } from "../types-CKNSyIf_.js";
+import { n as ProtectedProps, t as PermDockProviderProps } from "../types-BnIEz1sU.js";
+import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-BdnIEFkY.js";
+import { t as PermDockProvider } from "../provider-DZY281jO.js";
 export { type ApprovalHandle, type ApprovalState, type ClientPermDock, type ClientStatus, type FilterResult, PermDockProvider, type PermDockProviderProps, type PermissionSet, type PermissionState, Protected, type ProtectedProps, type SubjectView, type TenantView, approvalHeaders, describe, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissions, useRoles, useSubject, useTenant };

package/dist/react/index.js

@@ -1,6 +1,7 @@
 "use client";
-import { n as requiredPlans, t as describe } from "../describe-Bt1YD5uS.js";
-import { t as approvalHeaders } from "../headers-B5RRv3Xm.js";
-import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-B4K3BKoX.js";
-import { t as PermDockProvider } from "../provider-_wx46HpB.js";
+import { r as requiredPlans } from "../problem-details-_AMOYz-w.js";
+import { t as describe } from "../describe-B_gVZEVi.js";
+import { t as approvalHeaders } from "../headers-BZSDieNT.js";
+import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-utU-SLuy.js";
+import { t as PermDockProvider } from "../provider-CSQd7m92.js";
 export { PermDockProvider, Protected, approvalHeaders, describe, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissions, useRoles, useSubject, useTenant };

package/dist/react/provider-client.d.ts

@@ -1,2 +1,2 @@
-import { t as PermDockProvider } from "../provider-wTAUda2v.js";
+import { t as PermDockProvider } from "../provider-DZY281jO.js";
 export { PermDockProvider };

package/dist/react/provider-client.js

@@ -1,3 +1,3 @@
 "use client";
-import { t as PermDockProvider } from "../provider-_wx46HpB.js";
+import { t as PermDockProvider } from "../provider-CSQd7m92.js";
 export { PermDockProvider };

package/dist/react-native/index.d.ts

@@ -1,10 +1,92 @@
-import { Et as TokenVerifier, gt as Snapshot } from "../policy-CInmNGkM.js";
-import { a as requiredPlans, i as describe } from "../describe-DernyItf.js";
-import { t as approvalHeaders } from "../headers-C8SHQccD.js";
-import { a as FilterResult, c as PermissionState, d as TenantView, i as ClientStatus, l as ProtectedProps, n as ApprovalState, r as ClientPermDock, s as PermissionSet, t as ApprovalHandle, u as SubjectView } from "../types-DbWdEfcm.js";
-import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-BuPAycJT.js";
-import { t as ClientStore } from "../store-Bq90395i.js";
+import { At as SnapshotSource, Dr as CustomRole, Ft as TokenVerifier, Mr as Membership, Tt as Snapshot, pt as LocalSnapshotManifest } from "../policy-IB6yxpC3.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { n as requiredPlans } from "../problem-details-DX075l9V.js";
+import { i as describe } from "../describe-DMYiCjJV.js";
+import { t as parseLocalSnapshotManifest } from "../parse-local-manifest-JLnaBH0S.js";
+import { t as approvalHeaders } from "../headers-Cf-zWvsO.js";
+import { a as FilterResult, c as SubjectView, i as ClientStatus, l as TenantView, n as ApprovalState, o as PermissionSet, r as ClientPermDock, s as PermissionState, t as ApprovalHandle } from "../types-CKNSyIf_.js";
+import { n as ProtectedProps } from "../types-BnIEz1sU.js";
+import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-BdnIEFkY.js";
+import { t as ClientStore } from "../store-jOBYpiXC.js";
 import { ReactElement, ReactNode } from "react";
+//#region src/react-native/guards.d.ts
+/** `true` once the provider has a snapshot to answer from: storage was read or a seed was given. Hide the splash screen on it. */
+export declare function useSnapshotReady(): boolean;
+/**
+ * A boolean for `Stack.Protected` and `Tabs.Protected`: `false` while the
+ * snapshot is pending, `true` only when every permission is allowed for
+ * `data`.
+ */
+export declare function usePermissionGuard(permission: Permission | readonly Permission[], data?: unknown): boolean;
+//#endregion
+//#region src/react-native/local.d.ts
+/** What the device holds for the signed-in user, read from its local database. */
+type LocalSnapshotData = {
+  readonly principal: {
+    readonly id: string;
+    /** Global roles, declared or platform custom roles. */
+    readonly roles?: readonly string[];
+    readonly plans?: readonly string[];
+    /** The active tenant: the first scope's instance the UI shows. */
+    readonly tenant?: string;
+    readonly memberships?: readonly Membership[];
+    /** Attributes conditions read, such as `claims` for `principal.claims.team_ids`. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+  } | null;
+  /** The tenant's custom roles, in the shape a `RoleSource` returns. */
+  readonly customRoles?: readonly CustomRole[];
+};
+type LocalSnapshotOptions = {
+  /** `localSnapshotManifest(policy)`, written at build time. */
+  readonly manifest: LocalSnapshotManifest;
+  readonly read: () => LocalSnapshotData | Promise<LocalSnapshotData>;
+  /** Calls the listener when the rows `read` reads change; returns the unsubscribe. */
+  readonly subscribe?: (listener: () => void) => () => void;
+};
+/**
+ * The snapshot a server would send for `data`, built from the manifest. It
+ * drives UI guards only: the server still decides every request.
+ */
+export declare function buildLocalSnapshot(manifest: LocalSnapshotManifest, data: LocalSnapshotData, now?: number): Snapshot;
+/**
+ * A snapshot source over the device's own membership rows (SQLite, a
+ * PowerSync or Electric replica): offline, the UI guards answer from them.
+ */
+export declare function localSnapshot(options: LocalSnapshotOptions): SnapshotSource;
+//#endregion
+//#region src/react-native/powersync.d.ts
+/** The `PowerSyncDatabase` methods `powersyncSource` calls. */
+type PowerSyncWatchable = {
+  getAll(sql: string, parameters?: unknown[]): Promise<unknown[]>;
+  watch(sql: string, parameters: unknown[] | undefined, handler: {
+    onResult(result: unknown): void;
+    onError?(error: Error): void;
+  }, options: {
+    readonly signal: AbortSignal;
+  }): void;
+};
+/** One local query: SQL over the synced tables and its parameters. */
+type PowerSyncQuery = {
+  readonly sql: string;
+  readonly parameters?: readonly unknown[];
+};
+type PowerSyncSourceOptions<Q extends string> = {
+  /** `localSnapshotManifest(policy)`, as `permdock powersync generate` writes it to `powersync.manifest`. */
+  readonly manifest: LocalSnapshotManifest;
+  /** The queries over the `permdock_*` streams' tables; each one is watched. */
+  readonly queries: Readonly<Record<Q, PowerSyncQuery>>;
+  /** Maps the rows of each query to the signed-in user's memberships and roles. */
+  readonly read: (rows: Readonly<Record<Q, readonly unknown[]>>) => LocalSnapshotData;
+};
+/**
+ * A `localSnapshot` source over a PowerSync database: `get` runs every query
+ * with `db.getAll`, and a `db.watch` per query reports changes. A watch
+ * result with unchanged content re-renders nothing (`connectSource`). The source
+ * takes the database as an argument; `permdock/react-native` never imports
+ * `@powersync/*`.
+ */
+export declare function powersyncSource<Q extends string>(db: PowerSyncWatchable, options: PowerSyncSourceOptions<Q>): SnapshotSource;
+//#endregion
 //#region src/react-native/types.d.ts
 type PermDockStorage = {
   getItem(key: string): string | null | Promise<string | null>;
@@ -12,16 +94,31 @@ type PermDockStorage = {
   removeItem(key: string): void | Promise<void>;
 };
 type NativeRevalidate = "launch" | "focus" | number;
+/**
+ * Calls `listener` when the app changes state; `active` is `false` when it
+ * goes to the background. A listener called without an argument counts as
+ * a return to the foreground.
+ */
+type SubscribeForeground = (listener: (active?: boolean) => void) => () => void;
+/** Calls `listener` with `false` when the device loses connectivity and `true` when it returns. */
+type SubscribeOnline = (listener: (online: boolean) => void) => () => void;
 type NativePermDockProviderProps = {
   readonly storage: PermDockStorage;
+  /**
+   * The signed-in principal's id, or `null` when nobody is signed in. Only a
+   * persisted snapshot for this id is read or written; `null` clears storage.
+   */
+  readonly subjectId: string | null;
   readonly snapshot?: Snapshot | string;
   readonly snapshotUrl?: string;
+  /** Hydrates from the device's own rows (`localSnapshot`); with `snapshotUrl` too, the latest answer wins. */
+  readonly source?: SnapshotSource;
   readonly endpoint?: string;
   readonly approvals?: string;
   readonly tenant?: string;
-  readonly subjectId?: string;
   readonly revalidate?: NativeRevalidate;
-  readonly subscribeForeground?: (listener: () => void) => () => void;
+  readonly subscribeForeground?: SubscribeForeground;
+  readonly subscribeOnline?: SubscribeOnline;
   readonly fetch?: typeof fetch;
   readonly headers?: Readonly<Record<string, string>>;
   readonly maxAge?: number;
@@ -35,8 +132,67 @@ export declare function PermDockProvider(props: NativePermDockProviderProps): Re
 //#region src/react-native/storage.d.ts
 export declare function memoryStorage(initial?: Readonly<Record<string, string>>): PermDockStorage;
 //#endregion
+//#region src/react-native/storage-adapters.d.ts
+/** The `expo-secure-store` functions `secureStoreStorage` calls. */
+type SecureStoreModule = {
+  getItem(key: string, options?: object): string | null;
+  setItem(key: string, value: string, options?: object): void;
+  deleteItemAsync(key: string, options?: object): Promise<void>;
+};
+/** The `react-native-mmkv` instance methods `mmkvStorage` calls: `remove` (v4) or `delete` (v3). */
+type MmkvInstance = {
+  getString(key: string): string | undefined;
+  set(key: string, value: string): void;
+} & ({
+  remove(key: string): unknown;
+} | {
+  delete(key: string): unknown;
+});
+/**
+ * A `PermDockStorage` over `expo-secure-store`. Values are split into chunks
+ * of at most 2048 bytes under `<key>.<n>`; `<key>` holds the chunk count and
+ * is written last, so an interrupted write reads as absent.
+ */
+export declare function secureStoreStorage(store: SecureStoreModule, options?: object): PermDockStorage;
+/** A synchronous `PermDockStorage` over a `react-native-mmkv` instance: the first frame already has the snapshot. */
+export declare function mmkvStorage(mmkv: MmkvInstance): PermDockStorage;
+//#endregion
+//#region src/react-native/subscriptions.d.ts
+/** The `AppState` export of `react-native`, as `appStateForeground` calls it. */
+type AppStateModule = {
+  addEventListener(type: "change", listener: (state: string) => void): {
+    remove(): void;
+  };
+};
+/** The default export of `@react-native-community/netinfo`, as `netInfoOnline` calls it. */
+type NetInfoModule = {
+  addEventListener(listener: (state: {
+    readonly isConnected: boolean | null;
+    readonly isInternetReachable?: boolean | null;
+  }) => void): () => void;
+};
+/**
+ * `subscribeForeground` over `AppState`: `active` returns to the foreground
+ * and `background` leaves it. iOS `inactive` (a system sheet over the app) is
+ * neither.
+ */
+export declare function appStateForeground(appState: AppStateModule): SubscribeForeground;
+/** `subscribeOnline` over NetInfo. An unknown (`null`) connection counts as online. */
+export declare function netInfoOnline(netInfo: NetInfoModule): SubscribeOnline;
+//#endregion
 //#region src/react-native/store.d.ts
-type NativeStoreOptions = Omit<NativePermDockProviderProps, "children">;
+type NativeStoreOptions = Omit<NativePermDockProviderProps, "children" | "headers"> & {
+  readonly headers?: Readonly<Record<string, string>> | (() => Readonly<Record<string, string>> | undefined);
+  /** A store this one replaces: its snapshot and tenant seed this store, so guards do not flip while it boots. */
+  readonly previous?: ClientStore;
+};
+/**
+ * Hydrates `store` from `source` now, on every change it reports and on each
+ * return to the foreground. Only the latest read applies; a read with
+ * unchanged content re-renders nothing, and a failed read keeps the current
+ * snapshot. Returns the unsubscribe.
+ */
+export declare function connectSource(store: ClientStore, source: SnapshotSource, subscribeForeground?: SubscribeForeground): () => void;
 export declare function createNativeStore(options: NativeStoreOptions): ClientStore;
 //#endregion
-export { type ApprovalHandle, type ApprovalState, type ClientPermDock, type ClientStatus, type FilterResult, type NativePermDockProviderProps, type NativeRevalidate, type PermDockStorage, type PermissionSet, type PermissionState, Protected, type ProtectedProps, type SubjectView, type TenantView, approvalHeaders, describe, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissions, useRoles, useSubject, useTenant };
+export { type AppStateModule, type ApprovalHandle, type ApprovalState, type ClientPermDock, type ClientStatus, type FilterResult, type LocalSnapshotData, type LocalSnapshotManifest, type LocalSnapshotOptions, type MmkvInstance, type NativePermDockProviderProps, type NativeRevalidate, type NetInfoModule, type PermDockStorage, type PermissionSet, type PermissionState, type PowerSyncQuery, type PowerSyncSourceOptions, type PowerSyncWatchable, Protected, type ProtectedProps, type SecureStoreModule, type SnapshotSource, type SubjectView, type SubscribeForeground, type SubscribeOnline, type TenantView, approvalHeaders, describe, parseLocalSnapshotManifest, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissions, useRoles, useSubject, useTenant };