@37signals/basecamp 0.11.0 → 0.13.0

package/src/generated/services/reports.ts

@@ -22,16 +22,8 @@ export type Person = components["schemas"]["Person"];
  * Options for progress.
  */
 export interface ProgressReportOptions extends PaginationOptions {
-}
-
-/**
- * Options for upcoming.
- */
-export interface UpcomingReportOptions {
-  /** Window starts on */
-  windowStartsOn?: string;
-  /** Window ends on */
-  windowEndsOn?: string;
+  /** 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;
 }
 
 /**
@@ -46,6 +38,8 @@ export interface AssignedReportOptions {
  * Options for personProgress.
  */
 export interface PersonProgressReportOptions 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;
 }
 
 
@@ -78,6 +72,9 @@ export class ReportsService extends BaseService {
       },
       () =>
         this.client.GET("/reports/progress.json", {
+          params: {
+            query: { page: options?.page },
+          },
         })
       , options
     );
@@ -85,15 +82,16 @@ export class ReportsService extends BaseService {
 
   /**
    * Get upcoming schedule entries and assignable items within a date window.
-   * @param options - Optional query parameters
+   * @param windowStartsOn - Inclusive first day of the window, `YYYY-MM-DD`. Required — BC3 answers 400 without it.
+   * @param windowEndsOn - Inclusive last day of the window, `YYYY-MM-DD`. Required — BC3 answers 400 without it.
    * @returns The upcoming_schedule
    *
    * @example
    * ```ts
-   * const result = await client.reports.upcoming();
+   * const result = await client.reports.upcoming("window_starts_on", "window_ends_on");
    * ```
    */
-  async upcoming(options?: UpcomingReportOptions): Promise<components["schemas"]["GetUpcomingScheduleResponseContent"]> {
+  async upcoming(windowStartsOn: string, windowEndsOn: string): Promise<components["schemas"]["GetUpcomingScheduleResponseContent"]> {
     const response = await this.request(
       {
         service: "Reports",
@@ -104,7 +102,7 @@ export class ReportsService extends BaseService {
       () =>
         this.client.GET("/reports/schedules/upcoming.json", {
           params: {
-            query: { "window_starts_on": options?.windowStartsOn, "window_ends_on": options?.windowEndsOn },
+            query: { "window_starts_on": windowStartsOn, "window_ends_on": windowEndsOn },
           },
         })
     );
@@ -190,6 +188,7 @@ export class ReportsService extends BaseService {
         this.client.GET("/reports/users/progress/{personId}.json", {
           params: {
             path: { personId },
+            query: { page: options?.page },
           },
         })
       , "events", options

package/src/generated/services/schedules.ts

@@ -20,15 +20,17 @@ export type ScheduleEntry = components["schemas"]["ScheduleEntry"];
 export type Schedule = components["schemas"]["Schedule"];
 
 /**
- * Request parameters for updateEntry.
+ * Request parameters for replaceEntry.
  */
-export interface UpdateEntryScheduleRequest {
+export interface ReplaceEntryScheduleRequest {
   /** Summary text */
   summary?: string;
-  /** Starts at (RFC3339 (e.g., 2024-12-15T09:00:00Z)) */
-  startsAt?: string;
-  /** Ends at (RFC3339 (e.g., 2024-12-15T09:00:00Z)) */
-  endsAt?: string;
+  /** The entry's start, as a bare date ("2026-06-01") for an all-day entry or a
+full timestamp otherwise. Same rule as CreateScheduleEntry: send it
+verbatim, never parsed and re-rendered. */
+  startsAt: string;
+  /** The entry's end. See starts_at for the date-vs-timestamp rule. */
+  endsAt: string;
   /** Rich text description (HTML) */
   description?: string;
   /** Replaces the entry's participants.
@@ -41,10 +43,36 @@ including the shape in BC3's own "Update a schedule entry" doc example —
 silently removed every participant and notified each one. The controller
 now guards on the request actually addressing participants. */
   participantIds?: number[];
-  /** All day */
+  /** Whether the entry occupies whole days rather than a time range.
+
+Not carved out, and the carve-out list is what makes that dangerous to
+forget: `schedule_entries.all_day` is NOT NULL with a `false` default, so
+omitting this member on a replace resets it — silently converting an
+all-day entry into a midnight-to-midnight timed one. The SDK's merge-safe
+update and edit resend it from the read-back for exactly this reason.
+
+Sending an explicit null is worse than omitting it: the column rejects
+NULL, so BC3 raises rather than falling back to the default. The same is
+true of highlighted. */
   allDay?: boolean;
   /** Whether to send notifications to relevant people */
   notify?: boolean;
+  /** The entry's join link — a video-call URL or similar, up to 2500
+characters, validated as a URL when present.
+
+Omitting this member preserves the current join link; sending an empty
+string clears it. Read it back as `join_url`, never as `url`: the entry's
+`url` is its own Basecamp API URL, written by a partial that renders
+before this one, so BC3 emits the join link under a non-colliding key.
+Echoing the response's `url` into this member would write the API URL into
+the join link. */
+  url?: string;
+  /** Whether the entry is highlighted on the schedule.
+
+Omitting this member preserves the current highlight; sending false
+removes it. Preserved on omission because until basecamp/bc3#12502 the
+field was writable but never returned, so no caller could resend it. */
+  highlighted?: boolean;
 }
 
 /**
@@ -61,6 +89,8 @@ export interface UpdateSettingsScheduleRequest {
 export interface ListEntriesScheduleOptions extends PaginationOptions {
   /** Filter by status */
   status?: "active" | "archived" | "trashed";
+  /** 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;
 }
 
 /**
@@ -69,9 +99,21 @@ export interface ListEntriesScheduleOptions extends PaginationOptions {
 export interface CreateEntryScheduleRequest {
   /** Summary text */
   summary: string;
-  /** Starts at (RFC3339 (e.g., 2024-12-15T09:00:00Z)) */
+  /** The entry's start, as a bare date ("2026-06-01") for an all-day entry or a
+full timestamp ("2026-06-01T09:00:00Z") otherwise — the same two forms the
+response renders, and the same two ReplaceScheduleEntry accepts.
+
+Create and replace share one permit list:
+`Schedules::Entries::BaseController#base_schedule_entry_params` is what
+both `new_schedule_entry_params` and `update_schedule_entry_params` call,
+and Schedule::Entry does no format-specific parsing of either bound, so
+whatever one operation takes the other takes too.
+
+Treat the value as opaque and send it verbatim. Parsing it into a
+date-time type and re-rendering rewrites an all-day entry's bounds into
+midnight timestamps, which is why every SDK models it as a string. */
   startsAt: string;
-  /** Ends at (RFC3339 (e.g., 2024-12-15T09:00:00Z)) */
+  /** The entry's end. See starts_at for the date-vs-timestamp rule. */
   endsAt: string;
   /** Rich text description (HTML) */
   description?: string;
@@ -81,6 +123,43 @@ export interface CreateEntryScheduleRequest {
   allDay?: boolean;
   /** Whether to send notifications to relevant people */
   notify?: boolean;
+  /** The entry's join link — a video-call URL or similar, up to 2500
+characters, validated as a URL when present. A scheme-less value is
+normalized to `https://`.
+
+Spell it `url` on the way in and read it back as `join_url`: the response
+key `url` is the entry's own Basecamp API URL, written by a partial that
+renders before this field, so BC3 emits the join link under a
+non-colliding name. Sending `join_url` instead is silently dropped by
+strong parameters — the create succeeds with no join link.
+
+Accepted on create since long before it was documented:
+`Schedules::Entries::BaseController#base_schedule_entry_params` permits it
+and `new_schedule_entry_params` passes it through unchanged for API
+requests. Modeling it only on ReplaceScheduleEntry forced callers into a
+three-request read-modify-write for a field the create already took — and
+create is the notifying write, so participants learned about a video call
+before its link existed. */
+  url?: string;
+  /** Whether the entry is highlighted on the schedule. Defaults to false.
+
+Do not send an explicit null: `schedule_entries.highlighted` is NOT NULL,
+so BC3 raises rather than falling back to the default. Omit it instead —
+every SDK's request compactor already drops unset members. */
+  highlighted?: boolean;
+  /** Publication state at creation — `active|drafted`, defaulting to `active`
+for an API create.
+
+A top-level parameter, not part of the entry's attributes: `status` is a
+Recording column, so `wrap_parameters` leaves it outside the
+`schedule_entry` envelope and `Recording::StatusParam#status_param` reads
+it directly. On create it accepts `drafted`, `active`, `archived` or
+`trashed` and raises `ActionController::BadRequest` — a 400, not a 422 —
+for anything else; the two documented values are the two worth sending.
+
+Unlike messages and documents, schedule-entry drafts are not listed by
+GetMyDrafts. */
+  status?: string;
   /** Subscriptions */
   subscriptions?: number[];
   /** Visible to clients */
@@ -128,22 +207,28 @@ export class SchedulesService extends BaseService {
   }
 
   /**
-   * Update an existing schedule entry
+   * Replace a schedule entry with a new complete representation.
    * @param entryId - The entry ID
-   * @param req - Schedule_entry update parameters
+   * @param req - Schedule_entry request parameters
    * @returns The ScheduleEntry
-   * @throws {BasecampError} If the resource is not found or fields are invalid
+   * @throws {BasecampError} If the request fails
    *
    * @example
    * ```ts
-   * const result = await client.schedules.updateEntry(123, { });
+   * const result = await client.schedules.replaceEntry(123, { startsAt: "example", endsAt: "example" });
    * ```
    */
-  async updateEntry(entryId: number, req: UpdateEntryScheduleRequest): Promise<ScheduleEntry> {
+  async replaceEntry(entryId: number, req: ReplaceEntryScheduleRequest): Promise<ScheduleEntry> {
+    if (!req.startsAt) {
+      throw Errors.validation("Starts at is required");
+    }
+    if (!req.endsAt) {
+      throw Errors.validation("Ends at is required");
+    }
     const response = await this.request(
       {
         service: "Schedules",
-        operation: "UpdateScheduleEntry",
+        operation: "ReplaceScheduleEntry",
         resourceType: "schedule_entry",
         isMutation: true,
         resourceId: entryId,
@@ -161,6 +246,8 @@ export class SchedulesService extends BaseService {
             participant_ids: req.participantIds,
             all_day: req.allDay,
             notify: req.notify,
+            url: req.url,
+            highlighted: req.highlighted,
           },
         })
     );
@@ -289,7 +376,7 @@ export class SchedulesService extends BaseService {
         this.client.GET("/schedules/{scheduleId}/entries.json", {
           params: {
             path: { scheduleId },
-            query: { status: options?.status },
+            query: { status: options?.status, page: options?.page },
           },
         })
       , options
@@ -305,7 +392,7 @@ export class SchedulesService extends BaseService {
    *
    * @example
    * ```ts
-   * const result = await client.schedules.createEntry(123, { summary: "example", startsAt: "2025-06-01T09:00:00Z", endsAt: "2025-06-01T09:00:00Z" });
+   * const result = await client.schedules.createEntry(123, { summary: "example", startsAt: "example", endsAt: "example" });
    * ```
    */
   async createEntry(scheduleId: number, req: CreateEntryScheduleRequest): Promise<ScheduleEntry> {
@@ -339,6 +426,9 @@ export class SchedulesService extends BaseService {
             participant_ids: req.participantIds,
             all_day: req.allDay,
             notify: req.notify,
+            url: req.url,
+            highlighted: req.highlighted,
+            status: req.status,
             subscriptions: req.subscriptions,
             visible_to_clients: req.visibleToClients,
           },

package/src/generated/services/search.ts

@@ -49,6 +49,8 @@ endpoint's `file_search_types`. */
    * @deprecated prefer creator_ids[].
    */
   creatorId?: number;
+  /** 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;
 }
 
 
@@ -83,7 +85,7 @@ export class SearchService extends BaseService {
       () =>
         this.client.GET("/search.json", {
           params: {
-            query: { q: q, "type_names[]": options?.typeNames, "bucket_ids[]": options?.bucketIds, "creator_ids[]": options?.creatorIds, "file_type": options?.fileType, "exclude_chat": options?.excludeChat, since: options?.since, sort: options?.sort, type: options?.type, "bucket_id": options?.bucketId, "creator_id": options?.creatorId },
+            query: { q: q, "type_names[]": options?.typeNames, "bucket_ids[]": options?.bucketIds, "creator_ids[]": options?.creatorIds, "file_type": options?.fileType, "exclude_chat": options?.excludeChat, since: options?.since, sort: options?.sort, type: options?.type, "bucket_id": options?.bucketId, "creator_id": options?.creatorId, page: options?.page },
           },
         })
       , options

package/src/generated/services/templates.ts

@@ -23,6 +23,8 @@ export type Template = components["schemas"]["Template"];
 export interface ListTemplateOptions extends PaginationOptions {
   /** Filter by status */
   status?: "active" | "archived" | "trashed";
+  /** 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;
 }
 
 /**
@@ -87,7 +89,7 @@ export class TemplatesService extends BaseService {
       () =>
         this.client.GET("/templates.json", {
           params: {
-            query: { status: options?.status },
+            query: { status: options?.status, page: options?.page },
           },
         })
       , options

package/src/generated/services/timeline.ts

@@ -20,6 +20,8 @@ export type TimelineEvent = components["schemas"]["TimelineEvent"];
  * Options for projectTimeline.
  */
 export interface ProjectTimelineTimelineOptions 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;
 }
 
 
@@ -56,6 +58,7 @@ export class TimelineService extends BaseService {
         this.client.GET("/projects/{projectId}/timeline.json", {
           params: {
             path: { projectId },
+            query: { page: options?.page },
           },
         })
       , options

package/src/generated/services/timesheets.ts

@@ -27,6 +27,8 @@ export interface ForProjectTimesheetOptions extends PaginationOptions {
   to?: string;
   /** Person id */
   personId?: number;
+  /** 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;
 }
 
 /**
@@ -39,6 +41,8 @@ export interface ForRecordingTimesheetOptions extends PaginationOptions {
   to?: string;
   /** Person id */
   personId?: number;
+  /** 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;
 }
 
 /**
@@ -115,7 +119,7 @@ export class TimesheetsService extends BaseService {
         this.client.GET("/projects/{projectId}/timesheet.json", {
           params: {
             path: { projectId },
-            query: { from: options?.from, to: options?.to, "person_id": options?.personId },
+            query: { from: options?.from, to: options?.to, "person_id": options?.personId, page: options?.page },
           },
         })
       , options
@@ -146,7 +150,7 @@ export class TimesheetsService extends BaseService {
         this.client.GET("/recordings/{recordingId}/timesheet.json", {
           params: {
             path: { recordingId },
-            query: { from: options?.from, to: options?.to, "person_id": options?.personId },
+            query: { from: options?.from, to: options?.to, "person_id": options?.personId, page: options?.page },
           },
         })
       , options
@@ -290,4 +294,33 @@ export class TimesheetsService extends BaseService {
     );
     return response;
   }
+
+  /**
+   * Permanently delete a timesheet entry; answers 403 when the caller may not archive or trash it.
+   * @param entryId - The entry ID
+   * @returns void
+   * @throws {BasecampError} If the request fails
+   *
+   * @example
+   * ```ts
+   * await client.timesheets.destroy(123);
+   * ```
+   */
+  async destroy(entryId: number): Promise<void> {
+    await this.request(
+      {
+        service: "Timesheets",
+        operation: "DestroyTimesheetEntry",
+        resourceType: "timesheet_entry",
+        isMutation: true,
+        resourceId: entryId,
+      },
+      () =>
+        this.client.DELETE("/timesheet_entries/{entryId}", {
+          params: {
+            path: { entryId },
+          },
+        })
+    );
+  }
 }

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

@@ -14,8 +14,8 @@ import { Errors } from "../../errors.js";
 // Types
 // =============================================================================
 
-/** TodolistGroup entity from the Basecamp API. */
-export type TodolistGroup = components["schemas"]["TodolistGroup"];
+/** Todolist entity from the Basecamp API. */
+export type Todolist = components["schemas"]["Todolist"];
 
 /**
  * Request parameters for reposition.
@@ -29,6 +29,8 @@ export interface RepositionTodolistGroupRequest {
  * Options for list.
  */
 export interface ListTodolistGroupOptions 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;
 }
 
 /**
@@ -71,7 +73,7 @@ export class TodolistGroupsService extends BaseService {
         resourceId: groupId,
       },
       () =>
-        this.client.PUT("/todolists/{groupId}/position.json", {
+        this.client.PUT("/todolists/groups/{groupId}/position.json", {
           params: {
             path: { groupId },
           },
@@ -86,14 +88,17 @@ export class TodolistGroupsService extends BaseService {
    * List groups in a todolist
    * @param todolistId - The todolist ID
    * @param options - Optional query parameters
-   * @returns All TodolistGroup across all pages, with .meta.totalCount
+   * @returns All Todolist across all pages, with .meta.totalCount
    *
    * @example
    * ```ts
    * const result = await client.todolistGroups.list(123);
+   *
+   * // With options
+   * const filtered = await client.todolistGroups.list(123, { page: 1 });
    * ```
    */
-  async list(todolistId: number, options?: ListTodolistGroupOptions): Promise<ListResult<TodolistGroup>> {
+  async list(todolistId: number, options?: ListTodolistGroupOptions): Promise<ListResult<Todolist>> {
     return this.requestPaginated(
       {
         service: "TodolistGroups",
@@ -106,6 +111,7 @@ export class TodolistGroupsService extends BaseService {
         this.client.GET("/todolists/{todolistId}/groups.json", {
           params: {
             path: { todolistId },
+            query: { page: options?.page },
           },
         })
       , options
@@ -116,7 +122,7 @@ export class TodolistGroupsService extends BaseService {
    * Create a new group in a todolist
    * @param todolistId - The todolist ID
    * @param req - Todolist_group creation parameters
-   * @returns The TodolistGroup
+   * @returns The Todolist
    * @throws {BasecampError} If required fields are missing or invalid
    *
    * @example
@@ -124,7 +130,7 @@ export class TodolistGroupsService extends BaseService {
    * const result = await client.todolistGroups.create(123, { name: "My example" });
    * ```
    */
-  async create(todolistId: number, req: CreateTodolistGroupRequest): Promise<TodolistGroup> {
+  async create(todolistId: number, req: CreateTodolistGroupRequest): Promise<Todolist> {
     if (!req.name) {
       throw Errors.validation("Name is required");
     }

package/src/generated/services/todolists.ts

@@ -18,12 +18,12 @@ import { Errors } from "../../errors.js";
 export type Todolist = components["schemas"]["Todolist"];
 
 /**
- * Request parameters for update.
+ * Request parameters for replace.
  */
-export interface UpdateTodolistRequest {
-  /** Name (required for both Todolist and TodolistGroup) */
-  name?: string;
-  /** Description (Todolist only, ignored for groups) */
+export interface ReplaceTodolistRequest {
+  /** Name (required for a to-do list and for a group alike) - presence-validated server-side, so omitting it is a 422, not a preserve */
+  name: string;
+  /** Description (rich text HTML) - writable for a todolist group as well as a todolist, and omitting it clears it either way */
   description?: string;
 }
 
@@ -41,6 +41,8 @@ export interface RepositionTodolistRequest {
 export interface ListTodolistOptions extends PaginationOptions {
   /** Filter by status */
   status?: "active" | "archived" | "trashed";
+  /** 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;
 }
 
 /**
@@ -68,7 +70,7 @@ export class TodolistsService extends BaseService {
   /**
    * Get a single todolist or todolist group by id
    * @param id - The id
-   * @returns The todolist_or_group
+   * @returns The Todolist
    * @throws {BasecampError} If the resource is not found
    *
    * @example
@@ -76,7 +78,7 @@ export class TodolistsService extends BaseService {
    * const result = await client.todolists.get(123);
    * ```
    */
-  async get(id: number): Promise<components["schemas"]["GetTodolistOrGroupResponseContent"]> {
+  async get(id: number): Promise<Todolist> {
     const response = await this.request(
       {
         service: "Todolists",
@@ -96,18 +98,21 @@ export class TodolistsService extends BaseService {
   }
 
   /**
-   * Update an existing todolist or todolist group
+   * Replace a todolist (or todolist group) with a new complete representation.
    * @param id - The id
-   * @param req - Todolist_or_group update parameters
-   * @returns The todolist_or_group
-   * @throws {BasecampError} If the resource is not found or fields are invalid
+   * @param req - Todolist_or_group request parameters
+   * @returns The Todolist
+   * @throws {BasecampError} If the request fails
    *
    * @example
    * ```ts
-   * const result = await client.todolists.update(123, { });
+   * const result = await client.todolists.replace(123, { name: "My example" });
    * ```
    */
-  async update(id: number, req: UpdateTodolistRequest): Promise<components["schemas"]["UpdateTodolistOrGroupResponseContent"]> {
+  async replace(id: number, req: ReplaceTodolistRequest): Promise<Todolist> {
+    if (!req.name) {
+      throw Errors.validation("Name is required");
+    }
     const response = await this.request(
       {
         service: "Todolists",
@@ -190,7 +195,7 @@ export class TodolistsService extends BaseService {
         this.client.GET("/todosets/{todosetId}/todolists.json", {
           params: {
             path: { todosetId },
-            query: { status: options?.status },
+            query: { status: options?.status, page: options?.page },
           },
         })
       , options