@basictech/react 0.7.0 → 0.8.0-beta.2

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
+import react from 'react';
 export { useLiveQuery as useQuery } from 'dexie-react-hooks';
 
 /**
@@ -92,6 +92,10 @@ interface AuthError {
     status: number;
     message: string;
     response?: any;
+    /** Classifies the error for UI display (e.g. "session expired" vs "forbidden") */
+    errorType: 'expired' | 'forbidden' | 'revoked' | 'network' | 'unknown';
+    /** True if this error occurred after a retry with a refreshed token */
+    afterRetry: boolean;
 }
 /**
  * Custom error class for Remote DB API errors
@@ -102,13 +106,20 @@ declare class RemoteDBError extends Error {
     response?: any;
     constructor(message: string, status: number, response?: any);
 }
+/**
+ * Options for getToken (e.g. force refresh after 401)
+ */
+interface GetTokenOptions$1 {
+    /** When true, refresh the access token before returning (e.g. after server returned 401) */
+    forceRefresh?: boolean;
+}
 /**
  * Configuration for RemoteDB
  */
 interface RemoteDBConfig {
     serverUrl: string;
     projectId: string;
-    getToken: () => Promise<string>;
+    getToken: (options?: GetTokenOptions$1) => Promise<string>;
     schema?: any;
     /** Enable debug logging (default: false) */
     debug?: boolean;
@@ -233,57 +244,45 @@ declare const STORAGE_KEYS: {
     readonly AUTH_STATE: "basic_auth_state";
     readonly REDIRECT_URI: "basic_redirect_uri";
     readonly SERVER_URL: "basic_server_url";
+    readonly PDS_ENDPOINTS: "basic_pds_endpoints";
+    readonly LAST_CONNECT_REPORT: "basic_last_connect_report";
     readonly DEBUG: "basic_debug";
+    readonly CODE_VERIFIER: "basic_code_verifier";
 };
 
-type AuthConfig = {
-    scopes?: string | string[];
-    server_url?: string;
-    ws_url?: string;
+type User = {
+    sub?: string;
+    name?: string;
+    email?: string;
+    picture?: string;
 };
-type BasicProviderProps = {
-    children: React.ReactNode;
-    /**
-     * @deprecated Project ID is now extracted from schema.project_id.
-     * This prop is kept for backward compatibility but can be omitted.
-     */
-    project_id?: string;
-    /** The Basic schema object containing project_id and table definitions */
-    schema?: any;
-    debug?: boolean;
-    storage?: BasicStorage;
-    auth?: AuthConfig;
-    /**
-     * Database mode - determines which implementation is used
-     * - 'sync': Uses Dexie + WebSocket for local-first sync (default)
-     * - 'remote': Uses REST API calls directly to server
-     */
-    dbMode?: DBMode;
+type AuthResult = {
+    success: boolean;
+    error?: string;
+    code?: string;
+};
+type GetTokenOptions = {
+    forceRefresh?: boolean;
 };
+
 declare enum DBStatus {
     LOADING = "LOADING",
     OFFLINE = "OFFLINE",
     CONNECTING = "CONNECTING",
     ONLINE = "ONLINE",
     SYNCING = "SYNCING",
-    ERROR = "ERROR"
+    ERROR = "ERROR",
+    ERROR_WILL_RETRY = "ERROR_WILL_RETRY",
+    ERROR_TOKEN_EXPIRED = "ERROR_TOKEN_EXPIRED"
 }
-type User = {
-    name?: string;
-    email?: string;
-    id?: string;
-    primaryEmailAddress?: {
-        emailAddress: string;
-    };
-    fullName?: string;
-};
-/**
- * Auth result type for signInWithCode
- */
-type AuthResult = {
-    success: boolean;
+/** Snapshot of local schema vs server (for dev toolbar and debugging). */
+type BasicSchemaDevInfo = {
+    projectId: string | null;
+    localVersion: number | undefined;
+    status: string;
+    valid: boolean;
+    lastCheckedAt: number;
     error?: string;
-    code?: string;
 };
 /**
  * Context type for useBasic hook
@@ -292,26 +291,100 @@ type BasicContextType = {
     isReady: boolean;
     isSignedIn: boolean;
     user: User | null;
+    did: string | null;
+    scope: string | null;
+    hasScope: (scope: string) => boolean;
+    missingScopes: () => string[];
     signIn: () => Promise<void>;
+    signInWithHandle: (handle: string) => Promise<void>;
     signOut: () => Promise<void>;
     signInWithCode: (code: string, state?: string) => Promise<AuthResult>;
-    getToken: () => Promise<string>;
+    getToken: (options?: GetTokenOptions) => Promise<string>;
     getSignInUrl: (redirectUri?: string) => Promise<string>;
     db: BasicDB;
     dbStatus: DBStatus;
     dbMode: DBMode;
-    /** @deprecated Use isReady instead */
+    /** Local schema vs server status; null if no schema on the provider. */
+    devInfo: BasicSchemaDevInfo | null;
+    /** Re-run remote schema check (dev toolbar). */
+    refreshSchemaStatus: () => Promise<void>;
     isAuthReady: boolean;
-    /** @deprecated Use signIn instead */
     signin: () => Promise<void>;
-    /** @deprecated Use signOut instead */
     signout: () => Promise<void>;
-    /** @deprecated Use signInWithCode instead */
     signinWithCode: (code: string, state?: string) => Promise<AuthResult>;
-    /** @deprecated Use getSignInUrl instead */
     getSignInLink: (redirectUri?: string) => Promise<string>;
 };
-declare function BasicProvider({ children, project_id: project_id_prop, schema, debug, storage, auth, dbMode }: BasicProviderProps): react_jsx_runtime.JSX.Element;
 declare function useBasic(): BasicContextType;
 
-export { AuthConfig, AuthError, AuthResult, BasicContextType, BasicDB, BasicProvider, BasicProviderProps, BasicStorage, Collection, DBMode, LocalStorageAdapter, NotAuthenticatedError, RemoteCollection, RemoteDB, RemoteDBConfig, RemoteDBError, STORAGE_KEYS, useBasic };
+type AuthConfig = {
+    scopes?: string | string[];
+    /** @deprecated Use pds_url instead */
+    server_url?: string;
+    /** PDS URL for auth and data (default: https://pds.basic.id) */
+    pds_url?: string;
+    /** Admin server URL for connect reporting (default: https://api.basic.tech) */
+    admin_url?: string;
+    ws_url?: string;
+};
+type BasicProviderProps = {
+    children: react.ReactNode;
+    /**
+     * @deprecated Project ID is now extracted from schema.project_id.
+     * This prop is kept for backward compatibility but can be omitted.
+     */
+    project_id?: string;
+    /** The Basic schema object containing project_id and table definitions */
+    schema?: any;
+    debug?: boolean;
+    storage?: BasicStorage;
+    auth?: AuthConfig;
+    /**
+     * Database mode - determines which implementation is used
+     * - 'sync': Uses Dexie + WebSocket for local-first sync (default)
+     * - 'remote': Uses REST API calls directly to server
+     */
+    dbMode?: DBMode;
+    /** Show floating dev toolbar (localhost, NODE_ENV=development, or debug=true). */
+    devToolbar?: boolean;
+};
+declare function BasicProvider({ children, project_id: project_id_prop, schema, debug, storage, auth, dbMode, devToolbar, }: BasicProviderProps): react_jsx_runtime.JSX.Element;
+
+type BasicDevToolbarProps = {
+    /** When false, toolbar does not render. Defaults to true when used standalone. */
+    enabled?: boolean;
+    /** Same as BasicProvider `debug` — when true, toolbar shows even off localhost. */
+    debug?: boolean;
+};
+/**
+ * Floating dev-only toolbar: auth, DB/sync, and schema status. Requires `BasicProvider` with `debug` or localhost / NODE_ENV=development for visibility unless `enabled` is forced.
+ */
+declare function BasicDevToolbar({ enabled, debug }: BasicDevToolbarProps): react_jsx_runtime.JSX.Element | null;
+
+type ResolvedDid = {
+    did: string;
+    handle?: string;
+    didDocument: Record<string, unknown>;
+    pdsUrl: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+};
+/**
+ * Convert a did:web DID to the HTTPS URL where its DID document lives.
+ *
+ * did:web:pds.basic.id:did:abc123 -> https://pds.basic.id/did/abc123/did.json
+ * did:web:example.com             -> https://example.com/.well-known/did.json
+ */
+declare function resolveDidWebUrl(did: string): string | null;
+/**
+ * Fetch a DID document by DID, extract the PDS URL, and discover OAuth endpoints.
+ */
+declare function resolveDid(did: string): Promise<ResolvedDid>;
+/**
+ * Resolve a handle (e.g. "alice.basic.id") to a DID and discover PDS + OAuth endpoints.
+ *
+ * Fetches https://{handle}/.well-known/did.json per the did:web spec.
+ */
+declare function resolveHandle(handle: string): Promise<ResolvedDid>;
+
+export { type AuthConfig, type AuthError, type AuthResult, type BasicContextType, type BasicDB, BasicDevToolbar, type BasicDevToolbarProps, BasicProvider, type BasicProviderProps, type BasicSchemaDevInfo, type BasicStorage, type Collection, type DBMode, DBStatus, type GetTokenOptions$1 as GetTokenOptions, LocalStorageAdapter, NotAuthenticatedError, RemoteCollection, RemoteDB, type RemoteDBConfig, RemoteDBError, type ResolvedDid, STORAGE_KEYS, resolveDid, resolveDidWebUrl, resolveHandle, useBasic };