@basictech/react 0.7.0 → 0.8.0-beta.1

package/.turbo/turbo-build.log

@@ -1,23 +1,24 @@
 
 
-> @basictech/react@0.7.0-beta.6 build
+> @basictech/react@0.7.0 build
 > tsup
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
-CLI tsup v7.2.0
+CLI tsup v8.5.1
 CLI Using tsup config: /Users/raz/codebook/basic/libs/client-ts/packages/react/tsup.config.ts
 CLI Target: es2022
 CLI Cleaning output folder
 CJS Build start
 ESM Build start
-ESM dist/index.mjs     55.69 KB
-ESM dist/index.mjs.map 116.91 KB
-ESM ⚡️ Build success in 21ms
-CJS dist/index.js     57.98 KB
-CJS dist/index.js.map 116.96 KB
-CJS ⚡️ Build success in 21ms
-DTS Build start
-DTS ⚡️ Build success in 1353ms
-DTS dist/index.d.ts  9.48 KB
-DTS dist/index.d.mts 9.48 KB
+ESM dist/index.mjs     60.82 KB
+ESM dist/index.mjs.map 128.64 KB
+ESM ⚡️ Build success in 30ms
+CJS dist/index.js     63.30 KB
+CJS dist/index.js.map 128.74 KB
+CJS ⚡️ Build success in 30ms
+DTS Build start
+DTS ⚡️ Build success in 908ms
+DTS dist/index.d.ts  11.15 KB
+DTS dist/index.d.mts 11.15 KB
+⠙

package/AUTH_IMPLEMENTATION_GUIDE.md

