@37signals/basecamp 0.20.0 → 0.22.0

package/src/generated/services/subtasks.ts

@@ -0,0 +1,336 @@
+/**
+ * Subtasks service for the Basecamp API.
+ *
+ * @generated from OpenAPI spec - do not edit directly
+ */
+
+import { BaseService } from "../../services/base.js";
+import type { components } from "../schema.js";
+import { ListResult } from "../../pagination.js";
+import type { PaginationOptions } from "../../pagination.js";
+import { Errors } from "../../errors.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Subtask entity from the Basecamp API. */
+export type Subtask = components["schemas"]["Subtask"];
+/** @deprecated renamed to Subtask, the same Kanban::Step record. */
+export type CardStep = Subtask;
+
+/**
+ * Options for list.
+ */
+export interface ListSubtaskOptions extends PaginationOptions {
+  /** Page number for paginating through results. Defaults to 1. A positive value selects exactly that page, not a starting offset; see SPEC section 8. */
+  page?: number;
+}
+
+/**
+ * Request parameters for create.
+ */
+export interface CreateSubtaskRequest {
+  /** Title */
+  title: string;
+  /** Due date (YYYY-MM-DD) */
+  dueOn?: string;
+  /** Person IDs to assign to */
+  assigneeIds?: number[];
+}
+
+/**
+ * Request parameters for update.
+ */
+export interface UpdateSubtaskRequest {
+  /** Title */
+  title?: string;
+  /** Due date (YYYY-MM-DD) */
+  dueOn?: string;
+  /** Person IDs to assign to */
+  assigneeIds?: number[];
+}
+
+/**
+ * Request parameters for reposition.
+ */
+export interface RepositionSubtaskRequest {
+  /** The 1-based position to move it to */
+  position: number;
+}
+
+
+// =============================================================================
+// Service
+// =============================================================================
+
+/**
+ * Service for Subtasks operations.
+ */
+export class SubtasksService extends BaseService {
+
+  /**
+   * List a recording's subtasks, in position order
+   * @param recordingId - The recording ID
+   * @param options - Optional query parameters
+   * @returns Every Subtask across all pages, with .meta.totalCount
+   *
+   * @example
+   * ```ts
+   * const result = await client.subtasks.list(123);
+   *
+   * // With options
+   * const filtered = await client.subtasks.list(123, { page: 1 });
+   * ```
+   */
+  async list(recordingId: number, options?: ListSubtaskOptions): Promise<ListResult<Subtask>> {
+    return this.requestPaginated(
+      {
+        service: "Subtasks",
+        operation: "ListSubtasks",
+        resourceType: "subtask",
+        isMutation: false,
+        resourceId: recordingId,
+      },
+      () =>
+        this.client.GET("/recordings/{recordingId}/subtasks.json", {
+          params: {
+            path: { recordingId },
+            query: { page: options?.page },
+          },
+        })
+      , options
+    );
+  }
+
+  /**
+   * Create a subtask under a to-do or a card
+   * @param recordingId - The recording ID
+   * @param req - Subtask creation parameters
+   * @returns The Subtask
+   * @throws {BasecampError} If required fields are missing or invalid
+   *
+   * @example
+   * ```ts
+   * const result = await client.subtasks.create(123, { title: "example" });
+   * ```
+   */
+  async create(recordingId: number, req: CreateSubtaskRequest): Promise<Subtask> {
+    if (!req.title) {
+      throw Errors.validation("Title is required");
+    }
+    if (req.dueOn && !/^\d{4}-\d{2}-\d{2}$/.test(req.dueOn)) {
+      throw Errors.validation("Due on must be in YYYY-MM-DD format");
+    }
+    const response = await this.request(
+      {
+        service: "Subtasks",
+        operation: "CreateSubtask",
+        resourceType: "subtask",
+        isMutation: true,
+        resourceId: recordingId,
+      },
+      () =>
+        this.client.POST("/recordings/{recordingId}/subtasks.json", {
+          params: {
+            path: { recordingId },
+          },
+          body: {
+            title: req.title,
+            due_on: req.dueOn,
+            assignee_ids: req.assigneeIds,
+          },
+        })
+    );
+    return response;
+  }
+
+  /**
+   * Get a subtask by ID
+   * @param subtaskId - The subtask ID
+   * @returns The Subtask
+   * @throws {BasecampError} If the resource is not found
+   *
+   * @example
+   * ```ts
+   * const result = await client.subtasks.get(123);
+   * ```
+   */
+  async get(subtaskId: number): Promise<Subtask> {
+    const response = await this.request(
+      {
+        service: "Subtasks",
+        operation: "GetSubtask",
+        resourceType: "subtask",
+        isMutation: false,
+        resourceId: subtaskId,
+      },
+      () =>
+        this.client.GET("/subtasks/{subtaskId}", {
+          params: {
+            path: { subtaskId },
+          },
+        })
+    );
+    return response;
+  }
+
+  /**
+   * Update a subtask
+   * @param subtaskId - The subtask ID
+   * @param req - Subtask update parameters
+   * @returns The Subtask
+   * @throws {BasecampError} If the resource is not found or fields are invalid
+   *
+   * @example
+   * ```ts
+   * const result = await client.subtasks.update(123, { });
+   * ```
+   */
+  async update(subtaskId: number, req: UpdateSubtaskRequest): Promise<Subtask> {
+    if (req.dueOn && !/^\d{4}-\d{2}-\d{2}$/.test(req.dueOn)) {
+      throw Errors.validation("Due on must be in YYYY-MM-DD format");
+    }
+    const response = await this.request(
+      {
+        service: "Subtasks",
+        operation: "UpdateSubtask",
+        resourceType: "subtask",
+        isMutation: true,
+        resourceId: subtaskId,
+      },
+      () =>
+        this.client.PUT("/subtasks/{subtaskId}", {
+          params: {
+            path: { subtaskId },
+          },
+          body: {
+            title: req.title,
+            due_on: req.dueOn,
+            assignee_ids: req.assigneeIds,
+          },
+        })
+    );
+    return response;
+  }
+
+  /**
+   * Delete a subtask
+   * @param subtaskId - The subtask ID
+   * @returns void
+   * @throws {BasecampError} If the request fails
+   *
+   * @example
+   * ```ts
+   * await client.subtasks.delete(123);
+   * ```
+   */
+  async delete(subtaskId: number): Promise<void> {
+    await this.request(
+      {
+        service: "Subtasks",
+        operation: "DeleteSubtask",
+        resourceType: "subtask",
+        isMutation: true,
+        resourceId: subtaskId,
+      },
+      () =>
+        this.client.DELETE("/subtasks/{subtaskId}", {
+          params: {
+            path: { subtaskId },
+          },
+        })
+    );
+  }
+
+  /**
+   * Mark a subtask as completed
+   * @param subtaskId - The subtask ID
+   * @returns void
+   * @throws {BasecampError} If the request fails
+   *
+   * @example
+   * ```ts
+   * await client.subtasks.complete(123);
+   * ```
+   */
+  async complete(subtaskId: number): Promise<void> {
+    await this.request(
+      {
+        service: "Subtasks",
+        operation: "CompleteSubtask",
+        resourceType: "subtask",
+        isMutation: true,
+        resourceId: subtaskId,
+      },
+      () =>
+        this.client.POST("/subtasks/{subtaskId}/completion.json", {
+          params: {
+            path: { subtaskId },
+          },
+        })
+    );
+  }
+
+  /**
+   * Mark a subtask as not completed
+   * @param subtaskId - The subtask ID
+   * @returns void
+   * @throws {BasecampError} If the request fails
+   *
+   * @example
+   * ```ts
+   * await client.subtasks.uncomplete(123);
+   * ```
+   */
+  async uncomplete(subtaskId: number): Promise<void> {
+    await this.request(
+      {
+        service: "Subtasks",
+        operation: "UncompleteSubtask",
+        resourceType: "subtask",
+        isMutation: true,
+        resourceId: subtaskId,
+      },
+      () =>
+        this.client.DELETE("/subtasks/{subtaskId}/completion.json", {
+          params: {
+            path: { subtaskId },
+          },
+        })
+    );
+  }
+
+  /**
+   * Move a subtask to a new position among its siblings
+   * @param subtaskId - The subtask ID
+   * @param req - Subtask request parameters
+   * @returns void
+   * @throws {BasecampError} If the request fails
+   *
+   * @example
+   * ```ts
+   * await client.subtasks.reposition(123, { position: 1 });
+   * ```
+   */
+  async reposition(subtaskId: number, req: RepositionSubtaskRequest): Promise<void> {
+    await this.request(
+      {
+        service: "Subtasks",
+        operation: "RepositionSubtask",
+        resourceType: "subtask",
+        isMutation: true,
+        resourceId: subtaskId,
+      },
+      () =>
+        this.client.PUT("/subtasks/{subtaskId}/position.json", {
+          params: {
+            path: { subtaskId },
+          },
+          body: {
+            position: req.position,
+          },
+        })
+    );
+  }
+}

