@rool-dev/sdk 0.11.2 → 0.11.3-dev.521c0dc

package/README.md

@@ -142,6 +142,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 +218,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. |
@@ -490,16 +561,53 @@ High-level WebDAV methods that validate response status throw `WebDAVError` with
 
 ## Collaboration
 
+New members join a space by redeeming an invite. Owners and admins mint invites; the returned `url` contains the secret token and is only available at mint time.
+
 ```typescript
-const user = await client.searchUser('colleague@example.com');
-if (user) {
-  await space.addUser(user.id, 'editor');
+// Shareable invite link
+const invite = await space.createInvite('editor', { expiresInDays: 7 });
+console.log(invite.url);
+
+// Email-guarded invite: single-use, locked to that address, sent by mail
+const emailed = await space.createInvite('viewer', { email: 'colleague@example.com' });
+if (emailed.emailStatus !== 'sent') {
+  // Mail did not go out (e.g. no mail provider configured) — share emailed.url yourself
 }
 
-await space.setLinkAccess('viewer'); // 'none' | 'viewer' | 'editor'
+// Manage outstanding invites
+const invites = await space.listInvites();
+await space.revokeInvite(invites[0].inviteId);
+
+// Change an existing member's role, or remove them
+await space.setUserRole(userId, 'admin');
+await space.removeUser(userId);
+```
+
+On the join page, look up the invite before sign-in and redeem it once authenticated:
+
+```typescript
+const preview = await client.previewInvite(token); // no auth required
+console.log(preview.spaceName, preview.role, preview.inviterName);
+
+const result = await client.redeemInvite(token);
+console.log(result.spaceId, result.status); // 'joined' | 'upgraded' | 'already_member'
+```
+
+Invalid, expired, revoked, exhausted, or email-mismatched invites throw `InviteError` with a `code` of `'INVITE_INVALID' | 'INVITE_EXPIRED' | 'INVITE_REVOKED' | 'INVITE_EXHAUSTED' | 'INVITE_EMAIL_MISMATCH'`.
+
+```typescript
+import { InviteError } from '@rool-dev/sdk';
+
+try {
+  await client.redeemInvite(token);
+} catch (error) {
+  if (error instanceof InviteError && error.code === 'INVITE_EXPIRED') {
+    // Ask for a fresh invite
+  }
+}
 ```
 
-Roles:
+Roles (invites grant `admin`, `editor`, or `viewer` — never `owner`):
 
 | Role | Capabilities |
 | --- | --- |
@@ -529,7 +637,8 @@ const client = new RoolClient({
 | `getCurrentUser(): Promise<CurrentUser>` | Fetch current user. |
 | `updateCurrentUser(input): Promise<CurrentUser>` | Update `name`, `slug`, or `marketingOptIn`. |
 | `deleteCurrentUser(): Promise<void>` | Mark account for deletion and log out. |
-| `searchUser(email): Promise<UserResult | null>` | Exact email lookup. |
+| `previewInvite(token): Promise<InvitePreview>` | Look up an invite link without redeeming it. No auth required. |
+| `redeemInvite(token): Promise<InviteRedeemResult>` | Redeem an invite, joining (or upgrading in) its space. |
 | `listSpaces(): Promise<RoolSpaceInfo[]>` | List accessible spaces. |
 | `openSpace(id): Promise<RoolSpace>` | Open/cached live space handle. |
 | `createSpace(name): Promise<RoolSpace>` | Create and open a space. |
@@ -561,7 +670,7 @@ client.on('error', (error, context) => void 0);
 
 ## RoolSpace API
 
-Properties: `id`, `name`, `role`, `linkAccess`, `memberCount`, `channels`, `route`, `webdav`.
+Properties: `id`, `name`, `role`, `memberCount`, `channels`, `route`, `webdav`.
 
 | Method | Description |
 | --- | --- |
@@ -570,9 +679,11 @@ Properties: `id`, `name`, `role`, `linkAccess`, `memberCount`, `channels`, `rout
 | `rename(newName): Promise<void>` | Rename the space. |
 | `delete(): Promise<void>` | Permanently delete the space. |
 | `listUsers(): Promise<SpaceMember[]>` | List collaborators. |
-| `addUser(userId, role): Promise<void>` | Add collaborator. |
+| `setUserRole(userId, role): Promise<void>` | Change an existing member's role. |
 | `removeUser(userId): Promise<void>` | Remove collaborator. |
-| `setLinkAccess(linkAccess): Promise<void>` | Set URL sharing level. |
+| `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. |
@@ -593,7 +704,7 @@ space.on('connectionStateChanged', (state) => void 0);
 
 ## RoolChannel API
 
-Properties: `id` (space ID), `name` (space name), `role`, `linkAccess`, `userId`, `channelId`, `channelName`, `conversationId`, `isReadOnly`, `activeLeafId`.
+Properties: `id` (space ID), `name` (space name), `role`, `userId`, `channelId`, `channelName`, `conversationId`, `isReadOnly`, `activeLeafId`.
 
 | Area | Methods |
 | --- | --- |
@@ -631,6 +742,10 @@ Archives include objects, metadata, channels/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' }
@@ -663,6 +778,62 @@ interface GetObjectsResult {
   missing: string[];
 }
 
+type InviteRole = 'admin' | 'editor' | 'viewer';
+
+interface SpaceInvite {
+  inviteId: string;
+  spaceId: string;
+  role: InviteRole;
+  email: string | null;
+  createdBy: string;
+  createdAt: string;
+  expiresAt: string;
+  maxUses: number | null;
+  useCount: number;
+}
+
+// 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;
+  spaceId: string;
+  role: InviteRole;
+  email: string | null;
+  expiresAt: string;
+  maxUses: number | null;
+  url: string; // contains the secret token; only available at mint time
+  emailStatus: InviteEmailStatus | null;
+}
+
+interface InvitePreview {
+  spaceId: string;
+  spaceName: string;
+  role: InviteRole;
+  email: string | null;
+  inviterName: string | null;
+}
+
+interface InviteRedeemResult {
+  spaceId: string;
+  role: RoolUserRole;
+  status: 'joined' | 'upgraded' | 'already_member';
+}
+
 interface RoolObjectStat {
   path: string;
   modifiedAt: number;

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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"}