@nurama/sdk 0.0.0-stage → 1.4.0

package/src/routes/board.ts

@@ -0,0 +1,403 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type Board,
+  type BoardColumn,
+  type BoardWithTasks,
+  type Task,
+} from '@nurama/types';
+
+// --- Request Body Interfaces ---
+
+export interface CreateBoardData {
+  projectId: string;
+  name: string;
+  description?: string;
+  visibility?: ('creator' | 'reviewer')[];
+  columns?: {
+    name: string;
+    description?: string;
+    color?: string;
+    isDefault?: boolean;
+    taskStatus?: 'pending' | 'inProgress' | 'complete' | 'closed' | null;
+    sortOrder?: number;
+  }[];
+}
+
+export interface UpdateBoardData {
+  name?: string;
+  description?: string | null;
+  visibility?: ('creator' | 'reviewer')[];
+  status?: 'active' | 'archived';
+  sortOrder?: number;
+  /**
+   * When narrowing visibility, opt into automatic cleanup of dependent tasks,
+   * assignees, and relations. If omitted (or false) and dependents exist, the
+   * server returns 409 with a structured `errorData.blockers` payload.
+   */
+  cascade?: boolean;
+}
+
+export interface AddColumnData {
+  name: string;
+  description?: string;
+  color?: string;
+  isDefault?: boolean;
+  taskStatus?: 'pending' | 'inProgress' | 'complete' | 'closed' | null;
+  sortOrder?: number;
+  /** When true, reviewer-role users may create tasks in this column on a reviewer-visibility board. */
+  reviewersCanContribute?: boolean;
+}
+
+export interface UpdateColumnData {
+  name?: string;
+  description?: string | null;
+  color?: string | null;
+  isDefault?: boolean;
+  taskStatus?: 'pending' | 'inProgress' | 'complete' | 'closed' | null;
+  sortOrder?: number;
+  /** When true, reviewer-role users may create tasks in this column on a reviewer-visibility board. */
+  reviewersCanContribute?: boolean;
+}
+
+export interface ReorderColumnsData {
+  columns: { id: string; sortOrder: number }[];
+}
+
+export interface CreateBoardTaskData {
+  subject: string;
+  description?: string;
+  assignedToId?: string;
+  columnId?: string;
+  /** Optional announce flag. When supplied, after the task is created
+   *  the server posts a Nu reply in `chatId` threaded under `messageId`
+   *  with this task as a single taskCard and links them via TaskRelation.
+   *  Mirrors the same flag on `tasks.bulkCreate`. */
+  announce?: {
+    chatId: string;
+    messageId: string;
+  };
+}
+
+export interface AddExistingTaskData {
+  taskId: string;
+  columnId?: string;
+}
+
+export interface MoveTaskData {
+  /** Required for same-board moves; optional when `targetBoardId` is
+   *  set (server defaults to the target board's default column). */
+  columnId?: string;
+  sortOrder?: number;
+  /** When supplied AND different from the URL `boardId`, the server
+   *  performs a cross-board move — `boardId` and `columnId` are
+   *  updated together. Omit for the original same-board move. */
+  targetBoardId?: string;
+}
+
+export interface UpdateTaskDetailsData {
+  subject?: string;
+  description?: string | null;
+  assignedToId?: string | null;
+}
+
+export interface LinkTaskData {
+  linkedTaskId: string;
+  linkType?: 'related' | 'blocks' | 'blockedBy' | 'duplicate';
+}
+
+// --- Method Definitions ---
+
+export default function createBoardMethods(client: NuramaClient) {
+  return {
+    // ========================================================================
+    // Board CRUD
+    // ========================================================================
+
+    /**
+     * Create a new board inside a project. If `columns` are omitted the
+     * server seeds the standard four-column layout.
+     */
+    async createBoard(data: CreateBoardData): Promise<Board> {
+      if (!data.projectId) throw new Error('projectId is required.');
+      if (!data.name) throw new Error('name is required.');
+      return client._request<Board>({
+        method: 'POST',
+        endpoint: '/v1/boards/',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List boards in a project. Filters by visibility, free-text search,
+     * and tag ids.
+     */
+    async getProjectBoards(projectId: string, params?: { visibility?: string; search?: string; tags?: string[] }): Promise<Board[]> {
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<Board[]>({
+        method: 'GET',
+        endpoint: `/v1/boards/project/${projectId}`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List every task in a project across all boards. Use `boardId:
+     * 'unassigned'` to fetch only tasks not yet placed on a board.
+     */
+    async getProjectTasks(projectId: string, params?: {
+      search?: string;
+      status?: string;
+      boardId?: string | 'unassigned';
+      columnId?: string;
+      assignedToId?: string;
+      visibility?: string;
+      tags?: string[];
+      page?: number;
+      limit?: number;
+      sort?: Record<string, 1 | -1>;
+    }): Promise<any> {
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<any>({
+        method: 'GET',
+        endpoint: `/v1/boards/project/${projectId}/tasks`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /** Fetch a board with its columns and tasks populated. */
+    async getBoard(boardId: string): Promise<BoardWithTasks> {
+      if (!boardId) throw new Error('boardId is required.');
+      return client._request<BoardWithTasks>({
+        method: 'GET',
+        endpoint: `/v1/boards/${boardId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Update a board's metadata. Set `cascade: true` to opt into
+     * automatic cleanup of dependent tasks when narrowing visibility;
+     * otherwise the server returns 409 with a `blockers` payload.
+     */
+    async updateBoard(boardId: string, data: UpdateBoardData): Promise<Board> {
+      if (!boardId) throw new Error('boardId is required.');
+      return client._request<Board>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Delete a board. `disposition` controls what happens to its tasks:
+     * `unassign` (default — tasks survive boardless), `delete`, or
+     * `reassign` to another board/column.
+     */
+    async deleteBoard(
+      boardId: string,
+      body?: {
+        disposition?: 'unassign' | 'delete' | 'reassign';
+        targetBoardId?: string;
+        targetColumnId?: string;
+      }
+    ): Promise<{ message: string; disposition: string; deletedTaskIds: string[]; reassignedTaskIds: string[] }> {
+      if (!boardId) throw new Error('boardId is required.');
+      return client._request({
+        method: 'DELETE',
+        endpoint: `/v1/boards/${boardId}`,
+        body: body && Object.keys(body).length > 0 ? body : undefined,
+        sendJWT: true,
+      });
+    },
+
+    // ========================================================================
+    // Column Operations
+    // ========================================================================
+
+    /** Add a column to a board. Appended at the end unless `sortOrder` is provided. */
+    async addColumn(boardId: string, data: AddColumnData): Promise<BoardColumn> {
+      if (!boardId) throw new Error('boardId is required.');
+      if (!data.name) throw new Error('name is required.');
+      return client._request<BoardColumn>({
+        method: 'POST',
+        endpoint: `/v1/boards/${boardId}/columns`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** Reorder a board's columns. The request must include every column id. */
+    async reorderColumns(boardId: string, data: ReorderColumnsData): Promise<BoardColumn[]> {
+      if (!boardId) throw new Error('boardId is required.');
+      return client._request<BoardColumn[]>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}/columns/reorder`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** Update column metadata (name, color, task-status mapping, etc.). */
+    async updateColumn(boardId: string, columnId: string, data: UpdateColumnData): Promise<BoardColumn> {
+      if (!boardId) throw new Error('boardId is required.');
+      if (!columnId) throw new Error('columnId is required.');
+      return client._request<BoardColumn>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}/columns/${columnId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Delete a column. If the column holds tasks, pass `targetColumnId`
+     * to move them; otherwise the call fails.
+     */
+    async deleteColumn(boardId: string, columnId: string, targetColumnId?: string): Promise<void> {
+      if (!boardId) throw new Error('boardId is required.');
+      if (!columnId) throw new Error('columnId is required.');
+      return client._request<void>({
+        method: 'DELETE',
+        endpoint: `/v1/boards/${boardId}/columns/${columnId}`,
+        body: targetColumnId ? { targetColumnId } : undefined,
+        sendJWT: true,
+      });
+    },
+
+    // ========================================================================
+    // Board Task Operations
+    // ========================================================================
+
+    /** List tasks on a board, optionally narrowed by column / assignee / tag / status / search. */
+    async getBoardTasks(
+      boardId: string,
+      params?: {
+        columnId?: string;
+        search?: string;
+        status?: string;
+        assignedToId?: string;
+        tags?: string[];
+      }
+    ): Promise<Task[]> {
+      if (!boardId) throw new Error('boardId is required.');
+      return client._request<Task[]>({
+        method: 'GET',
+        endpoint: `/v1/boards/${boardId}/tasks`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Create a task directly on a board. When `announce` is supplied the
+     * server also posts a Nu reply in the named chat threaded under the
+     * given message, with this task linked via TaskRelation.
+     */
+    async createBoardTask(boardId: string, data: CreateBoardTaskData): Promise<Task> {
+      if (!boardId) throw new Error('boardId is required.');
+      if (!data.subject) throw new Error('subject is required.');
+      return client._request<Task>({
+        method: 'POST',
+        endpoint: `/v1/boards/${boardId}/tasks`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** Attach an existing project task to a board (no new task is created). */
+    async addExistingTaskToBoard(boardId: string, data: AddExistingTaskData): Promise<Task> {
+      if (!boardId) throw new Error('boardId is required.');
+      if (!data.taskId) throw new Error('taskId is required.');
+      return client._request<Task>({
+        method: 'POST',
+        endpoint: `/v1/boards/${boardId}/tasks/add`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** Move a task to a different column on the same board. */
+    async moveTask(boardId: string, taskId: string, data: MoveTaskData): Promise<Task> {
+      if (!boardId) throw new Error('boardId is required.');
+      if (!taskId) throw new Error('taskId is required.');
+      if (!data.columnId) throw new Error('columnId is required.');
+      return client._request<Task>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}/tasks/${taskId}/move`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** Detach a task from a board. The task itself is preserved as boardless. */
+    async removeTaskFromBoard(boardId: string, taskId: string): Promise<Task> {
+      if (!boardId) throw new Error('boardId is required.');
+      if (!taskId) throw new Error('taskId is required.');
+      return client._request<Task>({
+        method: 'DELETE',
+        endpoint: `/v1/boards/${boardId}/tasks/${taskId}`,
+        sendJWT: true,
+      });
+    },
+
+    // ========================================================================
+    // Task Detail Operations
+    // ========================================================================
+
+    // ========================================================================
+    // Task Link Operations
+    // ========================================================================
+
+    // ========================================================================
+    // Tagging
+    // ========================================================================
+
+    /** Attach a tag to a board. */
+    async tagBoard(boardId: string, tagId: string): Promise<Board> {
+      return client._request<Board>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}/tag`,
+        body: { tagId },
+        sendJWT: true,
+      });
+    },
+
+    /** Detach a tag from a board. */
+    async untagBoard(boardId: string, tagId: string): Promise<Board> {
+      return client._request<Board>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}/untag`,
+        body: { tagId },
+        sendJWT: true,
+      });
+    },
+
+    // ========================================================================
+    // Following
+    // ========================================================================
+
+    /** Follow a board to receive notifications about its tasks. */
+    async followBoard(boardId: string): Promise<Board> {
+      if (!boardId) throw new Error('boardId is required.');
+      return client._request<Board>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}/follow`,
+        sendJWT: true,
+      });
+    },
+
+    /** Stop following a board. */
+    async unfollowBoard(boardId: string): Promise<Board> {
+      if (!boardId) throw new Error('boardId is required.');
+      return client._request<Board>({
+        method: 'PUT',
+        endpoint: `/v1/boards/${boardId}/unfollow`,
+        sendJWT: true,
+      });
+    },
+  };
+}

package/src/routes/bot.ts

@@ -0,0 +1,257 @@
+import NuramaClient from '../NuramaClient.js';
+
+export interface BotApiKeySummary {
+  id: string;
+  keyPrefix: string;
+  name: string;
+  /** Discriminator. Bot keys mint as 'botAccess'. */
+  kind?: 'botAccess' | 'pat' | 'oauthAccess' | 'oauthRefresh' | null;
+  /** Granted action verbs. Empty array = unscoped (legacy). */
+  scopes?: string[];
+  lastUsed?: string | null;
+  expiresAt?: string | null;
+  status: 'active' | 'revoked';
+  createdAt: string;
+}
+
+export interface Bot {
+  id: string;
+  displayName: string;
+  color: string;
+  accountType: 'bot';
+  status: string;
+  avatarId: string | null;
+  /**
+   * Populated avatar Asset (joined server-side from `avatarId`). The web client
+   * resolves the image URL from this field via `getAvatarUrl()`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  avatar?: any | null;
+  roles?: string[];
+  membershipId?: string;
+  apiKeys?: BotApiKeySummary[];
+  apiKey?: BotApiKeySummary;
+  /**
+   * Project memberships within the workspace the bot belongs to. Populated by
+   * `listBots` and `getBot`. Empty array if the bot has no project assignments.
+   */
+  projectMemberships?: BotProjectMembership[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateBotData {
+  /** Display name for the bot. 1–50 characters. */
+  name: string;
+  /** Optional hex color from the approved palette. Auto-assigned if omitted. */
+  color?: string;
+  /** Workspace roles to grant the bot. Must be one or more of:
+   *  workspaceAdmin, workspaceMember, workspaceChatMember. */
+  roles: Array<'workspaceAdmin' | 'workspaceMember' | 'workspaceChatMember'>;
+  /**
+   * Optional API-key scopes. Defaults to [] (legacy — bot key can call
+   * any route that isn't yet scope-gated). Once a route is gated by
+   * `requireTokenScope` the bot needs the matching scope here for that
+   * route to work.
+   */
+  scopes?: string[];
+}
+
+export interface CreateBotResponse {
+  bot: Bot;
+  /** Raw API key, returned ONCE at creation time. Store it immediately — it
+   *  cannot be retrieved again. */
+  rawKey: string;
+}
+
+export interface UpdateBotData {
+  name?: string;
+  color?: string;
+}
+
+export interface RotateBotKeyResponse {
+  apiKey: BotApiKeySummary;
+  /** New raw API key. Returned once. */
+  rawKey: string;
+}
+
+export interface UpdateBotAvatarFileData {
+  name: string;
+  sizeInMB: number;
+  checksum: string;
+}
+
+export interface UpdateBotAvatarResponse {
+  user: { id: string; avatarId: string | null };
+  asset?: { id: string; [k: string]: unknown };
+  signedUrlData?: {
+    key: string;
+    uploadId: string;
+    urls: string[];
+  };
+  [k: string]: unknown;
+}
+
+export type BotProjectRole = 'creator' | 'reviewer' | 'projectAdmin';
+
+export interface BotProjectMembership {
+  membershipId: string;
+  projectId: string;
+  projectName: string;
+  roles: BotProjectRole[];
+}
+
+/**
+ * Bot user administration methods. Used by workspace owners/admins (callers
+ * holding a JWT) to manage bot users in a workspace. Bots themselves cannot
+ * call these endpoints — bot administration is restricted server-side.
+ */
+export default function createBotMethods(client: NuramaClient) {
+  return {
+    /**
+     * Create a bot user in a workspace.
+     * Returns the new bot and the raw API key (shown only once).
+     */
+    async createBot(workspaceId: string, data: CreateBotData): Promise<CreateBotResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<CreateBotResponse>({
+        method: 'POST',
+        endpoint: `/v1/workspaces/${workspaceId}/bots`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** List bot users in a workspace. */
+    async listBots(workspaceId: string): Promise<Bot[]> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<Bot[]>({
+        method: 'GET',
+        endpoint: `/v1/workspaces/${workspaceId}/bots`,
+        sendJWT: true,
+        bypassCache: true,
+      });
+    },
+
+    /** Get a single bot's details, including all of its API key metadata (no secrets). */
+    async getBot(workspaceId: string, botId: string): Promise<Bot> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      return client._request<Bot>({
+        method: 'GET',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}`,
+        sendJWT: true,
+        bypassCache: true,
+      });
+    },
+
+    /** Update a bot's display name and/or color. */
+    async updateBot(workspaceId: string, botId: string, data: UpdateBotData): Promise<Bot> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      return client._request<Bot>({
+        method: 'PUT',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Delete a bot user. Revokes all API keys, removes the workspace
+     * membership, and marks the user inactive.
+     */
+    async deleteBot(workspaceId: string, botId: string): Promise<void> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      return client._request<void>({
+        method: 'DELETE',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Revoke the bot's current API key and issue a new one.
+     * The new raw key is returned once.
+     */
+    async rotateBotKey(workspaceId: string, botId: string): Promise<RotateBotKeyResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      return client._request<RotateBotKeyResponse>({
+        method: 'POST',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}/rotate-key`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Request signed URL data to upload a new avatar for the bot.
+     * Caller multipart-uploads the file to S3 using the returned `signedUrlData`,
+     * then calls `client.asset.completeUpload(...)` to finalize.
+     */
+    async updateBotAvatar(
+      workspaceId: string,
+      botId: string,
+      fileData: UpdateBotAvatarFileData,
+    ): Promise<UpdateBotAvatarResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      return client._request<UpdateBotAvatarResponse>({
+        method: 'POST',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}/avatar`,
+        body: fileData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List the bot's project memberships within the workspace.
+     */
+    async listProjectMemberships(workspaceId: string, botId: string): Promise<BotProjectMembership[]> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      return client._request<BotProjectMembership[]>({
+        method: 'GET',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}/memberships`,
+        sendJWT: true,
+        bypassCache: true,
+      });
+    },
+
+    /**
+     * Upsert the bot's membership on a project. Replaces roles if a membership
+     * already exists; creates one otherwise. Idempotent.
+     */
+    async setProjectMembership(
+      workspaceId: string,
+      botId: string,
+      projectId: string,
+      data: { roles: BotProjectRole[] },
+    ): Promise<BotProjectMembership> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<BotProjectMembership>({
+        method: 'PUT',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}/memberships/project/${projectId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Remove the bot's membership on a project. Idempotent.
+     */
+    async removeProjectMembership(workspaceId: string, botId: string, projectId: string): Promise<void> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!botId) throw new Error('botId is required.');
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<void>({
+        method: 'DELETE',
+        endpoint: `/v1/workspaces/${workspaceId}/bots/${botId}/memberships/project/${projectId}`,
+        sendJWT: true,
+      });
+    },
+  };
+}