package/src/generated/services/templates.ts

@@ -14,21 +14,65 @@ import { Errors } from "../../errors.js";
 // Types
 // =============================================================================
 
+/** CardTable entity from the Basecamp API. */
+export type CardTable = components["schemas"]["CardTable"];
+/** Todolist entity from the Basecamp API. */
+export type Todolist = components["schemas"]["Todolist"];
 /** Template entity from the Basecamp API. */
 export type Template = components["schemas"]["Template"];
 
+/**
+ * Request parameters for createTemplatification.
+ */
+export interface CreateTemplatificationTemplateRequest {
+  /** What to call the template. Defaults to the source recording's own title. */
+  templateName?: string;
+  /** Carry the comments across. */
+  copyComments?: boolean;
+  /** Carry assignees and the people involved across, adding them to the library
+if they are not already there. */
+  copyAssignments?: boolean;
+  /** Gather the cards into Triage. Card tables only, and ignored otherwise. */
+  moveCardsToTriage?: boolean;
+}
+
+/**
+ * Request parameters for createLibraryCardTable.
+ */
+export interface CreateLibraryCardTableTemplateRequest {
+  /** The template's name. Write-only: the response carries it as `title`. */
+  name: string;
+}
+
 /**
  * Request parameters for createLibraryCopy.
  */
 export interface CreateLibraryCopyTemplateRequest {
-  /** Template recording id */
+  /** The to-do list or card table in the library to copy. */
   templateRecordingId: number;
-  /** Destination parent id */
-  destinationParentId: number;
+  /** The destination project. Basecamp resolves the container from the
+template's kind, so a caller naming a project needs to know nothing about
+docks or to-do sets. Supply this or destination_parent_id; if both are
+sent, destination_parent_id wins. */
+  destinationProjectId?: number;
+  /** The container to copy into, for a caller that already holds one: the
+project's to-do set for a to-do list template, or its dock for a card
+table. A caller who may not edit it gets 404, not 403. */
+  destinationParentId?: number;
   /** Confirm granting destination-project access to people referenced by the template. */
   addingPeopleConfirmed?: boolean;
 }
 
