@rool-dev/sdk 0.11.3-dev.5dfa2e5 → 0.11.3-dev.7c57c94

package/README.md

@@ -4,9 +4,8 @@ TypeScript SDK for Rool, a persistent collaborative workspace for objects, AI-as
 
 Core primitives:
 
-- **Spaces** — containers for objects, schema, metadata, channels, collaborators, and files.
-- **Channels** — named contexts within a space for object operations and AI conversations.
-- **Conversations** — independent interaction histories within a channel.
+- **Spaces** — containers for objects, schema, metadata, conversations, collaborators, and files.
+- **Conversations** — independent interaction histories in a space.
 - **Objects** — JSON records addressed by object paths such as `/space/article/welcome.json`.
 - **Files** — user-visible files stored under `/rool-drive/...` through WebDAV.
 
@@ -31,36 +30,36 @@ async function main() {
   }
 
   const space = await client.createSpace('Solar System');
-  const channel = await space.openChannel('main');
+  const conversation = space.conversation('main');
 
-  await channel.createCollection('body', [
+  await conversation.createCollection('body', [
     { name: 'name', type: { kind: 'string' } },
     { name: 'mass', type: { kind: 'string' } },
     { name: 'radius', type: { kind: 'string' } },
     { name: 'orbits', type: { kind: 'maybe', inner: { kind: 'ref' } } },
   ]);
 
-  const { object: sun } = await channel.putObject('/space/body/sun.json', {
+  const { object: sun } = await conversation.putObject('/space/body/sun.json', {
     name: 'Sun',
     mass: '1 solar mass',
     radius: '696,340 km',
   });
 
-  const { object: earth } = await channel.putObject('/space/body/earth.json', {
+  const { object: earth } = await conversation.putObject('/space/body/earth.json', {
     name: 'Earth',
     mass: '1 Earth mass',
     radius: '6,371 km',
     orbits: sun.path,
   });
 
-  const { message, objects } = await channel.prompt(
+  const { message, objects } = await conversation.prompt(
     'Add the other planets in our solar system, each referencing the Sun.'
   );
 
   console.log(message);
   console.log(`Modified ${objects.length} objects`);
 
-  const loadedEarth = await channel.getObject(earth.path);
+  const loadedEarth = await space.getObject(earth.path);
   console.log(loadedEarth?.body.name);
 
   space.close();
@@ -142,6 +141,74 @@ if (!authenticated) {
 if (!authenticated) throw new Error('Login required');
 ```
 
+### Native (Capacitor, Cordova, Tauri, ...)
+
+Use the native PKCE provider for JS app shells that sign in through an external
+system browser. `login()`/`signup()` open the auth server's `/authorize` page
+via the `openExternal` callback you supply; when the deep link returns, feed it
+to `client.handleAuthRedirect(url)` from your platform's deep-link handler. The
+code is exchanged for a session at `/token` and tokens are stored like the
+browser provider.
+
+```typescript
+import { RoolClient, NativePkceAuthProvider } from '@rool-dev/sdk';
+import { Browser } from '@capacitor/browser';
+import { App } from '@capacitor/app';
+
+const client = new RoolClient({
+  authProvider: new NativePkceAuthProvider({
+    redirectUri: 'roolandroidauth://auth/callback', // must match the server allowlist
+    defaultProvider: 'google',                       // 'google' | 'apple'
+    openExternal: (url) => Browser.open({ url }),
+  }),
+});
+
+// Complete sign-in when the OS hands the app its deep link.
+App.addListener('appUrlOpen', async ({ url }) => {
+  if (await client.handleAuthRedirect(url)) {
+    await Browser.close();
+    // Now authenticated — refresh your UI.
+  }
+});
+
+if (!(await client.initialize())) {
+  // Opens the system browser; completion arrives via the listener above.
+  await client.login('My App'); // pass { provider: 'apple' } to override the default
+}
+```
+
+#### Email + password and magic links (native)
+
+The native provider also supports email/password sign-in and magic links —
+no system browser, the server returns the token set as JSON directly.
+
+```typescript
+// Password sign-in
+const result = await client.signInWithPassword(email, password);
+if (result.status === 'signed_in') {
+  // authenticated — refresh your UI
+} else {
+  // status === 'verify_required': the email isn't verified yet and the server
+  // has emailed a magic link. Tell the user to check their inbox.
+}
+
+// Or request a magic link explicitly
+await client.requestMagicLink(email);
+```
+
+The magic link carries a `?verify=<token>` param; complete sign-in by passing
+that token to `client.verify(token)` once the link lands back in the app.
+
+> **⚠️ Magic links open the website, not the app, until Universal Links / App
+> Links are configured.** The emailed link is an `https://` URL for the Rool
+> web app. On native, an `https` link only re-opens your app if you've set up
+> [iOS Universal Links](https://developer.apple.com/ios/universal-links/) /
+> [Android App Links](https://developer.android.com/training/app-links) for that
+> domain (custom-scheme deep links don't apply to email links). **Without that
+> setup the magic link completes sign-in in the browser/website, not in the
+> native app** — so for now treat magic links on native as a website hand-off,
+> and prefer password or social sign-in for an in-app experience.
+
 ### Auth API
 
 | Method | Description |
@@ -150,6 +217,9 @@ if (!authenticated) throw new Error('Login required');
 | `login(appName, params?): Promise<void>` | Start login flow. |
 | `signup(appName, params?): Promise<void>` | Start signup flow. |
 | `verify(token): Promise<boolean>` | Complete email verification token flow; returns `false` when the active auth provider does not implement verification. |
+| `handleAuthRedirect(url): Promise<boolean>` | Complete a native PKCE sign-in from a deep-link callback URL. Returns `false` when the active auth provider does not implement it. |
+| `signInWithPassword(email, password): Promise<PasswordSignInResult>` | Email + password sign-in (native provider). Resolves `{ status: 'signed_in' }`, or `{ status: 'verify_required' }` when the email is unverified (a magic link was emailed). Rejects on bad credentials. |
+| `requestMagicLink(email): Promise<void>` | Email the user a magic sign-in link (native provider). See the caveat below — on native the link opens the **website**, not the app, until Universal Links / App Links are configured. |
 | `logout(): void` | Clear auth state and close open spaces. |
 | `isAuthenticated(): Promise<boolean>` | Whether credentials are held locally. No network call — a server outage does not read as logged out. |
 | `getAuthUser(): AuthUser` | Return auth identity decoded from the token. |
@@ -159,58 +229,57 @@ if (!authenticated) throw new Error('Login required');
 
 A temporarily unreachable server never reads as "logged out". `initialize()` reports authentication from stored credentials, so on an offline start it can return `true` while `currentUser` is still `null` and user storage is empty — the SDK keeps reconnecting in the background and hydrates both automatically once the server is reachable, emitting `currentUserChanged`. Only an invalid or expired refresh token ends the session, via `authStateChanged(false)`.
 
-## Spaces and Channels
+## Spaces and Conversations
 
-Open a space to receive live events and manage collaborators, file storage, and channels. Open a channel to work with objects, schema, metadata, and AI.
+Open a space to receive live events and manage collaborators, file storage, and conversations. Open a conversation to work with objects, schema, metadata, and AI.
 
 ```typescript
 const space = await client.openSpace('space-id');
 
-space.on('channelCreated', (channel) => console.log(channel.id));
+const conversation = space.conversation('main');
 space.on('filesChanged', () => console.log('files changed'));
 
-const channel = await space.openChannel('main');
-await channel.prompt('Summarize this space');
+await conversation.prompt('Summarize this space');
 ```
 
-Channel IDs must be 1–32 characters and contain only letters, numbers, `_`, and `-`.
+Conversation IDs must be 1–32 characters and contain only letters, numbers, `_`, and `-`.
 
 ## Object Operations
 
 Objects are JSON files under `/space`. Create the collection before writing objects in it.
 
 ```typescript
-await channel.createCollection('article', [
+await conversation.createCollection('article', [
   { name: 'title', type: { kind: 'string' } },
   { name: 'status', type: { kind: 'string' } },
 ]);
 
 // Create or replace an exact object path
-const { object } = await channel.putObject('/space/article/welcome.json', {
+const { object } = await conversation.putObject('/space/article/welcome.json', {
   title: 'Welcome',
   status: 'draft',
 });
 
 // Patch fields; null or undefined deletes a field
-await channel.patchObject(object.path, {
+await conversation.patchObject(object.path, {
   data: { status: 'published', obsoleteField: null },
 });
 
 // Read one or many objects
-await channel.getObject('/space/article/welcome.json');
-await channel.getObjects([
+await space.getObject('/space/article/welcome.json');
+await space.getObjects([
   '/space/article/welcome.json',
   '/space/article/intro.json',
 ]);
 
 // Rename or move an object
-await channel.moveObject(
+await conversation.moveObject(
   '/space/article/welcome.json',
   '/space/article/hello-world.json'
 );
 
 // Delete objects
-await channel.deleteObjects(['/space/article/hello-world.json']);
+await conversation.deleteObjects(['/space/article/hello-world.json']);
 ```
 
 | Method | Description |
@@ -228,7 +297,7 @@ await channel.deleteObjects(['/space/article/hello-world.json']);
 `prompt()` invokes the AI agent. The agent can inspect space context and, unless `readOnly` or a read-only effort is used, create/modify/move/delete objects.
 
 ```typescript
-const { message, objects } = await channel.prompt(
+const { message, objects } = await conversation.prompt(
   'Create a topic node for the solar system, then child nodes for each planet.'
 );
 
@@ -251,12 +320,12 @@ console.log(objects.map((object) => object.path));
 
 ```typescript
 // Read-only quick question
-await channel.prompt('What topics are covered?', {
+await conversation.prompt('What topics are covered?', {
   effort: 'QUICK', // fast/read-only
 });
 
 // Focus on existing objects and files
-await channel.prompt('Compare these resources', {
+await conversation.prompt('Compare these resources', {
   attachments: [
     '/space/article/intro.json',
     'rool-machine:/rool-drive/docs/report.pdf',
@@ -264,12 +333,12 @@ await channel.prompt('Compare these resources', {
 });
 
 // Upload a local file as an attachment
-await channel.prompt('Describe this image', {
+await conversation.prompt('Describe this image', {
   attachments: [fileInput.files![0]],
 });
 
 // Structured response
-const { message } = await channel.prompt('Categorize these items', {
+const { message } = await conversation.prompt('Categorize these items', {
   responseSchema: {
     type: 'object',
     properties: {
@@ -282,7 +351,7 @@ const result = JSON.parse(message);
 
 // Stop a long prompt with a signal (when the caller holds the controller)
 const ac = new AbortController();
-const promptPromise = channel.prompt('Do a deep analysis', {
+const promptPromise = conversation.prompt('Do a deep analysis', {
   effort: 'RESEARCH',
   signal: ac.signal,
 });
@@ -294,39 +363,33 @@ await promptPromise;
 
 Use `signal` when the same call site cancels the prompt. When the Stop button
 lives elsewhere — a different component, after a reload, or a prompt another
-client started — stop by ID or stop the conversation's active interaction
-instead. Both are best-effort: the server halts the agent loop and closes the
-stream, but an LLM turn already in flight keeps generating server-side and is
-billed.
+client started — stop by interaction ID or through a conversation handle. Both
+are best-effort: the server halts the agent loop and closes the stream, but an
+LLM turn already in flight keeps generating server-side and is billed.
 
 ```typescript
-// Stop whatever is in flight on this channel's (default) conversation.
-// No-op returning false when nothing is running.
-await channel.stop();
-
-// Stop a specific interaction by ID (e.g. from channel.activeLeafId or
-// the interactions list). Returns whether the server stopped it.
-await channel.stopInteraction(channel.activeLeafId!);
+// Stop a specific interaction by ID (for example, from conversation.activeLeafId
+// or the interactions list). Returns whether the server stopped it.
+await space.stopInteraction(conversation.activeLeafId!);
 
 // Conversation handles stop their own in-flight interaction.
-const thread = channel.conversation('thread-42');
+const thread = space.conversation('thread-42');
 await thread.stop();
 ```
 
 | Method | Description |
 | --- | --- |
-| `stop(): Promise<boolean>` | Stop the in-flight interaction on the default conversation; `false` if none. |
 | `stopInteraction(id): Promise<boolean>` | Ask the server to stop a specific interaction by ID. |
 | `conversation.stop(): Promise<boolean>` | Stop a specific conversation's in-flight interaction. |
 
 ## Conversations
 
-Every channel has a default conversation. Use `channel.conversation(id)` for independent histories (for example, multiple chat threads). Conversations are represented as trees: interactions point at a `parentId`, and the SDK tracks an active leaf for each conversation.
+Use `space.conversation(id)` for independent histories (for example, multiple chat threads). Conversations are represented as trees: interactions point at a `parentId`, and the SDK tracks an active leaf for each conversation.
 
 ```typescript
-await channel.prompt('Hello'); // default conversation
+await conversation.prompt('Hello');
 
-const thread = channel.conversation('thread-42');
+const thread = space.conversation('thread-42');
 await thread.prompt('Hello from another thread');
 await thread.setSystemInstruction('Answer in haiku');
 
@@ -340,15 +403,14 @@ if (thread.activeLeafId) {
 
 | Method/property | Description |
 | --- | --- |
-| `channel.conversation(id): ConversationHandle` | Get a conversation-scoped handle. |
+| `space.conversation(id): ConversationHandle` | Get a conversation-scoped handle. |
 | `getInteractions(): Interaction[]` | Active branch as a flat list. |
 | `getTree(): Record<string, Interaction>` | Full interaction tree. |
 | `activeLeafId` | Current branch tip. |
 | `setActiveLeaf(id): void` | Switch branches. |
 | `getSystemInstruction()` / `setSystemInstruction(value)` | Manage conversation system instruction. Pass `null` to clear. |
-| `getConversations(): ConversationInfo[]` | List channel conversations (on `RoolChannel`). |
+| `getConversations(): ConversationInfo[]` | List conversations in the space. |
 | `deleteConversation(id): Promise<void>` | Delete a non-active conversation. |
-| `renameConversation(name): Promise<void>` | Rename the current/default conversation (on `RoolChannel`). |
 | `conversation.rename(name): Promise<void>` | Rename a specific conversation handle. |
 
 `ConversationHandle` also supports conversation-scoped `putObject`, `patchObject`, `moveObject`, `deleteObjects`, `prompt`, `stop`, collection-schema methods, and `setMetadata`.
@@ -358,7 +420,7 @@ if (thread.activeLeafId) {
 Collections define the schema visible to the AI agent. Hidden body fields whose names start with `_` are useful for app/UI state that should not be considered by AI.
 
 ```typescript
-await channel.createCollection('article', {
+await conversation.createCollection('article', {
   schemaOrgType: 'Article',
   fields: [
     { name: 'title', type: { kind: 'string' } },
@@ -368,15 +430,15 @@ await channel.createCollection('article', {
   ],
 });
 
-const schema = channel.getSchema();
+const schema = space.getSchema();
 
-await channel.alterCollection('article', [
+await conversation.alterCollection('article', [
   { name: 'title', type: { kind: 'string' } },
   { name: 'status', type: { kind: 'string' } },
 ]);
 
-channel.setMetadata('viewport', { x: 0, y: 0, zoom: 1 });
-const viewport = channel.getMetadata('viewport');
+conversation.setMetadata('viewport', { x: 0, y: 0, zoom: 1 });
+const viewport = space.getMetadata('viewport');
 ```
 
 | Method | Description |
@@ -393,14 +455,14 @@ Field kinds: `string`, `number`, `boolean`, `ref`, `enum`, `literal`, `array`, a
 
 ## Undo/Redo
 
-Undo/redo uses checkpoints for the current channel ID. A checkpoint captures space state; call `checkpoint()` before a user action you want to make undoable.
+Undo/redo uses checkpoints over the whole space. A checkpoint captures space state; call `checkpoint()` before a user action you want to make undoable.
 
 ```typescript
-await channel.checkpoint('Delete article');
-await channel.deleteObjects(['/space/article/welcome.json']);
+await space.checkpoint('Delete article');
+await conversation.deleteObjects(['/space/article/welcome.json']);
 
-if (await channel.canUndo()) {
-  await channel.undo();
+if (await space.canUndo()) {
+  await space.undo();
 }
 ```
 
@@ -413,7 +475,7 @@ if (await channel.canUndo()) {
 | `redo(): Promise<boolean>` | Reapply undone work. |
 | `clearHistory(): Promise<void>` | Clear checkpoint history. |
 
-Undo/redo availability and history are scoped to the channel handle (`channel.channelId`).
+Undo/redo availability and history are scoped to the space.
 
 ## File Storage and WebDAV
 
@@ -579,7 +641,7 @@ const client = new RoolClient({
 | `getAllUserStorage(): Record<string, unknown>` | Copy all cached user storage. |
 | `reportEvent(event, url?): void` | Fire-and-forget telemetry event. |
 | `destroy(): void` | Close subscriptions, spaces, auth resources, and listeners. |
-| `generateId(): string` | Generate a 6-character alphanumeric ID. |
+| `generateId(): string` | Generate a unique ID suitable for conversation IDs. |
 
 ### Client events
 
@@ -589,9 +651,6 @@ client.on('currentUserChanged', (user) => void 0); // CurrentUser | null; null o
 client.on('spaceAdded', (space) => void 0);
 client.on('spaceRemoved', (spaceId) => void 0);
 client.on('spaceRenamed', (spaceId, newName) => void 0);
-client.on('channelCreated', (spaceId, channel) => void 0);
-client.on('channelUpdated', (spaceId, channel) => void 0);
-client.on('channelDeleted', (spaceId, channelId) => void 0);
 client.on('userStorageChanged', ({ key, value, source }) => void 0);
 client.on('connectionStateChanged', (state) => void 0);
 client.on('error', (error, context) => void 0);
@@ -599,12 +658,18 @@ client.on('error', (error, context) => void 0);
 
 ## RoolSpace API
 
-Properties: `id`, `name`, `role`, `memberCount`, `channels`, `route`, `webdav`.
+Properties: `id`, `name`, `role`, `memberCount`, `conversations`, `route`, `webdav`.
 
 | Method | Description |
 | --- | --- |
-| `openChannel(channelId): Promise<RoolChannel>` | Open/create a channel. |
-| `close(): void` | Stop subscription and close open channels. |
+| `conversation(conversationId): ConversationHandle` | Get a conversation-scoped handle. |
+| `getObject`, `getObjects`, `stat` | Read object data and stats. |
+| `getConversations`, `deleteConversation` | List and delete conversations. |
+| `getMetadata`, `getAllMetadata`, `getSchema` | Read metadata and schema. |
+| `checkpoint`, `canUndo`, `canRedo`, `undo`, `redo`, `clearHistory` | Space history controls. |
+| `stopInteraction(interactionId): Promise<boolean>` | Stop an in-flight interaction by ID. |
+| `fetch(url, init?): Promise<Response>` | Proxy an external HTTP request through the server to bypass browser CORS. |
+| `close(): void` | Stop the space subscription. |
 | `rename(newName): Promise<void>` | Rename the space. |
 | `delete(): Promise<void>` | Permanently delete the space. |
 | `listUsers(): Promise<SpaceMember[]>` | List collaborators. |
@@ -613,8 +678,6 @@ Properties: `id`, `name`, `role`, `memberCount`, `channels`, `route`, `webdav`.
 | `createInvite(role, options?): Promise<SpaceInviteCreated>` | Mint an invite link; `options` takes `email`, `expiresInDays`, `maxUses`. |
 | `listInvites(): Promise<SpaceInvite[]>` | List currently redeemable invites. |
 | `revokeInvite(inviteId): Promise<boolean>` | Revoke an invite so its link stops working. |
-| `renameChannel(channelId, name): Promise<void>` | Rename a channel. |
-| `deleteChannel(channelId): Promise<void>` | Delete a channel and history. |
 | `exportArchive(): Promise<Blob>` | Export a space archive. |
 | `refresh(): Promise<void>` | Refresh cached space data. |
 | `fetchPath(path, options?): Promise<Response>` | Fetch a `/rool-drive/...` file. |
@@ -623,42 +686,15 @@ Properties: `id`, `name`, `role`, `memberCount`, `channels`, `route`, `webdav`.
 Events:
 
 ```typescript
-space.on('channelCreated', (channel) => void 0);
-space.on('channelUpdated', (channel) => void 0);
-space.on('channelDeleted', (channelId) => void 0);
+space.on('metadataUpdated', ({ metadata, source }) => void 0);
+space.on('schemaUpdated', ({ schema, source }) => void 0);
+space.on('conversationUpdated', ({ conversationId, source }) => void 0);
+space.on('reset', ({ source }) => void 0);
+space.on('syncError', (error) => void 0);
 space.on('filesChanged', ({ spaceId, source, timestamp }) => void 0);
 space.on('filesReset', ({ spaceId, source, timestamp }) => void 0);
 space.on('connectionStateChanged', (state) => void 0);
 ```
-
-## RoolChannel API
-
-Properties: `id` (space ID), `name` (space name), `role`, `userId`, `channelId`, `channelName`, `conversationId`, `isReadOnly`, `activeLeafId`.
-
-| Area | Methods |
-| --- | --- |
-| Lifecycle | `close()`, `rename(name)`, `conversation(id)` |
-| Objects | `getObject`, `getObjects`, `stat`, `putObject`, `patchObject`, `moveObject`, `deleteObjects` |
-| Schema | `getSchema`, `createCollection`, `alterCollection`, `dropCollection` |
-| Metadata | `setMetadata`, `getMetadata`, `getAllMetadata` |
-| Conversations | `getInteractions`, `getTree`, `setActiveLeaf`, `getConversations`, `deleteConversation`, `getSystemInstruction`, `setSystemInstruction`, `renameConversation` |
-| AI | `prompt`, `stop`, `stopInteraction` |
-| Undo/redo | `checkpoint`, `canUndo`, `canRedo`, `undo`, `redo`, `clearHistory` |
-| Utilities | `fetch(url, init?)` server-side proxied fetch |
-
-Channel events:
-
-```typescript
-channel.on('metadataUpdated', ({ metadata, source }) => void 0);
-channel.on('schemaUpdated', ({ schema, source }) => void 0);
-channel.on('channelUpdated', ({ channelId, source }) => void 0);
-channel.on('conversationUpdated', ({ conversationId, channelId, source }) => void 0);
-channel.on('reset', ({ source }) => void 0);
-channel.on('syncError', (error) => void 0);
-```
-
-`channel.fetch(url, init?)` proxies external HTTP requests through the server to bypass browser CORS.
-
 ## Import/Export
 
 ```typescript
@@ -666,11 +702,15 @@ const archive = await space.exportArchive();
 const imported = await client.importArchive('Imported Data', archive);
 ```
 
-Archives include objects, metadata, channels/conversations, and file storage.
+Archives include objects, metadata, conversations, and file storage.
 
 ## Data Types
 
 ```typescript
+// Outcome of signInWithPassword. 'verify_required' means the account's email
+// isn't verified yet and the server has emailed a magic link.
+type PasswordSignInResult = { status: 'signed_in' | 'verify_required' };
+
 type FieldType =
   | { kind: 'string' }
   | { kind: 'number' }
@@ -717,10 +757,22 @@ interface SpaceInvite {
   useCount: number;
 }
 
-// Outcome of the invite email send; null when no email was involved (open link).
-// 'not_configured' means the server has no mail provider (local dev). Future
-// codes may appear; treat unknown values as not sent.
-type InviteEmailStatus = 'sent' | 'not_configured' | 'failed' | (string & {});
+// Outcome of the invite email send. Null when no email was involved (open link).
+// The invite is always minted and its `url` is usable regardless of this value;
+// only the email delivery is reflected here.
+// - 'sent': email dispatched
+// - 'not_configured': server has no mail provider (local dev)
+// - 'failed': provider rejected the send
+// - 'cooldown': a recent invite to this same address was already emailed
+// - 'rate_limited': the inviter hit their daily email-invite cap
+// Treat unknown values as not sent.
+type InviteEmailStatus =
+  | 'sent'
+  | 'not_configured'
+  | 'failed'
+  | 'cooldown'
+  | 'rate_limited'
+  | (string & {});
 
 interface SpaceInviteCreated {
   inviteId: string;
@@ -752,7 +804,6 @@ interface RoolObjectStat {
   modifiedAt: number;
   modifiedBy: string;
   modifiedByName: string | null;
-  modifiedInChannel: string;
   modifiedInConversation: string | null;
   modifiedInInteraction: string | null;
 }

package/dist/auth-base.d.ts

@@ -0,0 +1,100 @@
+import type { AuthProvider, AuthUser } from './types.js';
+import { type Logger } from './logger.js';
+export interface BaseTokenAuthConfig {
+    /** Auth URL (e.g. https://rool.dev/auth). Injected by RoolClient if omitted. */
+    authUrl?: string;
+    /** Injected by RoolClient if omitted. */
+    logger?: Logger;
+    /** Injected by RoolClient if omitted, so auth-state reaches client events. */
+    onAuthStateChanged?: (authenticated: boolean) => void;
+}
+export declare abstract class BaseTokenAuthProvider implements AuthProvider {
+    protected logger: Logger;
+    private _authUrl;
+    private _onAuthStateChanged;
+    private refreshPromise;
+    private refreshTimeoutId;
+    private boundVisibilityHandler;
+    constructor(config?: BaseTokenAuthConfig);
+    setAuthUrl(url: string): void;
+    setLogger(logger: Logger): void;
+    setAuthStateChangedHandler(handler: (authenticated: boolean) => void): void;
+    abstract initialize(): boolean;
+    abstract login(appName: string, params?: Record<string, string>): Promise<void> | void;
+    abstract signup(appName: string, params?: Record<string, string>): Promise<void> | void;
+    /**
+     * Check if user is currently authenticated.
+     *
+     * This reports identity (do we hold credentials), NOT server reachability.
+     * It deliberately does not perform a network refresh: a backend outage must
+     * not read as "logged out". A genuinely invalid/expired refresh token
+     * surfaces later as a 401 on first real use, which clears tokens and fires
+     * onAuthStateChanged(false) — the only path that ends the session.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Get current access token and rool token, refreshing if expired.
+     * Returns undefined if not authenticated.
+     */
+    getTokens(): Promise<{
+        accessToken: string;
+        roolToken: string;
+    } | undefined>;
+    /**
+     * Get auth identity decoded from JWT token.
+     */
+    getAuthUser(): AuthUser;
+    /**
+     * Complete an email verification flow. Exchanges a verify JWT (from the
+     * verification email link) for a fresh token set and signs the user in.
+     */
+    verify(token: string): Promise<boolean>;
+    /**
+     * Logout - clear all tokens and state.
+     */
+    logout(): void;
+    /**
+     * Destroy auth manager - clear refresh timers and listeners.
+     */
+    destroy(): void;
+    /** Auth URL without trailing slash */
+    protected get authBaseUrl(): string;
+    protected notifyAuthState(authenticated: boolean): void;
+    /** Persist a fresh token set and (re)arm the background refresh timer. */
+    protected acceptTokens(accessToken: string, refreshToken: string | null, roolToken: string | null, expiresAt: number): void;
+    /** Arm auto-refresh + visibility re-scheduling. Call from initialize(). */
+    protected initBase(): void;
+    /**
+     * Overridable hook: clear subclass-owned transient state on logout/cancel
+     * (e.g. an in-flight OAuth `state` or PKCE verifier). No-op by default.
+     */
+    protected clearTransientState(): void;
+    protected get storagePrefix(): string;
+    /** Build a storage key scoped to this auth endpoint. */
+    protected keyFor(name: string): string;
+    protected get storageKeys(): {
+        readonly access: `${string}access_token`;
+        readonly refresh: `${string}refresh_token`;
+        readonly rool: `${string}rool_token`;
+        readonly expiresAt: `${string}token_expires_at`;
+    };
+    protected readString(key: string): string | null;
+    protected writeString(key: string, value: string): void;
+    protected removeString(key: string): void;
+    protected scheduleTokenRefresh(): void;
+    protected writeTokens(accessToken: string | null, refreshToken: string | null, expiresAt: number | null): void;
+    protected writeRoolToken(token: string | null): void;
+    protected clearTokens(): void;
+    protected readAccessToken(): string | null;
+    protected readRoolToken(): string;
+    protected readExpiresAt(): number | null;
+    /**
+     * Get a short hash of the auth URL for scoping storage by endpoint.
+     */
+    private get endpointHash();
+    private tryRefreshToken;
+    private listenForVisibility;
+    private cancelScheduledRefresh;
+    private decodeAuthUser;
+}
+//# sourceMappingURL=auth-base.d.ts.map

package/dist/auth-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-base.d.ts","sourceRoot":"","sources":["../src/auth-base.ts"],"names":[],"mappings":"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"}