@nurama/sdk 0.0.0-stage → 1.4.1

package/src/routes/chatAi.ts

@@ -0,0 +1,125 @@
+import NuramaClient from '../NuramaClient.js';
+import type {
+  AiChatListTopicsParams,
+  AiChatListTopicsResponse,
+  AiChatCreateTopicRequest,
+  AiChatCreateTopicResponse,
+  AiChatGetTopicResponse,
+  AiChatUpdateTopicRequest,
+} from '@nurama/types';
+
+/**
+ * Topic-CRUD methods for AI chat. Message send + list happens through
+ * the regular chat endpoints on `nuramaClient.chat`:
+ *
+ *   - send:  `nuramaClient.chat.createMessage(topic.chatId, …)`
+ *   - list:  `nuramaClient.chat.getMessages(topic.chatId, …)`
+ *
+ * The backend's `chat.service.createMessage` detects `chatType === 'ai'`
+ * and fires the AI orchestrator as a tail call so the same path that
+ * powers every other chat surface (attachments, mentions, link previews,
+ * link‐preview generation, notifications) carries AI chat too.
+ *
+ * Each topic is private to its creator. Topic scope is one of:
+ *   - 'workspace' → cross-project chat in the workspace
+ *   - 'project'   → bound to a single project
+ *   - 'social'    → personal chat with no resource backing
+ *
+ * All endpoints below require:
+ *   - workspace AI add-on subscription
+ *   - `aiChatEnabled` resolved true (workspace setting + project override)
+ *   - caller has project / workspace read access for scoped topics
+ *
+ * Credit-balance gating happens server-side on the regular chat
+ * `createMessage` path when the target chat is an AI chat.
+ */
+export default function createAiChatMethods(client: NuramaClient) {
+  const buildQuery = (params: Record<string, unknown>): string => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null || value === '') continue;
+      search.set(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `?${query}` : '';
+  };
+
+  return {
+    /** List the caller's topics for a scope (workspace, project, or social). */
+    async listTopics(params: AiChatListTopicsParams): Promise<AiChatListTopicsResponse> {
+      if (!params?.workspaceId) throw new Error('workspaceId is required.');
+      if (!params?.scopeType) throw new Error('scopeType is required.');
+      if (params.scopeType !== 'social' && !params.scopeId) {
+        throw new Error('scopeId is required for workspace/project scope.');
+      }
+      return client._request({
+        endpoint: `/v1/ai/chat/topics${buildQuery(params as unknown as Record<string, unknown>)}`,
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Create a new (empty) topic. After this resolves, send the first
+     * message through `nuramaClient.chat.createMessage(topic.chatId, …)`.
+     */
+    async createTopic(data: AiChatCreateTopicRequest): Promise<AiChatCreateTopicResponse> {
+      if (!data?.workspaceId) throw new Error('workspaceId is required.');
+      if (!data?.scopeType) throw new Error('scopeType is required.');
+      if (data.scopeType !== 'social' && !data.scopeId) {
+        throw new Error('scopeId is required for workspace/project scope.');
+      }
+      return client._request({
+        endpoint: '/v1/ai/chat/topics',
+        method: 'POST',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    async getTopic(
+      topicId: string,
+      params: { workspaceId: string },
+    ): Promise<AiChatGetTopicResponse> {
+      if (!topicId) throw new Error('topicId is required.');
+      return client._request({
+        endpoint: `/v1/ai/chat/topics/${encodeURIComponent(topicId)}${buildQuery(params)}`,
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+
+    async updateTopic(
+      topicId: string,
+      data: AiChatUpdateTopicRequest,
+    ): Promise<AiChatGetTopicResponse> {
+      if (!topicId) throw new Error('topicId is required.');
+      return client._request({
+        endpoint: `/v1/ai/chat/topics/${encodeURIComponent(topicId)}`,
+        method: 'PATCH',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Soft-delete a topic. The backend flips the topic + its backing
+     * chat + every chat-scoped attachment asset to `pendingDelete`;
+     * the file-management sweeper handles the actual S3 + DB cleanup
+     * asynchronously. The caller can drop the row from their local
+     * list immediately — there's no "undo" surface for this.
+     */
+    async deleteTopic(
+      topicId: string,
+      params: { workspaceId: string },
+    ): Promise<AiChatGetTopicResponse> {
+      if (!topicId) throw new Error('topicId is required.');
+      return client._request({
+        endpoint: `/v1/ai/chat/topics/${encodeURIComponent(topicId)}${buildQuery(params)}`,
+        method: 'DELETE',
+        sendJWT: true,
+      });
+    },
+
+  };
+}

package/src/routes/config.ts

@@ -0,0 +1,31 @@
+// import { Config } from '@nurama/types'; // Removed temporarily due to import resolution issues
+import type NuramaClient from '../NuramaClient'; // Use type import for client
+
+// Define the shape of the returned object
+export interface ConfigMethods {
+  getConfig: () => Promise<any>;
+}
+
+/**
+ * Creates methods related to configuration endpoints.
+ * @param client - The NuramaClient instance.
+ * @returns An object with configuration-related methods.
+ */
+export default function createConfigMethods(client: NuramaClient): ConfigMethods {
+  return {
+    /**
+     * Retrieves the application configuration.
+     *
+     * @returns {Promise<any>} A promise that resolves with the configuration object.
+     * @throws {ApiError} Throws an ApiError if the request fails.
+     */
+    getConfig: async (): Promise<any> => {
+      // client._log('[DEBUG] Fetching application configuration'); // Logging is handled by _request
+      return client._request<any>({
+        endpoint: '/v1/config',
+        method: 'GET',
+        sendJWT: false, // This endpoint does not require authentication
+      });
+    },
+  };
+} 

package/src/routes/convo.ts

@@ -0,0 +1,321 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type StartConvoRequest,
+  type StartConvoResponse,
+  type GetConvoResponse,
+  type JoinConvoResponse,
+  type LeaveConvoResponse,
+  type CompleteConvoResponse,
+  type UpdateConvoRequest,
+  type UpdateConvoResponse,
+  type GetScopeConvosResponse,
+  type PromoteConvoArtifactRequest,
+  type PromoteConvoArtifactResponse,
+  type Convo,
+} from '@nurama/types';
+
+/**
+ * Defines convo (video/audio chat) related methods for the NuramaClient.
+ * Handles starting, joining, and managing real-time conversations.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the convo-related methods.
+ */
+export default function createConvoMethods(client: NuramaClient) {
+  return {
+    /**
+     * Start a new conversation (video or audio).
+     * Requires authentication.
+     * @param {StartConvoRequest} data - Conversation start data.
+     * @returns {Promise<StartConvoResponse>} The created conversation and room details.
+     * @example
+     * const result = await client.convo.startConvo({
+     *   chatId: '507f1f77bcf86cd799439011',
+     *   chatType: 'chat',
+     *   convoType: 'video'
+     * });
+     */
+    async startConvo(data: StartConvoRequest): Promise<StartConvoResponse> {
+      if (!data.chatId || !data.chatType || !data.convoType) {
+        throw new Error('chatId, chatType, and convoType are required.');
+      }
+      return client._request<StartConvoResponse>({
+        method: 'POST',
+        endpoint: '/v1/convos',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Get a specific conversation by ID.
+     * Requires authentication and permission to view the conversation.
+     * @param {string} convoId - The conversation ID.
+     * @returns {Promise<GetConvoResponse>} The conversation details.
+     * @example
+     * const result = await client.convo.getConvo('507f1f77bcf86cd799439011');
+     */
+    async getConvo(convoId: string): Promise<GetConvoResponse> {
+      if (!convoId) {
+        throw new Error('convoId is required.');
+      }
+      return client._request<GetConvoResponse>({
+        method: 'GET',
+        endpoint: `/v1/convos/${convoId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Join an active conversation.
+     * Returns the conversation details and a Daily.co meeting token for the user.
+     * Requires authentication and permission to join the conversation.
+     * @param {string} convoId - The conversation ID.
+     * @returns {Promise<JoinConvoResponse>} The conversation and meeting token.
+     * @example
+     * const result = await client.convo.joinConvo('507f1f77bcf86cd799439011');
+     * // Use result.token to join the Daily.co call
+     * // Use result.convo.dailyRoomUrl as the room URL
+     */
+    async joinConvo(convoId: string): Promise<JoinConvoResponse> {
+      if (!convoId) {
+        throw new Error('convoId is required.');
+      }
+      return client._request<JoinConvoResponse>({
+        method: 'PUT',
+        endpoint: `/v1/convos/${convoId}/join`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Rejoin an active conversation (page refresh / reconnect).
+     * Only returns a new meeting token if the user is already an active participant.
+     * No notifications are sent.
+     * @param {string} convoId - The conversation ID.
+     * @returns {Promise<JoinConvoResponse>} The conversation and meeting token.
+     */
+    async rejoinConvo(convoId: string): Promise<JoinConvoResponse> {
+      if (!convoId) {
+        throw new Error('convoId is required.');
+      }
+      return client._request<JoinConvoResponse>({
+        method: 'PUT',
+        endpoint: `/v1/convos/${convoId}/rejoin`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Leave an active conversation.
+     * Removes the user from the active participants list.
+     * Requires authentication.
+     * @param {string} convoId - The conversation ID.
+     * @returns {Promise<LeaveConvoResponse>} The updated conversation.
+     * @example
+     * const result = await client.convo.leaveConvo('507f1f77bcf86cd799439011');
+     */
+    async leaveConvo(convoId: string): Promise<LeaveConvoResponse> {
+      if (!convoId) {
+        throw new Error('convoId is required.');
+      }
+      return client._request<LeaveConvoResponse>({
+        method: 'PUT',
+        endpoint: `/v1/convos/${convoId}/leave`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Mark a conversation as complete.
+     * Ends the conversation and triggers recording/transcript processing if enabled.
+     * Requires authentication and permission to complete the conversation.
+     * @param {string} convoId - The conversation ID.
+     * @returns {Promise<CompleteConvoResponse>} The completed conversation.
+     * @example
+     * const result = await client.convo.completeConvo('507f1f77bcf86cd799439011');
+     */
+    async completeConvo(convoId: string): Promise<CompleteConvoResponse> {
+      if (!convoId) {
+        throw new Error('convoId is required.');
+      }
+      return client._request<CompleteConvoResponse>({
+        method: 'PUT',
+        endpoint: `/v1/convos/${convoId}/complete`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Delete/cancel a conversation.
+     * Only the creator can delete a conversation.
+     * Requires authentication and permission to delete the conversation.
+     * @param {string} convoId - The conversation ID.
+     * @returns {Promise<void>} Resolves with no value; the API responds 204.
+     * @example
+     * await client.convo.deleteConvo('507f1f77bcf86cd799439011');
+     */
+    async deleteConvo(convoId: string): Promise<void> {
+      if (!convoId) {
+        throw new Error('convoId is required.');
+      }
+      await client._request<null>({
+        method: 'DELETE',
+        endpoint: `/v1/convos/${convoId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Update a conversation's subject and/or description.
+     * Only the conversation starter can update these fields.
+     * Requires authentication.
+     * @param {string} convoId - The conversation ID.
+     * @param {UpdateConvoRequest} data - Update data containing subject and/or description.
+     * @returns {Promise<UpdateConvoResponse>} The updated conversation.
+     * @example
+     * const result = await client.convo.updateConvo('507f1f77bcf86cd799439011', {
+     *   subject: 'Weekly Team Sync',
+     *   description: 'Discussing project updates and roadmap'
+     * });
+     */
+    async updateConvo(convoId: string, data: UpdateConvoRequest): Promise<UpdateConvoResponse> {
+      if (!convoId) {
+        throw new Error('convoId is required.');
+      }
+      return client._request<UpdateConvoResponse>({
+        method: 'PATCH',
+        endpoint: `/v1/convos/${convoId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List the convos that have taken place in a chat, newest first.
+     * Requires read access to the chat.
+     * @param {string} chatId - The chat ID.
+     * @param {object} [params] - Optional filter.
+     * @param {'active'|'completed'|'cancelled'} [params.status] - Only convos in this status.
+     * @returns {Promise<Convo[]>} Convos for the chat.
+     */
+    async getChatConvos(chatId: string, params?: { status?: 'active' | 'completed' | 'cancelled' }): Promise<Convo[]> {
+      if (!chatId) throw new Error('chatId is required.');
+      return client._request<Convo[]>({
+        method: 'GET',
+        endpoint: `/v1/chats/${chatId}/convos`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List every convo across all chats in a project (the "Convos drawer"), newest first.
+     * Requires `canGetProject` on the project.
+     * @param {string} projectId - The project ID.
+     * @param {object} [params] - Optional filters.
+     * @param {'creator'|'reviewer'} [params.visibility] - Only convos from chats with this visibility.
+     * @param {'active'|'completed'|'cancelled'} [params.status] - Only convos in this status.
+     * @returns {Promise<Convo[]>} Convos for the project.
+     */
+    async getProjectConvos(
+      projectId: string,
+      params?: { visibility?: 'creator' | 'reviewer'; status?: 'active' | 'completed' | 'cancelled' },
+    ): Promise<Convo[]> {
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<Convo[]>({
+        method: 'GET',
+        endpoint: `/v1/projects/${projectId}/convos`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Get conversations for a scope (project).
+     * Returns paginated list of conversations with cursor-based pagination.
+     * Active conversations are returned first.
+     * Requires authentication and permission to view conversations.
+     * @param {string} scopeId - The scope (project) ID.
+     * @param {object} params - Query parameters.
+     * @param {string[]} params.visibility - Array of visibility levels ('creator', 'reviewer').
+     * @param {string} [params.status] - Filter by status ('active', 'completed', 'cancelled').
+     * @param {string} [params.search] - Search query for participant names.
+     * @param {number} [params.limit=20] - Number of results per page.
+     * @param {string} [params.cursor] - Cursor for pagination.
+     * @param {boolean} [params.includeCounts] - Include total counts.
+     * @returns {Promise<GetScopeConvosResponse>} Paginated conversation list.
+     * @example
+     * const result = await client.convo.getScopeConvos('507f1f77bcf86cd799439011', {
+     *   visibility: ['creator', 'reviewer'],
+     *   status: 'active',
+     *   limit: 20
+     * });
+     */
+    /**
+     * Promote a convo's recording or transcript to a standalone asset.
+     *
+     * Additive: the artifact stays bundled with the convo as well, so calling
+     * this twice returns the first asset with `alreadyPromoted: true` rather
+     * than making a second copy.
+     *
+     * Only the convo's starter may promote. A transcript is promoted as a text
+     * document built from the transcript text, not the raw .vtt.
+     * @param {string} convoId - The conversation ID.
+     * @param {'recording'|'transcript'} kind - Which artifact to promote.
+     * @param {string} dailyId - The provider's id for the artifact, taken from
+     *   the convo's `recordings` / `transcripts` entries.
+     * @param {PromoteConvoArtifactRequest} [data] - Optional display name.
+     * @returns {Promise<PromoteConvoArtifactResponse>} The asset, and whether it already existed.
+     * @example
+     * const { asset } = await client.convo.promoteConvoArtifact(convoId, 'recording', rec.dailyId);
+     */
+    async promoteConvoArtifact(
+      convoId: string,
+      kind: 'recording' | 'transcript',
+      dailyId: string,
+      data?: PromoteConvoArtifactRequest,
+    ): Promise<PromoteConvoArtifactResponse> {
+      if (!convoId) throw new Error('convoId is required.');
+      if (!dailyId) throw new Error('dailyId is required.');
+      return client._request<PromoteConvoArtifactResponse>({
+        method: 'POST',
+        endpoint: `/v1/convos/${convoId}/artifacts/${kind}/${dailyId}/promote`,
+        body: data ?? {},
+        sendJWT: true,
+      });
+    },
+
+    async getScopeConvos(
+      scopeId: string,
+      params: {
+        visibility: string[];
+        status?: string;
+        search?: string;
+        limit?: number;
+        cursor?: string;
+        includeCounts?: boolean;
+      }
+    ): Promise<GetScopeConvosResponse> {
+      if (!scopeId) {
+        throw new Error('scopeId is required.');
+      }
+      if (!params.visibility || params.visibility.length === 0) {
+        throw new Error('visibility array is required and must not be empty.');
+      }
+
+      const queryParams = new URLSearchParams();
+      params.visibility.forEach((vis) => queryParams.append('visibility[]', vis));
+      if (params.status) queryParams.append('status', params.status);
+      if (params.search) queryParams.append('search', params.search);
+      if (params.limit) queryParams.append('limit', params.limit.toString());
+      if (params.cursor) queryParams.append('cursor', params.cursor);
+      if (params.includeCounts) queryParams.append('includeCounts', 'true');
+
+      return client._request<GetScopeConvosResponse>({
+        method: 'GET',
+        endpoint: `/v1/convos/scope/${scopeId}?${queryParams.toString()}`,
+        sendJWT: true,
+      });
+    },
+  };
+}

package/src/routes/credits.ts

@@ -0,0 +1,112 @@
+import NuramaClient from '../NuramaClient.js';
+
+export interface GetBalanceResponse {
+  /** Total spendable balance — sum of planBalance + purchasedBalance. */
+  balance: number;
+  /**
+   * Plan-granted credits for the current billing cycle. Refreshed (SET, not
+   * added) on every Stripe renewal. Unspent plan credits do NOT carry over.
+   */
+  planBalance: number;
+  /**
+   * Purchased credits — accumulated from one-off top-ups, auto-top-ups, admin
+   * grants. Carries over indefinitely.
+   */
+  purchasedBalance: number;
+  /**
+   * True when the workspace has at least one prior manual top-up
+   * (`subscriptionGrant` order). Powers the FE auto-top-up enable gate —
+   * users must top up manually once before auto top-up can be enabled.
+   */
+  hasPriorTopUp?: boolean;
+}
+
+export interface UsageReportParams {
+  /** ISO date string. Server defaults to 30 days ago when omitted. */
+  startDate?: string;
+  /** ISO date string. Server defaults to "now" when omitted. */
+  endDate?: string;
+  /** Narrow the per-integration breakdown to a single user's calls. */
+  userId?: string;
+  /** Narrow the per-user breakdown to a single integration point. */
+  integrationPoint?: string;
+}
+
+export interface UsageReportUserRow {
+  userId: string;
+  displayName: string | null;
+  avatar: unknown | null;
+  color: string | null;
+  billedCredits: number;
+  callCount: number;
+}
+
+export interface UsageReportIntegrationRow {
+  integrationPoint: string;
+  billedCredits: number;
+  callCount: number;
+}
+
+export interface UsageReportResponse {
+  total: {
+    billedCredits: number;
+    callCount: number;
+    tokensIn: number;
+    tokensOut: number;
+  };
+  byUser: UsageReportUserRow[];
+  byIntegration: UsageReportIntegrationRow[];
+  filters: {
+    startDate: string;
+    endDate: string;
+    userId: string | null;
+    integrationPoint: string | null;
+  };
+}
+
+/**
+ * Service-agnostic Nurama Credit balance + usage endpoints.
+ *
+ * The `/v1/credits/*` route shape and SDK namespace are deliberately
+ * decoupled from any single service's naming so future services (convos,
+ * etc.) can draw from the same balance without callers having to know
+ * where the spend originated. Today the metered data is AI-only because
+ * AI is the only service that's metered, but the contract is stable.
+ */
+export default function createCreditsMethods(client: NuramaClient) {
+  return {
+    /**
+     * Get the workspace's spendable credit balance.
+     */
+    async getBalance(workspaceId: string): Promise<GetBalanceResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        endpoint: `/v1/credits/balance?workspaceId=${encodeURIComponent(workspaceId)}`,
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Get the workspace's credit usage report. Same shape as the AI usage
+     * report — today the data is AI-only because AI is the only service
+     * that's metered.
+     */
+    async getUsageReport(
+      workspaceId: string,
+      params: UsageReportParams = {},
+    ): Promise<UsageReportResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      const query = new URLSearchParams({ workspaceId });
+      if (params.startDate) query.set('startDate', params.startDate);
+      if (params.endDate) query.set('endDate', params.endDate);
+      if (params.userId) query.set('userId', params.userId);
+      if (params.integrationPoint) query.set('integrationPoint', params.integrationPoint);
+      return client._request({
+        endpoint: `/v1/credits/usage?${query.toString()}`,
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+  };
+}