+/**
+ * Request parameters for createLibraryTodolist.
+ */
+export interface CreateLibraryTodolistTemplateRequest {
+  /** What to call the template. */
+  name: string;
+  /** Rich text describing the template. */
+  description?: string;
+}
+
 /**
  * Options for list.
  */
@@ -78,39 +122,143 @@ export interface CreateProjectTemplateRequest {
 export class TemplatesService extends BaseService {
 
   /**
-   * Get the account's to-do list template library
-   * @returns The template_library
+   * Templatify a to-do list or card table
+   * @param bucketId - The bucket ID
+   * @param recordingId - The to-do list or card table to templatify. Anything else is a 403.
+   * @param req - Templatification creation parameters
+   * @returns The templatification
+   * @throws {BasecampError} If required fields are missing or invalid
+   *
+   * @example
+   * ```ts
+   * const result = await client.templates.createTemplatification(123, 123, { });
+   * ```
+   */
+  async createTemplatification(bucketId: number, recordingId: number, req: CreateTemplatificationTemplateRequest): Promise<components["schemas"]["CreateTemplatificationResponseContent"]> {
+    const response = await this.request(
+      {
+        service: "Templates",
+        operation: "CreateTemplatification",
+        resourceType: "templatification",
+        isMutation: true,
+        projectId: bucketId,
+        resourceId: recordingId,
+      },
+      () =>
+        this.client.POST("/buckets/{bucketId}/recordings/{recordingId}/templatifications.json", {
+          params: {
+            path: { bucketId, recordingId },
+          },
+          body: {
+            template_name: req.templateName,
+            copy_comments: req.copyComments,
+            copy_assignments: req.copyAssignments,
+            move_cards_to_triage: req.moveCardsToTriage,
+          },
+        })
+    );
+    return response;
+  }
+
+  /**
+   * Get a templatification
+   * @param bucketId - The bucket ID
+   * @param recordingId - The recording ID
+   * @param templatificationId - The templatification ID
+   * @returns The templatification
    * @throws {BasecampError} If the resource is not found
    *
    * @example
    * ```ts
-   * const result = await client.templates.getLibrary();
+   * const result = await client.templates.getTemplatification(123, 123, 123);
    * ```
    */
-  async getLibrary(): Promise<components["schemas"]["GetTemplateLibraryResponseContent"]> {
+  async getTemplatification(bucketId: number, recordingId: number, templatificationId: number): Promise<components["schemas"]["GetTemplatificationResponseContent"]> {
     const response = await this.request(
       {
         service: "Templates",
-        operation: "GetTemplateLibrary",
-        resourceType: "template_library",
+        operation: "GetTemplatification",
+        resourceType: "templatification",
         isMutation: false,
+        projectId: bucketId,
+        resourceId: templatificationId,
+      },
+      () =>
+        this.client.GET("/buckets/{bucketId}/recordings/{recordingId}/templatifications/{templatificationId}", {
+          params: {
+            path: { bucketId, recordingId, templatificationId },
+          },
+        })
+    );
+    return response;
+  }
+
+  /**
+   * Get the account's card table templates
+   * @returns The template_library_card_table
+   * @throws {BasecampError} If the resource is not found
+   *
+   * @example
+   * ```ts
+   * const result = await client.templates.getLibraryCardTables();
+   * ```
+   */
+  async getLibraryCardTables(): Promise<components["schemas"]["GetTemplateLibraryCardTablesResponseContent"]> {
+    const response = await this.request(
+      {
+        service: "Templates",
+        operation: "GetTemplateLibraryCardTables",
+        resourceType: "template_library_card_table",
+        isMutation: false,
+      },
+      () =>
+        this.client.GET("/template_library/card_tables.json", {
+        })
+    );
+    return response;
+  }
+
+  /**
+   * Create a card table template with the default columns
+   * @param req - Template_library_card_table creation parameters
+   * @returns The CardTable
+   * @throws {BasecampError} If required fields are missing or invalid
+   *
+   * @example
+   * ```ts
+   * const result = await client.templates.createLibraryCardTable({ name: "My example" });
+   * ```
+   */
+  async createLibraryCardTable(req: CreateLibraryCardTableTemplateRequest): Promise<CardTable> {
+    if (!req.name) {
+      throw Errors.validation("Name is required");
+    }
+    const response = await this.request(
+      {
+        service: "Templates",
+        operation: "CreateTemplateLibraryCardTable",
+        resourceType: "template_library_card_table",
+        isMutation: true,
       },
       () =>
-        this.client.GET("/template_library.json", {
+        this.client.POST("/template_library/card_tables.json", {
+          body: {
+            name: req.name,
+          },
         })
     );
     return response;
   }
 
   /**
-   * Start copying a to-do list template into a project
+   * Start copying a to-do list or card table template into a project
    * @param req - Template_library_copy creation parameters
    * @returns The template_library_copy
    * @throws {BasecampError} If required fields are missing or invalid
    *
    * @example
    * ```ts
-   * const result = await client.templates.createLibraryCopy({ templateRecordingId: 1, destinationParentId: 1 });
+   * const result = await client.templates.createLibraryCopy({ templateRecordingId: 1 });
    * ```
    */
   async createLibraryCopy(req: CreateLibraryCopyTemplateRequest): Promise<components["schemas"]["CreateTemplateLibraryCopyResponseContent"]> {
@@ -125,6 +273,7 @@ export class TemplatesService extends BaseService {
         this.client.POST("/template_library/copies.json", {
           body: {
             template_recording_id: req.templateRecordingId,
+            destination_project_id: req.destinationProjectId,
             destination_parent_id: req.destinationParentId,
             adding_people_confirmed: req.addingPeopleConfirmed,
           },
@@ -163,10 +312,68 @@ export class TemplatesService extends BaseService {
     return response;
   }
 
+  /**
+   * Get the account's to-do list templates
+   * @returns The template_library_todolist
+   * @throws {BasecampError} If the resource is not found
+   *
+   * @example
+   * ```ts
+   * const result = await client.templates.getLibraryTodolists();
+   * ```
+   */
+  async getLibraryTodolists(): Promise<components["schemas"]["GetTemplateLibraryTodolistsResponseContent"]> {
+    const response = await this.request(
+      {
+        service: "Templates",
+        operation: "GetTemplateLibraryTodolists",
+        resourceType: "template_library_todolist",
+        isMutation: false,
+      },
+      () =>
+        this.client.GET("/template_library/todolists.json", {
+        })
+    );
+    return response;
+  }
+
+  /**
+   * Create an empty to-do list template
+   * @param req - Template_library_todolist creation parameters
+   * @returns The Todolist
+   * @throws {BasecampError} If required fields are missing or invalid
+   *
+   * @example
+   * ```ts
+   * const result = await client.templates.createLibraryTodolist({ name: "My example" });
+   * ```
+   */
+  async createLibraryTodolist(req: CreateLibraryTodolistTemplateRequest): Promise<Todolist> {
+    if (!req.name) {
+      throw Errors.validation("Name is required");
+    }
+    const response = await this.request(
+      {
+        service: "Templates",
+        operation: "CreateTemplateLibraryTodolist",
+        resourceType: "template_library_todolist",
+        isMutation: true,
+      },
+      () =>
+        this.client.POST("/template_library/todolists.json", {
+          body: {
+            name: req.name,
+            description: req.description,
+          },
+        })
+    );
+    return response;
+  }
+
   /**
    * List all templates visible to the current user
    * @param options - Optional query parameters
-   * @returns All Template across all pages, with .meta.totalCount
+   * @returns Every Template across all pages, with .meta.totalCount
    *
    * @example
    * ```ts

package/src/generated/services/timeline.ts

@@ -38,7 +38,7 @@ export class TimelineService extends BaseService {
    * Get project timeline
    * @param projectId - The project ID
    * @param options - Optional query parameters
-   * @returns All TimelineEvent across all pages, with .meta.totalCount
+   * @returns Every TimelineEvent across all pages, with .meta.totalCount
    *
    * @example
    * ```ts

package/src/generated/services/timesheets.ts

@@ -99,7 +99,7 @@ export class TimesheetsService extends BaseService {
    * Get timesheet for a specific project
    * @param projectId - The project ID
    * @param options - Optional query parameters
-   * @returns All TimesheetEntry across all pages, with .meta.totalCount
+   * @returns Every TimesheetEntry across all pages, with .meta.totalCount
    *
    * @example
    * ```ts
@@ -130,7 +130,7 @@ export class TimesheetsService extends BaseService {
    * Get timesheet for a specific recording
    * @param recordingId - The recording ID
    * @param options - Optional query parameters
-   * @returns All TimesheetEntry across all pages, with .meta.totalCount
+   * @returns Every TimesheetEntry across all pages, with .meta.totalCount
    *
    * @example
    * ```ts
@@ -296,7 +296,7 @@ export class TimesheetsService extends BaseService {
   }
 
   /**
-   * Permanently delete a timesheet entry; answers 403 when the caller may not archive or trash it.
+   * Permanently delete a timesheet entry, which never appears in the trash and cannot be restored; this is the only way to remove one, since bc3 answers 403 to TrashRecording and ArchiveRecording for every timesheet entry, and it answers 403 when the caller may not remove the entry.
    * @param entryId - The entry ID
    * @returns void
    * @throws {BasecampError} If the request fails

package/src/generated/services/todolist-groups.ts

@@ -88,7 +88,7 @@ export class TodolistGroupsService extends BaseService {
    * List groups in a todolist
    * @param todolistId - The todolist ID
    * @param options - Optional query parameters
-   * @returns All Todolist across all pages, with .meta.totalCount
+   * @returns Every Todolist across all pages, with .meta.totalCount
    *
    * @example
    * ```ts

package/src/generated/services/todolists.ts

@@ -172,7 +172,7 @@ export class TodolistsService extends BaseService {
    * List todolists in a todoset
    * @param todosetId - The todoset ID
    * @param options - Optional query parameters
-   * @returns All Todolist across all pages, with .meta.totalCount
+   * @returns Every Todolist across all pages, with .meta.totalCount
    *
    * @example
    * ```ts

package/src/generated/services/todos.ts

@@ -164,7 +164,7 @@ export class TodosService extends BaseService {
    * List todos in a todolist
    * @param todolistId - The todolist ID
    * @param options - Optional query parameters
-   * @returns All Todo across all pages, with .meta.totalCount
+   * @returns Every Todo across all pages, with .meta.totalCount
    *
    * @example
    * ```ts