@nurama/sdk 0.0.0-stage → 1.4.0

package/src/routes/workspace.ts

@@ -0,0 +1,223 @@
+import NuramaClient from '../NuramaClient.js';
+
+// Define specific types for workspace requests/responses if desired
+export interface CreateWorkspaceData {
+    name: string;
+    description?: string;
+}
+
+export interface UpdateWorkspaceData {
+    name?: string;
+    description?: string;
+    updateSlug?: boolean;
+}
+
+export interface FileData { 
+    name: string;
+    checksum: string;
+    sizeInMB: number;
+}
+
+export interface SortParams {
+    [key: string]: 1 | -1;
+}
+
+/**
+ * Defines workspace-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the workspace methods.
+ */
+export default function createWorkspaceMethods(client: NuramaClient) {
+  // Specify return type more accurately if possible, using WorkspaceMethods interface
+  return {
+    /**
+     * Creates a new workspace.
+     * Requires authentication.
+     * @param data - Workspace data.
+     * @returns {Promise<object>} The created workspace object.
+     */
+    async createWorkspace(data: CreateWorkspaceData): Promise<any> {
+      return client._request({
+        endpoint: '/v1/workspaces',
+        method: 'POST',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Retrieves a specific workspace by its ID.
+     * Requires authentication.
+     * @param {string} workspaceId - The ID of the workspace to retrieve.
+     * @returns {Promise<object>} The workspace object.
+     */
+    async getWorkspace(workspaceId: string): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}`,
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Lists all workspaces the authenticated user has access to.
+     * Requires authentication.
+     * @param {object} [sortParams] - Optional sorting. Keys are field names (`id`, `name`, `createdAt`, `updatedAt`);
+     *   values are 1 for ascending or -1 for descending. Sent as `?sort[name]=1&sort[createdAt]=-1`.
+     * @returns {Promise<Array<object>>} Workspaces with the caller's `roles` and the workspace `capabilities`.
+     */
+    async listWorkspaces(sortParams: SortParams = {}): Promise<any[]> {
+      return client._request({
+        endpoint: '/v1/workspaces',
+        method: 'GET',
+        params: Object.keys(sortParams).length > 0 ? { sort: sortParams } : undefined,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Request signed URL data to upload a workspace logo.
+     * Caller then multipart-uploads the file using the returned `signedUrlData`
+     * and calls `client.asset.completeUpload(...)` to finalize.
+     *
+     * @param {string} fileData.checksum - The MD5 checksum.
+     * @param {number} fileData.sizeInMB - The file size in MB.
+     * @returns {Promise<object>} Response containing signed URL data and workspace info.
+     */
+    async createLogo(workspaceId: string, fileData: FileData): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}/logo`,
+        method: 'POST',
+        body: fileData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Request signed URL data to replace the workspace logo. Same upload
+     * shape as `createLogo`; existing logo is replaced once `completeUpload`
+     * lands.
+     *
+     * @param {string} fileData.checksum - The MD5 checksum.
+     * @param {number} fileData.sizeInMB - The file size in MB.
+     * @returns {Promise<object>} Response containing signed URL data and workspace info.
+     */
+    async updateLogo(workspaceId: string, fileData: FileData): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}/logo`,
+        method: 'PUT',
+        body: fileData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Request signed URL data to upload a workspace icon (the small square
+     * shown in sidebars and tabs — distinct from the logo).
+     *
+     * @param {string} fileData.checksum - The MD5 checksum.
+     * @param {number} fileData.sizeInMB - The file size in MB.
+     * @returns {Promise<object>} Response containing signed URL data and workspace info.
+     */
+    async createIcon(workspaceId: string, fileData: FileData): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}/icon`,
+        method: 'POST',
+        body: fileData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Request signed URL data to replace the workspace icon. Same upload
+     * shape as `createIcon`.
+     *
+     * @param {string} fileData.checksum - The MD5 checksum.
+     * @param {number} fileData.sizeInMB - The file size in MB.
+     * @returns {Promise<object>} Response containing signed URL data and workspace info.
+     */
+    async updateIcon(workspaceId: string, fileData: FileData): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}/icon`,
+        method: 'PUT',
+        body: fileData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List the projects inside a workspace that the calling user has
+     * access to.
+     *
+     * @param {string} workspaceId - The ID of the workspace.
+     * @returns {Promise<Array<object>>} An array of project objects.
+     */
+    async listProjects(workspaceId: string): Promise<any[]> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}/projects`,
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Update workspace metadata (name, description, etc.).
+     *
+     * @param {boolean} [updateData.updateSlug] - Whether to update the slug based on the new name.
+     * @returns {Promise<object>} The updated workspace object.
+     */
+    async updateWorkspace(workspaceId: string, updateData: UpdateWorkspaceData): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}`,
+        method: 'PUT',
+        body: updateData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Soft-delete a workspace. All nested resources (projects, chats,
+     * assets) become inaccessible; bytes are reclaimed by the cleanup
+     * cron.
+     *
+     * @param {string} workspaceId - The ID of the workspace to delete.
+     * @returns {Promise<object>} Object confirming the status change.
+     */
+    async deleteWorkspace(workspaceId: string): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}`,
+        method: 'DELETE',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Toggle a single workspace boolean setting (e.g. an `enableX` feature
+     * flag).
+     *
+     * @param {string} workspaceId - The ID of the workspace.
+     * @param {string} settingName - The name of the setting.
+     * @param {boolean} value - The new value for the setting.
+     * @returns {Promise<object>} The updated workspace object with new settings.
+     */
+    async updateSetting(workspaceId: string, settingName: string, value: boolean): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!settingName) throw new Error('settingName is required.');
+      return client._request({
+        endpoint: `/v1/workspaces/${workspaceId}/settings/${settingName}`,
+        method: 'PUT',
+        body: { value },
+        sendJWT: true,
+      });
+    },
+
+  };
+}

