@rool-dev/sdk 0.1.0-dev.8511433

package/dist/client.d.ts

@@ -0,0 +1,202 @@
+import { EventEmitter } from './event-emitter.js';
+import { RoolSpace } from './space.js';
+import type { RoolClientConfig, RoolClientEvents, RoolSpaceInfo, CurrentUser, UserResult, AuthUser, PublishedAppInfo, PublishAppOptions } from './types.js';
+/**
+ * Rool Client - Manages authentication, space lifecycle, and shared infrastructure.
+ *
+ * The client is lightweight - most operations happen on Space instances
+ *
+ * Features:
+ * - Authentication (login, logout, token management)
+ * - Spaces lifecycle (list, open, create, delete)
+ * - Client-level subscription for lifecycle events
+ * - Media operations
+ * - AI operations (prompt, image generation)
+ */
+export declare class RoolClient extends EventEmitter<RoolClientEvents> {
+    private urls;
+    private authManager;
+    private graphqlClient;
+    private subscriptionManager;
+    private openSpaces;
+    private _storageCache;
+    constructor(config: RoolClientConfig);
+    /**
+     * Initialize the client - should be called on app startup.
+     * Processes any auth callback in the URL, sets up auto-refresh,
+     * and starts real-time event subscription if authenticated.
+     * @returns true if an auth callback was processed
+     */
+    initialize(): boolean;
+    /**
+     * Clean up resources - call when destroying the client.
+     */
+    destroy(): void;
+    /**
+     * Initiate login by redirecting to auth page.
+     * @param appName - The name of the application requesting login (displayed on auth page)
+     */
+    login(appName: string): Promise<void>;
+    /**
+     * Logout - clear all tokens and state.
+     */
+    logout(): void;
+    /**
+     * Process auth callback from URL fragment.
+     * Called automatically by initialize(), but can be called manually.
+     */
+    processAuthCallback(): boolean;
+    /**
+     * Check if user is currently authenticated (validates token is usable).
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Get current access token.
+     * Returns undefined if not authenticated.
+     */
+    getToken(): Promise<string | undefined>;
+    /**
+     * Get auth identity decoded from JWT token.
+     * For the Rool user (with server-assigned id), use getCurrentUser().
+     */
+    getAuthUser(): AuthUser;
+    /**
+     * List all spaces accessible to the user.
+     */
+    listSpaces(): Promise<RoolSpaceInfo[]>;
+    /**
+     * Open an existing space.
+     * Loads the space data from the server and returns a Space instance.
+     * The space manages its own real-time subscription.
+     *
+     * @param spaceId - The ID of the space to open
+     * @param options.conversationId - Optional conversation ID for AI context continuity. If not provided, a new conversation is created.
+     */
+    openSpace(spaceId: string, options?: {
+        conversationId?: string;
+    }): Promise<RoolSpace>;
+    /**
+     * Create a new space.
+     * Creates on server and returns a Space instance.
+     * The space manages its own real-time subscription.
+     *
+     * @param name - Optional name for the space
+     * @param options.conversationId - Optional conversation ID for AI context continuity. If not provided, a new conversation is created.
+     */
+    createSpace(name?: string, options?: {
+        conversationId?: string;
+    }): Promise<RoolSpace>;
+    /**
+     * Delete a space.
+     * Note: This does not affect any open Space instances - they become stale.
+     */
+    deleteSpace(spaceId: string): Promise<void>;
+    /**
+     * Get the current Rool user from the server.
+     * Returns the user's server-assigned id, email, plan, and credits.
+     */
+    getCurrentUser(): Promise<CurrentUser>;
+    /**
+     * Search for a user by email.
+     */
+    searchUser(email: string): Promise<UserResult | null>;
+    /**
+     * Set the current user's slug (used in app publishing URLs).
+     * Slug must be 3-32 characters, start with a letter, and contain only
+     * lowercase letters, numbers, hyphens, and underscores.
+     * Cannot be changed if the user has published apps.
+     */
+    setSlug(slug: string): Promise<void>;
+    /**
+     * Publish an app. The app will be accessible at:
+     * https://rool.app/{user_slug}/{appId}/
+     *
+     * @param appId - URL-safe identifier (alphanumeric, hyphens, underscores)
+     * @param options - App name, bundle (zip file), and optional SPA flag
+     */
+    publishApp(appId: string, options: PublishAppOptions): Promise<PublishedAppInfo>;
+    /**
+     * Unpublish an app.
+     */
+    unpublishApp(appId: string): Promise<void>;
+    /**
+     * List all published apps for the current user.
+     */
+    listApps(): Promise<PublishedAppInfo[]>;
+    /**
+     * Get info for a specific published app.
+     * Returns null if the app doesn't exist.
+     */
+    getAppInfo(appId: string): Promise<PublishedAppInfo | null>;
+    /**
+     * Get a value from user storage (sync read from local cache).
+     * Returns undefined if key doesn't exist.
+     */
+    getUserStorage<T = unknown>(key: string): T | undefined;
+    /**
+     * Set a value in user storage.
+     * Updates local cache immediately, then syncs to server.
+     * Pass undefined/null to delete the key.
+     * Storage is limited to 10MB total.
+     */
+    setUserStorage(key: string, value: unknown): void;
+    /**
+     * Get all user storage data (sync read from local cache).
+     */
+    getAllUserStorage(): Record<string, unknown>;
+    private get mediaClient();
+    private get appsClient();
+    /**
+     * Ensure the client-level event subscription is active.
+     * Called automatically when opening spaces.
+     * Also fetches and caches the current user ID.
+     * @internal
+     */
+    private ensureSubscribed;
+    /**
+     * Disconnect from real-time events.
+     * @internal
+     */
+    private unsubscribe;
+    /**
+     * Generate a unique entity ID.
+     * 6-character alphanumeric string (62^6 = 56.8 billion possible values).
+     * Also available as top-level generateEntityId() export.
+     */
+    static generateId(): string;
+    /**
+     * Execute an arbitrary GraphQL query or mutation.
+     * Use this escape hatch for app-specific operations not covered by the typed API.
+     *
+     * @example
+     * const result = await client.graphql<{ lastMessages: Message[] }>(
+     *   `query trace($spaceId: String!) { trace(spaceId: $spaceId) }`,
+     *   { spaceId: 'abc123' }
+     * );
+     */
+    graphql<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    private registerSpace;
+    private unregisterSpace;
+    /**
+     * Handle a client-level event from the subscription.
+     * @internal
+     */
+    private handleClientEvent;
+    /**
+     * Load storage cache from auth provider.
+     * @internal
+     */
+    private loadStorageCache;
+    /**
+     * Save storage cache via auth provider.
+     * @internal
+     */
+    private saveStorageCache;
+    /**
+     * Handle a user storage change from SSE (remote update).
+     * Updates cache and emits event if value actually changed.
+     * @internal
+     */
+    private handleUserStorageChanged;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,472 @@
+// =============================================================================
+// Rool Client
+// =============================================================================
+import { EventEmitter } from './event-emitter.js';
+import { AuthManager } from './auth.js';
+import { GraphQLClient } from './graphql.js';
+import { ClientSubscriptionManager } from './subscription.js';
+import { MediaClient } from './media.js';
+import { AppsClient } from './apps.js';
+import { RoolSpace, generateEntityId } from './space.js';
+/**
+ * Rool Client - Manages authentication, space lifecycle, and shared infrastructure.
+ *
+ * The client is lightweight - most operations happen on Space instances
+ *
+ * Features:
+ * - Authentication (login, logout, token management)
+ * - Spaces lifecycle (list, open, create, delete)
+ * - Client-level subscription for lifecycle events
+ * - Media operations
+ * - AI operations (prompt, image generation)
+ */
+export class RoolClient extends EventEmitter {
+    urls;
+    authManager;
+    graphqlClient;
+    subscriptionManager = null;
+    // Registry of open spaces (for cleanup on logout/destroy)
+    openSpaces = new Map();
+    // User storage cache (synced to localStorage)
+    _storageCache = {};
+    constructor(config) {
+        super();
+        const baseUrl = config.baseUrl.replace(/\/+$/, ''); // Remove trailing slashes
+        this.urls = {
+            graphql: config.graphqlUrl ?? `${baseUrl}/graphql`,
+            media: config.mediaUrl ?? `${baseUrl}/media`,
+            auth: config.authUrl ?? `${baseUrl}/auth`,
+            apps: `${baseUrl}/apps`,
+        };
+        this.authManager = new AuthManager({
+            authUrl: this.urls.auth,
+            authProvider: config.authProvider,
+            onAuthStateChanged: (authenticated) => {
+                this.emit('authStateChanged', authenticated);
+            },
+        });
+        this.graphqlClient = new GraphQLClient({
+            graphqlUrl: this.urls.graphql,
+            authManager: this.authManager,
+        });
+        // Load storage cache from localStorage
+        this.loadStorageCache();
+    }
+    // ===========================================================================
+    // Initialization
+    // ===========================================================================
+    /**
+     * Initialize the client - should be called on app startup.
+     * Processes any auth callback in the URL, sets up auto-refresh,
+     * and starts real-time event subscription if authenticated.
+     * @returns true if an auth callback was processed
+     */
+    initialize() {
+        const result = this.authManager.initialize();
+        // Auto-subscribe to real-time events if authenticated (fire-and-forget)
+        void this.authManager.isAuthenticated().then(authenticated => {
+            if (authenticated) {
+                void this.ensureSubscribed();
+            }
+        });
+        return result;
+    }
+    /**
+     * Clean up resources - call when destroying the client.
+     */
+    destroy() {
+        this.authManager.destroy();
+        this.subscriptionManager?.destroy();
+        // Close all open spaces
+        for (const space of this.openSpaces.values()) {
+            space.close();
+        }
+        this.openSpaces.clear();
+        this.removeAllListeners();
+    }
+    // ===========================================================================
+    // Authentication
+    // ===========================================================================
+    /**
+     * Initiate login by redirecting to auth page.
+     * @param appName - The name of the application requesting login (displayed on auth page)
+     */
+    async login(appName) {
+        return this.authManager.login(appName);
+    }
+    /**
+     * Logout - clear all tokens and state.
+     */
+    logout() {
+        this.authManager.logout();
+        this.unsubscribe();
+        // Close all open spaces
+        for (const space of this.openSpaces.values()) {
+            space.close();
+        }
+        this.openSpaces.clear();
+    }
+    /**
+     * Process auth callback from URL fragment.
+     * Called automatically by initialize(), but can be called manually.
+     */
+    processAuthCallback() {
+        return this.authManager.processCallback();
+    }
+    /**
+     * Check if user is currently authenticated (validates token is usable).
+     */
+    async isAuthenticated() {
+        return this.authManager.isAuthenticated();
+    }
+    /**
+     * Get current access token.
+     * Returns undefined if not authenticated.
+     */
+    async getToken() {
+        return this.authManager.getToken();
+    }
+    /**
+     * Get auth identity decoded from JWT token.
+     * For the Rool user (with server-assigned id), use getCurrentUser().
+     */
+    getAuthUser() {
+        return this.authManager.getAuthUser();
+    }
+    // ===========================================================================
+    // Space Lifecycle
+    // ===========================================================================
+    /**
+     * List all spaces accessible to the user.
+     */
+    async listSpaces() {
+        return this.graphqlClient.listSpaces();
+    }
+    /**
+     * Open an existing space.
+     * Loads the space data from the server and returns a Space instance.
+     * The space manages its own real-time subscription.
+     *
+     * @param spaceId - The ID of the space to open
+     * @param options.conversationId - Optional conversation ID for AI context continuity. If not provided, a new conversation is created.
+     */
+    async openSpace(spaceId, options) {
+        // Ensure client subscription is active (for lifecycle events)
+        void this.ensureSubscribed();
+        const { data, name, role, userId } = await this.graphqlClient.getSpace(spaceId);
+        const space = new RoolSpace({
+            id: spaceId,
+            name,
+            role: role,
+            userId,
+            initialData: data,
+            conversationId: options?.conversationId,
+            graphqlClient: this.graphqlClient,
+            mediaClient: this.mediaClient,
+            graphqlUrl: this.urls.graphql,
+            authManager: this.authManager,
+            onClose: (id) => this.unregisterSpace(id),
+        });
+        // Register for cleanup
+        this.registerSpace(spaceId, space);
+        return space;
+    }
+    /**
+     * Create a new space.
+     * Creates on server and returns a Space instance.
+     * The space manages its own real-time subscription.
+     *
+     * @param name - Optional name for the space
+     * @param options.conversationId - Optional conversation ID for AI context continuity. If not provided, a new conversation is created.
+     */
+    async createSpace(name, options) {
+        // Ensure client subscription is active (for lifecycle events)
+        void this.ensureSubscribed();
+        const spaceId = generateEntityId();
+        const spaceName = name ?? spaceId;
+        // Create on server with name (use a temporary conversationId for lifecycle ops)
+        await this.graphqlClient.createSpace(spaceId, spaceName, generateEntityId());
+        // Fetch the created space to get userId (server assigns it)
+        const { data, userId } = await this.graphqlClient.getSpace(spaceId);
+        const space = new RoolSpace({
+            id: spaceId,
+            name: spaceName,
+            role: 'owner',
+            userId,
+            initialData: data,
+            conversationId: options?.conversationId,
+            graphqlClient: this.graphqlClient,
+            mediaClient: this.mediaClient,
+            graphqlUrl: this.urls.graphql,
+            authManager: this.authManager,
+            onClose: (id) => this.unregisterSpace(id),
+        });
+        // Register for cleanup
+        this.registerSpace(spaceId, space);
+        return space;
+    }
+    /**
+     * Delete a space.
+     * Note: This does not affect any open Space instances - they become stale.
+     */
+    async deleteSpace(spaceId) {
+        // Use a temporary conversationId for lifecycle ops
+        await this.graphqlClient.deleteSpace(spaceId, generateEntityId());
+        // Client-level event will be emitted via SSE subscription
+    }
+    // ===========================================================================
+    // User Operations
+    // ===========================================================================
+    /**
+     * Get the current Rool user from the server.
+     * Returns the user's server-assigned id, email, plan, and credits.
+     */
+    async getCurrentUser() {
+        return this.graphqlClient.getAccount();
+    }
+    /**
+     * Search for a user by email.
+     */
+    async searchUser(email) {
+        return this.graphqlClient.searchUser(email);
+    }
+    /**
+     * Set the current user's slug (used in app publishing URLs).
+     * Slug must be 3-32 characters, start with a letter, and contain only
+     * lowercase letters, numbers, hyphens, and underscores.
+     * Cannot be changed if the user has published apps.
+     */
+    async setSlug(slug) {
+        return this.graphqlClient.setSlug(slug);
+    }
+    // ===========================================================================
+    // App Publishing
+    // ===========================================================================
+    /**
+     * Publish an app. The app will be accessible at:
+     * https://rool.app/{user_slug}/{appId}/
+     *
+     * @param appId - URL-safe identifier (alphanumeric, hyphens, underscores)
+     * @param options - App name, bundle (zip file), and optional SPA flag
+     */
+    async publishApp(appId, options) {
+        return this.appsClient.publish(appId, options);
+    }
+    /**
+     * Unpublish an app.
+     */
+    async unpublishApp(appId) {
+        return this.appsClient.unpublish(appId);
+    }
+    /**
+     * List all published apps for the current user.
+     */
+    async listApps() {
+        return this.appsClient.list();
+    }
+    /**
+     * Get info for a specific published app.
+     * Returns null if the app doesn't exist.
+     */
+    async getAppInfo(appId) {
+        return this.appsClient.get(appId);
+    }
+    // ===========================================================================
+    // User Storage (server-side localStorage equivalent)
+    // ===========================================================================
+    /**
+     * Get a value from user storage (sync read from local cache).
+     * Returns undefined if key doesn't exist.
+     */
+    getUserStorage(key) {
+        return this._storageCache[key];
+    }
+    /**
+     * Set a value in user storage.
+     * Updates local cache immediately, then syncs to server.
+     * Pass undefined/null to delete the key.
+     * Storage is limited to 10MB total.
+     */
+    setUserStorage(key, value) {
+        // Update local cache
+        if (value === null || value === undefined) {
+            delete this._storageCache[key];
+        }
+        else {
+            this._storageCache[key] = value;
+        }
+        // Persist to localStorage
+        this.saveStorageCache();
+        // Emit event (local source)
+        this.emit('userStorageChanged', { key, value: value ?? null, source: 'local' });
+        // Fire-and-forget server sync
+        this.graphqlClient.setUserStorage(key, value).catch((error) => {
+            console.error('[RoolClient] Failed to sync user storage:', error);
+            this.emit('error', error instanceof Error ? error : new Error(String(error)), 'userStorage');
+        });
+    }
+    /**
+     * Get all user storage data (sync read from local cache).
+     */
+    getAllUserStorage() {
+        return { ...this._storageCache };
+    }
+    // ===========================================================================
+    // Media Client (used internally by Space instances)
+    // ===========================================================================
+    get mediaClient() {
+        return new MediaClient({
+            mediaUrl: this.urls.media,
+            backendOrigin: new URL(this.urls.media).origin,
+            authManager: this.authManager,
+        });
+    }
+    // ===========================================================================
+    // Apps Client (used for app publishing)
+    // ===========================================================================
+    get appsClient() {
+        return new AppsClient({
+            appsUrl: this.urls.apps,
+            authManager: this.authManager,
+        });
+    }
+    // ===========================================================================
+    // Subscriptions (internal - auto-managed)
+    // ===========================================================================
+    /**
+     * Ensure the client-level event subscription is active.
+     * Called automatically when opening spaces.
+     * Also fetches and caches the current user ID.
+     * @internal
+     */
+    async ensureSubscribed() {
+        if (this.subscriptionManager)
+            return;
+        this.subscriptionManager = new ClientSubscriptionManager({
+            graphqlUrl: this.urls.graphql,
+            authManager: this.authManager,
+            onEvent: (event) => this.handleClientEvent(event),
+            onConnectionStateChanged: (state) => {
+                this.emit('connectionStateChanged', state);
+            },
+            onError: (error) => {
+                this.emit('error', error, 'subscription');
+            },
+        });
+        await this.subscriptionManager.subscribe();
+    }
+    /**
+     * Disconnect from real-time events.
+     * @internal
+     */
+    unsubscribe() {
+        if (this.subscriptionManager) {
+            this.subscriptionManager.destroy();
+            this.subscriptionManager = null;
+        }
+    }
+    // ===========================================================================
+    // Utilities
+    // ===========================================================================
+    /**
+     * Generate a unique entity ID.
+     * 6-character alphanumeric string (62^6 = 56.8 billion possible values).
+     * Also available as top-level generateEntityId() export.
+     */
+    static generateId() {
+        return generateEntityId();
+    }
+    /**
+     * Execute an arbitrary GraphQL query or mutation.
+     * Use this escape hatch for app-specific operations not covered by the typed API.
+     *
+     * @example
+     * const result = await client.graphql<{ lastMessages: Message[] }>(
+     *   `query trace($spaceId: String!) { trace(spaceId: $spaceId) }`,
+     *   { spaceId: 'abc123' }
+     * );
+     */
+    async graphql(query, variables) {
+        return this.graphqlClient.query(query, variables);
+    }
+    // ===========================================================================
+    // Private Methods - Space Registry
+    // ===========================================================================
+    registerSpace(spaceId, space) {
+        this.openSpaces.set(spaceId, space);
+    }
+    unregisterSpace(spaceId) {
+        this.openSpaces.delete(spaceId);
+    }
+    // ===========================================================================
+    // Private Methods - Event Handling
+    // ===========================================================================
+    /**
+     * Handle a client-level event from the subscription.
+     * @internal
+     */
+    handleClientEvent(event) {
+        switch (event.type) {
+            case 'space_created':
+                this.emit('spaceCreated', {
+                    id: event.spaceId,
+                    name: event.name ?? event.spaceId,
+                    role: event.role ?? 'owner',
+                    ownerId: event.ownerId ?? '',
+                    size: event.size ?? 0,
+                    createdAt: event.createdAt ?? new Date().toISOString(),
+                    updatedAt: event.updatedAt ?? new Date().toISOString(),
+                });
+                break;
+            case 'space_deleted':
+                this.emit('spaceDeleted', event.spaceId);
+                break;
+            case 'space_renamed':
+                this.emit('spaceRenamed', event.spaceId, event.name ?? event.spaceId);
+                break;
+            case 'user_storage_changed':
+                this.handleUserStorageChanged(event.key, event.value);
+                break;
+        }
+    }
+    // ===========================================================================
+    // Private Methods - User Storage Cache
+    // ===========================================================================
+    /**
+     * Load storage cache from auth provider.
+     * @internal
+     */
+    loadStorageCache() {
+        const cached = this.authManager.getStorage();
+        if (cached) {
+            this._storageCache = cached;
+        }
+    }
+    /**
+     * Save storage cache via auth provider.
+     * @internal
+     */
+    saveStorageCache() {
+        this.authManager.setStorage(this._storageCache);
+    }
+    /**
+     * Handle a user storage change from SSE (remote update).
+     * Updates cache and emits event if value actually changed.
+     * @internal
+     */
+    handleUserStorageChanged(key, value) {
+        const currentValue = this._storageCache[key];
+        // Only update and emit if value actually changed
+        if (JSON.stringify(currentValue) !== JSON.stringify(value)) {
+            if (value === null || value === undefined) {
+                delete this._storageCache[key];
+            }
+            else {
+                this._storageCache[key] = value;
+            }
+            this.saveStorageCache();
+            this.emit('userStorageChanged', { key, value: value ?? null, source: 'remote' });
+        }
+    }
+}
+//# sourceMappingURL=client.js.map