@@ -13,7 +13,7 @@ This guide provides comprehensive REST API specifications and requirements for i
    - [Session Management](#session-management)
    - [Password Management](#password-management)
    - [Email Verification](#email-verification)
-   - [Username Availability](#username-availability)
+   - [Handle Availability](#handle-availability)
    - [DID Resolution](#did-resolution)
 2. [OAuth2 Implementation](#oauth2-implementation)
    - [Discovery & Configuration](#discovery--configuration)
@@ -36,7 +36,7 @@ This guide provides comprehensive REST API specifications and requirements for i
 
 ## PDS Authentication
 
-PDS authentication provides username/password-based authentication with email verification, password reset, and decentralized identifiers (DIDs). This is meant for clients of the PDS server, usually a front-end.
+PDS authentication provides handle/password-based authentication with email verification, password reset, and decentralized identifiers (DIDs). This is meant for clients of the PDS server, usually a front-end.
 
 ---
 
@@ -44,7 +44,7 @@ PDS authentication provides username/password-based authentication with email ve
 
 **Endpoint:** `POST /auth/signup`
 
-Create a new user account with username and password.
+Create a new user account with handle and password.
 
 #### Request
 
@@ -54,7 +54,7 @@ Content-Type: application/json
 
 {
   "type": "password",
-  "username": "john_doe",
+  "handle": "john_doe",
   "password": "securepassword123",
   "email": "john@example.com",
   "name": "John Doe"
@@ -66,7 +66,7 @@ Content-Type: application/json
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `type` | string | Yes | Authentication type. Must be `"password"` |
-| `username` | string | Yes | Unique username (alphanumeric, underscores) |
+| `handle` | string | Yes | Unique handle (alphanumeric, 2-30 chars) |
 | `password` | string | Yes | User password (minimum 3 characters) |
 | `email` | string | No | User email address (for verification) |
 | `name` | string | No | User's display name |
@@ -78,7 +78,7 @@ Content-Type: application/json
 {
   "data": {
     "id": "acc_12345",
-    "username": "john_doe",
+    "handle": "john_doe.basic.id",
     "email": "john@example.com",
     "name": "John Doe",
     "created_at": "2025-09-29T10:00:00Z"
@@ -109,7 +109,7 @@ The verification token is valid for **24 hours**.
 
 **Endpoint:** `POST /auth/login`
 
-Authenticate with username and password to receive access and refresh tokens.
+Authenticate with handle and password to receive access and refresh tokens.
 
 #### Request
 
@@ -118,7 +118,7 @@ POST /auth/login HTTP/1.1
 Content-Type: application/json
 
 {
-  "username": "john_doe",
+  "handle": "john_doe",
   "password": "securepassword123"
 }
 ```
@@ -127,7 +127,7 @@ Content-Type: application/json
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `username` | string | Yes | User's username or email |
+| `handle` | string | Yes | User's handle or email |
 | `password` | string | Yes | User's password |
 
 #### Response
@@ -336,7 +336,7 @@ Content-Type: application/json
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `identifier` | string | Yes | User's email or username |
+| `identifier` | string | Yes | User's email or handle |
 
 #### Response
 
@@ -344,7 +344,7 @@ Content-Type: application/json
 ```json
 {
   "success": true,
-  "message": "If an account with that email/username exists, a password reset link has been sent"
+  "message": "If an account with that email/handle exists, a password reset link has been sent"
 }
 ```
 
@@ -507,23 +507,25 @@ Content-Type: application/json
 
 ---
 
-### Username Availability
+### Handle Availability
 
-**Endpoint:** `GET /auth/check-username`
+**Endpoint:** `GET /auth/check-handle`
 
-Check if a username is available for registration.
+Check if a handle is available for registration.
 
 #### Request
 
 ```http
-GET /auth/check-username?username=john_doe HTTP/1.1
+GET /auth/check-handle?handle=john_doe HTTP/1.1
 ```
 
+> **Backward compatibility:** The legacy `GET /auth/check-username` endpoint redirects to `/auth/check-handle`.
+
 #### Query Parameters
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `username` | string | Yes | Username to check |
+| `handle` | string | Yes | Handle to check |
 
 #### Response
 
@@ -938,7 +940,7 @@ Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
   "id": "acc_12345",
   "name": "John Doe",
   "email": "john@example.com",
-  "username": "john_doe"
+  "handle_bare": "john_doe"
 }
 ```
 
@@ -1001,7 +1003,7 @@ The server uses a hierarchical scope-based authorization system for fine-grained
 
 | Scope | Description |
 |-------|-------------|
-| `profile:read` | User profile information (name, username) |
+| `profile:read` | User profile information (name, handle) |
 | `email:read` | User's email address |
 | `openid:read` | OpenID Connect authentication |
 

package/changelog.md

@@ -1,5 +1,23 @@
 # 1.3.4
 
+## 0.8.0-beta.1
+
+### Minor Changes
+
+- uth updates
+
+## 0.8.0-beta.0
+
+### Minor Changes
+
+- Overhaul auth system: extract AuthManager, add PKCE, cross-tab sync, proactive token refresh, enriched error handling, and fix DELETE Content-Type issue
+
+## Unreleased
+
+### Patch Changes
+
+- **DBStatus:** Add `ERROR_WILL_RETRY` to align with dexie-syncable status code 4 (error but will retry). Export `DBStatus` enum from the package. Document all `DBStatus` values in readme, including when `ERROR_WILL_RETRY` occurs (e.g. expired token). Enables UI to show "Reconnecting…" or future token refresh on this state.
+
 ## 0.7.0
 
 ### Minor Changes
@@ -203,7 +221,6 @@
 - 96e0156: update schema validation
 - cda3d16: add schema validation
 - 2c898ae: update useQuery hook
-
   - no need to pass param as a function, can now enter query directly
   - defaults to empty array when loading
 
@@ -259,7 +276,6 @@
 ### Minor Changes
 
 - update useQuery hook
-
   - no need to pass param as a function, can now enter query directly
   - defaults to empty array when loading
 

package/dist/index.d.mts

@@ -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,12 +244,35 @@ 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 User = {
+    sub?: string;
+    name?: string;
+    email?: string;
+    picture?: string;
+};
+type AuthResult = {
+    success: boolean;
+    error?: string;
+    code?: string;
+};
+type GetTokenOptions = {
+    forceRefresh?: boolean;
 };
 
 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 = {
@@ -266,25 +300,12 @@ declare enum DBStatus {
     CONNECTING = "CONNECTING",
     ONLINE = "ONLINE",
     SYNCING = "SYNCING",
-    ERROR = "ERROR"
+    ERROR = "ERROR",
+    /** Sync reported an error but will retry (e.g. expired token). Used for status code 4 from dexie-syncable. */
+    ERROR_WILL_RETRY = "ERROR_WILL_RETRY",
+    /** Token expired; the SDK is refreshing and will reconnect automatically. */
+    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;
-    error?: string;
-    code?: string;
-};
 /**
  * Context type for useBasic hook
  */
@@ -292,10 +313,19 @@ type BasicContextType = {
     isReady: boolean;
     isSignedIn: boolean;
     user: User | null;
+    /** The user's DID (Decentralized Identifier), extracted from the access token `sub` claim */
+    did: string | null;
+    /** Space-separated scope string from the access token */
+    scope: string | null;
+    /** Check if a specific scope is granted (e.g., hasScope('profile')) */
+    hasScope: (scope: string) => boolean;
+    /** Returns scopes that were requested but not granted in the current token */
+    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;
@@ -314,4 +344,31 @@ type BasicContextType = {
 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 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, BasicProvider, type BasicProviderProps, 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 };

package/dist/index.d.ts

@@ -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,12 +244,35 @@ 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 User = {
+    sub?: string;
+    name?: string;
+    email?: string;
+    picture?: string;
+};
+type AuthResult = {
+    success: boolean;
+    error?: string;
+    code?: string;
+};
+type GetTokenOptions = {
+    forceRefresh?: boolean;
 };
 
 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 = {
@@ -266,25 +300,12 @@ declare enum DBStatus {
     CONNECTING = "CONNECTING",
     ONLINE = "ONLINE",
     SYNCING = "SYNCING",
-    ERROR = "ERROR"
+    ERROR = "ERROR",
+    /** Sync reported an error but will retry (e.g. expired token). Used for status code 4 from dexie-syncable. */
+    ERROR_WILL_RETRY = "ERROR_WILL_RETRY",
+    /** Token expired; the SDK is refreshing and will reconnect automatically. */
+    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;
-    error?: string;
-    code?: string;
-};
 /**
  * Context type for useBasic hook
  */
@@ -292,10 +313,19 @@ type BasicContextType = {
     isReady: boolean;
     isSignedIn: boolean;
     user: User | null;
+    /** The user's DID (Decentralized Identifier), extracted from the access token `sub` claim */
+    did: string | null;
+    /** Space-separated scope string from the access token */
+    scope: string | null;
+    /** Check if a specific scope is granted (e.g., hasScope('profile')) */
+    hasScope: (scope: string) => boolean;
+    /** Returns scopes that were requested but not granted in the current token */
+    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;
@@ -314,4 +344,31 @@ type BasicContextType = {
 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 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, BasicProvider, type BasicProviderProps, 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 };