package/src/utils/uploadSessionManager.ts

@@ -0,0 +1,407 @@
+/**
+ * Upload Session Manager for Nurama SDK
+ * 
+ * Provides upload progress persistence and cross-tab synchronization
+ * - Persists upload progress to localStorage with project isolation
+ * - Syncs upload state across multiple browser tabs
+ * - Automatic cleanup of completed/failed uploads
+ */
+
+export interface UploadSessionData {
+  sessionId: string;
+  projectId: string;
+  uploadId: string;          // S3 multipart upload ID
+  key: string;               // S3 object key
+  assetId?: string;          // Backend asset ID (once available)
+  
+  // Progress tracking
+  progress: number;          // Overall progress (0-100)
+  partNumber: number;        // Current part being uploaded
+  totalParts: number;        // Total number of parts
+  completedParts: number[];  // Array of completed part numbers
+  
+  // Metadata
+  fileName: string;
+  fileSize: number;
+  timestamp: number;         // Last update timestamp
+  status: 'uploading' | 'completing' | 'completed' | 'failed' | 'cancelled';
+  
+  // Optional error information
+  error?: string;
+}
+
+export interface CrossTabMessage {
+  type: 'upload_progress_update' | 'upload_status_change' | 'upload_cleanup';
+  projectId: string;
+  sessionId: string;
+  data?: Partial<UploadSessionData>;
+}
+
+export class UploadSessionManager {
+  private static instance: UploadSessionManager;
+  private messageListeners: Map<string, (message: CrossTabMessage) => void> = new Map();
+  private readonly STORAGE_PREFIX = 'nurama_upload_session_';
+  private readonly MESSAGE_CHANNEL = 'nurama_upload_sync';
+  private broadcastChannel?: BroadcastChannel;
+
+  constructor() {
+    this.initializeCrossTabSync();
+  }
+
+  public static getInstance(): UploadSessionManager {
+    if (!UploadSessionManager.instance) {
+      UploadSessionManager.instance = new UploadSessionManager();
+    }
+    return UploadSessionManager.instance;
+  }
+
+  /**
+   * Initialize cross-tab synchronization using BroadcastChannel
+   */
+  private initializeCrossTabSync(): void {
+    if (typeof window !== 'undefined' && 'BroadcastChannel' in window) {
+      try {
+        this.broadcastChannel = new BroadcastChannel(this.MESSAGE_CHANNEL);
+        this.broadcastChannel.addEventListener('message', this.handleCrossTabMessage.bind(this));
+      } catch (error) {
+        console.warn('[UploadSessionManager] BroadcastChannel not available:', error);
+      }
+    }
+  }
+
+  /**
+   * Handle cross-tab messages
+   */
+  private handleCrossTabMessage(event: MessageEvent<CrossTabMessage>): void {
+    const message = event.data;
+    if (message && message.type && message.projectId && message.sessionId) {
+      // Notify registered listeners
+      this.messageListeners.forEach(listener => {
+        try {
+          listener(message);
+        } catch (error) {
+          console.error('[UploadSessionManager] Error in message listener:', error);
+        }
+      });
+    }
+  }
+
+  /**
+   * Generate storage key for upload session
+   */
+  private getStorageKey(projectId: string, sessionId: string): string {
+    return `${this.STORAGE_PREFIX}${projectId}_${sessionId}`;
+  }
+
+  /**
+   * Create a new upload session
+   */
+  public createSession(
+    projectId: string, 
+    sessionId: string, 
+    uploadData: {
+      uploadId: string;
+      key: string;
+      fileName: string;
+      fileSize: number;
+      totalParts: number;
+      assetId?: string;
+    }
+  ): UploadSessionData {
+    const session: UploadSessionData = {
+      sessionId,
+      projectId,
+      uploadId: uploadData.uploadId,
+      key: uploadData.key,
+      assetId: uploadData.assetId,
+      progress: 0,
+      partNumber: 1,
+      totalParts: uploadData.totalParts,
+      completedParts: [],
+      fileName: uploadData.fileName,
+      fileSize: uploadData.fileSize,
+      timestamp: Date.now(),
+      status: 'uploading'
+    };
+
+    this.saveSession(session);
+    this.broadcastMessage('upload_status_change', projectId, sessionId, session);
+    
+    return session;
+  }
+
+  /**
+   * Update upload progress for a session
+   */
+  public updateProgress(
+    projectId: string, 
+    sessionId: string, 
+    progress: {
+      progress: number;
+      partNumber: number;
+      completedParts?: number[];
+    }
+  ): void {
+    const session = this.getSession(projectId, sessionId);
+    if (!session) {
+      console.warn(`[UploadSessionManager] Session not found: ${sessionId}`);
+      return;
+    }
+
+    const updatedSession: UploadSessionData = {
+      ...session,
+      progress: progress.progress,
+      partNumber: progress.partNumber,
+      completedParts: progress.completedParts || session.completedParts,
+      timestamp: Date.now()
+    };
+
+    this.saveSession(updatedSession);
+    this.broadcastMessage('upload_progress_update', projectId, sessionId, {
+      progress: progress.progress,
+      partNumber: progress.partNumber,
+      completedParts: progress.completedParts,
+      timestamp: updatedSession.timestamp
+    });
+  }
+
+  /**
+   * Update upload status
+   */
+  public updateStatus(
+    projectId: string, 
+    sessionId: string, 
+    status: UploadSessionData['status'],
+    error?: string
+  ): void {
+    const session = this.getSession(projectId, sessionId);
+    if (!session) {
+      console.warn(`[UploadSessionManager] Session not found: ${sessionId}`);
+      return;
+    }
+
+    const updatedSession: UploadSessionData = {
+      ...session,
+      status,
+      error,
+      timestamp: Date.now()
+    };
+
+    this.saveSession(updatedSession);
+    this.broadcastMessage('upload_status_change', projectId, sessionId, {
+      status,
+      error,
+      timestamp: updatedSession.timestamp
+    });
+  }
+
+  /**
+   * Get upload session data
+   */
+  public getSession(projectId: string, sessionId: string): UploadSessionData | null {
+    if (typeof window === 'undefined') return null;
+
+    try {
+      const key = this.getStorageKey(projectId, sessionId);
+      const data = localStorage.getItem(key);
+      if (data) {
+        const session = JSON.parse(data) as UploadSessionData;
+        // Validate session data
+        if (session.projectId === projectId && session.sessionId === sessionId) {
+          return session;
+        }
+      }
+    } catch (error) {
+      console.warn(`[UploadSessionManager] Failed to get session ${sessionId}:`, error);
+    }
+
+    return null;
+  }
+
+  /**
+   * Get all upload sessions for a project
+   */
+  public getProjectSessions(projectId: string): UploadSessionData[] {
+    if (typeof window === 'undefined') return [];
+
+    const sessions: UploadSessionData[] = [];
+    const prefix = `${this.STORAGE_PREFIX}${projectId}_`;
+
+    try {
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key && key.startsWith(prefix)) {
+          const data = localStorage.getItem(key);
+          if (data) {
+            try {
+              const session = JSON.parse(data) as UploadSessionData;
+              if (session.projectId === projectId) {
+                sessions.push(session);
+              }
+            } catch (error) {
+              console.warn(`[UploadSessionManager] Invalid session data in ${key}:`, error);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.warn('[UploadSessionManager] Failed to get project sessions:', error);
+    }
+
+    // Sort by timestamp (most recent first)
+    return sessions.sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  /**
+   * Get every upload session across ALL projects (scans the whole localStorage
+   * prefix, not a single project). Used by app-level guards that need a global
+   * "is anything uploading right now" answer without knowing the project id.
+   */
+  public getAllSessions(): UploadSessionData[] {
+    if (typeof window === 'undefined') return [];
+
+    const sessions: UploadSessionData[] = [];
+    try {
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key && key.startsWith(this.STORAGE_PREFIX)) {
+          const data = localStorage.getItem(key);
+          if (data) {
+            try {
+              sessions.push(JSON.parse(data) as UploadSessionData);
+            } catch (error) {
+              console.warn(`[UploadSessionManager] Invalid session data in ${key}:`, error);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.warn('[UploadSessionManager] Failed to enumerate sessions:', error);
+    }
+
+    return sessions.sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  /**
+   * True when at least one upload is genuinely in flight anywhere in the app.
+   *
+   * "In flight" = status `uploading`/`completing` AND updated within `staleMs`.
+   * The freshness window matters: a tab that crashed mid-upload leaves an
+   * `uploading` row in localStorage forever (it never reaches a terminal
+   * status). Progress ticks bump `timestamp` on every part, so a real upload
+   * stays fresh; a dead one goes stale and stops counting — otherwise a stale
+   * row would block app refreshes/navigation indefinitely.
+   *
+   * @param staleMs How long since the last progress update still counts as
+   *   active. Default 2 minutes — comfortably longer than a single part PUT on
+   *   a slow connection, short enough that a crashed upload clears quickly.
+   */
+  public hasActiveUploads(staleMs: number = 2 * 60 * 1000): boolean {
+    const cutoff = Date.now() - staleMs;
+    return this.getAllSessions().some(
+      (s) =>
+        (s.status === 'uploading' || s.status === 'completing') &&
+        s.timestamp >= cutoff
+    );
+  }
+
+  /**
+   * Save session to localStorage
+   */
+  private saveSession(session: UploadSessionData): void {
+    if (typeof window === 'undefined') return;
+
+    try {
+      const key = this.getStorageKey(session.projectId, session.sessionId);
+      localStorage.setItem(key, JSON.stringify(session));
+    } catch (error) {
+      console.warn(`[UploadSessionManager] Failed to save session ${session.sessionId}:`, error);
+    }
+  }
+
+  /**
+   * Remove upload session
+   */
+  public removeSession(projectId: string, sessionId: string): void {
+    if (typeof window === 'undefined') return;
+
+    try {
+      const key = this.getStorageKey(projectId, sessionId);
+      localStorage.removeItem(key);
+      this.broadcastMessage('upload_cleanup', projectId, sessionId);
+    } catch (error) {
+      console.warn(`[UploadSessionManager] Failed to remove session ${sessionId}:`, error);
+    }
+  }
+
+  /**
+   * Clean up old or completed sessions
+   */
+  public cleanupSessions(projectId: string, olderThanMs: number = 24 * 60 * 60 * 1000): void {
+    const sessions = this.getProjectSessions(projectId);
+    const cutoff = Date.now() - olderThanMs;
+
+    sessions.forEach(session => {
+      // Remove old sessions or completed/failed/cancelled sessions older than 1 hour
+      const shouldRemove = session.timestamp < cutoff || 
+        (['completed', 'failed', 'cancelled'].includes(session.status) && 
+         session.timestamp < (Date.now() - 60 * 60 * 1000));
+
+      if (shouldRemove) {
+        this.removeSession(projectId, session.sessionId);
+      }
+    });
+  }
+
+  /**
+   * Register a listener for cross-tab messages
+   */
+  public onMessage(listenerId: string, callback: (message: CrossTabMessage) => void): void {
+    this.messageListeners.set(listenerId, callback);
+  }
+
+  /**
+   * Unregister a message listener
+   */
+  public offMessage(listenerId: string): void {
+    this.messageListeners.delete(listenerId);
+  }
+
+  /**
+   * Broadcast a message to other tabs
+   */
+  private broadcastMessage(
+    type: CrossTabMessage['type'], 
+    projectId: string, 
+    sessionId: string, 
+    data?: Partial<UploadSessionData>
+  ): void {
+    if (this.broadcastChannel) {
+      try {
+        const message: CrossTabMessage = {
+          type,
+          projectId,
+          sessionId,
+          data
+        };
+        this.broadcastChannel.postMessage(message);
+      } catch (error) {
+        console.warn('[UploadSessionManager] Failed to broadcast message:', error);
+      }
+    }
+  }
+
+  /**
+   * Cleanup resources
+   */
+  public destroy(): void {
+    if (this.broadcastChannel) {
+      this.broadcastChannel.close();
+      this.broadcastChannel = undefined;
+    }
+    this.messageListeners.clear();
+  }
+}
+
+// Export a singleton instance for convenience
+export const uploadSessionManager = UploadSessionManager.getInstance();