@37signals/basecamp 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Basecamp TypeScript SDK Client
+ *
+ * Creates a type-safe client for the Basecamp 3 API using openapi-fetch.
+ * Includes middleware for authentication, retry with exponential backoff,
+ * and ETag-based caching.
+ */
+import createClient from "openapi-fetch";
+import type { paths } from "./generated/schema.js";
+import type { BasecampHooks } from "./hooks.js";
+import { parseNextLink, resolveURL, isSameOrigin } from "./pagination-utils.js";
+import { type AuthStrategy } from "./auth-strategy.js";
+import { ProjectsService } from "./generated/services/projects.js";
+import { TodosService } from "./generated/services/todos.js";
+import { TodolistsService } from "./generated/services/todolists.js";
+import { TodosetsService } from "./generated/services/todosets.js";
+import { PeopleService } from "./generated/services/people.js";
+import { MessagesService } from "./generated/services/messages.js";
+import { CommentsService } from "./generated/services/comments.js";
+import { CampfiresService } from "./generated/services/campfires.js";
+import { CardTablesService } from "./generated/services/card-tables.js";
+import { CardsService } from "./generated/services/cards.js";
+import { CardColumnsService } from "./generated/services/card-columns.js";
+import { CardStepsService } from "./generated/services/card-steps.js";
+import { MessageBoardsService } from "./generated/services/message-boards.js";
+import { MessageTypesService } from "./generated/services/message-types.js";
+import { ForwardsService } from "./generated/services/forwards.js";
+import { CheckinsService } from "./generated/services/checkins.js";
+import { ClientApprovalsService } from "./generated/services/client-approvals.js";
+import { ClientCorrespondencesService } from "./generated/services/client-correspondences.js";
+import { ClientRepliesService } from "./generated/services/client-replies.js";
+import { WebhooksService } from "./generated/services/webhooks.js";
+import { SubscriptionsService } from "./generated/services/subscriptions.js";
+import { AttachmentsService } from "./generated/services/attachments.js";
+import { VaultsService } from "./generated/services/vaults.js";
+import { DocumentsService } from "./generated/services/documents.js";
+import { UploadsService } from "./generated/services/uploads.js";
+import { SchedulesService } from "./generated/services/schedules.js";
+import { EventsService } from "./generated/services/events.js";
+import { RecordingsService } from "./generated/services/recordings.js";
+import { SearchService } from "./generated/services/search.js";
+import { ReportsService } from "./generated/services/reports.js";
+import { TemplatesService } from "./generated/services/templates.js";
+import { LineupService } from "./generated/services/lineup.js";
+import { TodolistGroupsService } from "./generated/services/todolist-groups.js";
+import { ToolsService } from "./generated/services/tools.js";
+import { TimesheetsService } from "./generated/services/timesheets.js";
+import { TimelineService } from "./generated/services/timeline.js";
+import { ClientVisibilityService } from "./generated/services/client-visibility.js";
+import { BoostsService } from "./generated/services/boosts.js";
+import { AuthorizationService } from "./services/authorization.js";
+export type { paths };
+/**
+ * Raw client type from openapi-fetch.
+ * Use this when you need direct access to GET/POST/PUT/DELETE methods.
+ */
+export type RawClient = ReturnType<typeof createClient<paths>>;
+/**
+ * Enhanced Basecamp client with hooks support and service accessors.
+ * Wraps the raw openapi-fetch client with observability features.
+ */
+export interface BasecampClient extends RawClient {
+    /** The underlying raw client (for advanced use cases) */
+    readonly raw: RawClient;
+    /** Hooks for observability (if configured) */
+    readonly hooks?: BasecampHooks;
+    /** Projects service - list, get, create, update, and trash projects */
+    readonly projects: ProjectsService;
+    /** Todos service - list, get, create, update, complete, and manage todos */
+    readonly todos: TodosService;
+    /** Todolists service - list, get, create, and update todo lists */
+    readonly todolists: TodolistsService;
+    /** Todosets service - get todo sets (container for todo lists) */
+    readonly todosets: TodosetsService;
+    /** People service - list, get, and manage people in your account */
+    readonly people: PeopleService;
+    /** Authorization service - get authorization info and identity */
+    readonly authorization: AuthorizationService;
+    /** Messages service - list, get, create, update, pin/unpin messages */
+    readonly messages: MessagesService;
+    /** Comments service - list, get, create, and update comments */
+    readonly comments: CommentsService;
+    /** Campfires service - list, get campfires and manage lines */
+    readonly campfires: CampfiresService;
+    /** Card tables service - get card tables (kanban boards) */
+    readonly cardTables: CardTablesService;
+    /** Cards service - list, get, create, update, and move cards */
+    readonly cards: CardsService;
+    /** Card columns service - get, create, update, and manage columns */
+    readonly cardColumns: CardColumnsService;
+    /** Card steps service - create, update, complete, and manage card steps */
+    readonly cardSteps: CardStepsService;
+    /** Message boards service - get message boards */
+    readonly messageBoards: MessageBoardsService;
+    /** Message types service - list, get, create, update, delete message types */
+    readonly messageTypes: MessageTypesService;
+    /** Forwards service - manage email forwards and replies */
+    readonly forwards: ForwardsService;
+    /** Checkins service - manage questionnaires, questions, and answers */
+    readonly checkins: CheckinsService;
+    /** Client approvals service - list and get client approvals */
+    readonly clientApprovals: ClientApprovalsService;
+    /** Client correspondences service - list and get client correspondences */
+    readonly clientCorrespondences: ClientCorrespondencesService;
+    /** Client replies service - list and get client replies */
+    readonly clientReplies: ClientRepliesService;
+    /** Webhooks service - create, update, delete webhooks */
+    readonly webhooks: WebhooksService;
+    /** Subscriptions service - manage notification subscriptions */
+    readonly subscriptions: SubscriptionsService;
+    /** Attachments service - upload files for embedding in rich text */
+    readonly attachments: AttachmentsService;
+    /** Vaults service - manage folders in the Files tool */
+    readonly vaults: VaultsService;
+    /** Documents service - manage documents in vaults */
+    readonly documents: DocumentsService;
+    /** Uploads service - manage files in vaults */
+    readonly uploads: UploadsService;
+    /** Schedules service - manage schedules and calendar entries */
+    readonly schedules: SchedulesService;
+    /** Events service - view recording change events */
+    readonly events: EventsService;
+    /** Recordings service - manage recordings (base type for most content) */
+    readonly recordings: RecordingsService;
+    /** Search service - full-text search across all content */
+    readonly search: SearchService;
+    /** Reports service - timesheet and other reports */
+    readonly reports: ReportsService;
+    /** Templates service - manage project templates */
+    readonly templates: TemplatesService;
+    /** Lineup service - manage timeline markers */
+    readonly lineup: LineupService;
+    /** Todolist groups service - manage groups within todolists */
+    readonly todolistGroups: TodolistGroupsService;
+    /** Tools service - manage project dock tools */
+    readonly tools: ToolsService;
+    /** Timesheets service - get timesheet data */
+    readonly timesheets: TimesheetsService;
+    /** Timeline service - get project timeline */
+    readonly timeline: TimelineService;
+    /** Client visibility service - manage client visibility */
+    readonly clientVisibility: ClientVisibilityService;
+    /** Boosts service - manage recording boosts */
+    readonly boosts: BoostsService;
+}
+/**
+ * Token provider - either a static token string or an async function that returns a token.
+ * Use an async function for token refresh scenarios.
+ */
+export type TokenProvider = string | (() => Promise<string>);
+/**
+ * Configuration options for creating a Basecamp client.
+ */
+export interface BasecampClientOptions {
+    /** Basecamp account ID (found in your Basecamp URL) */
+    accountId: string;
+    /** OAuth access token or async function that returns one */
+    accessToken?: TokenProvider;
+    /** Authentication strategy (alternative to accessToken for custom auth schemes) */
+    auth?: AuthStrategy;
+    /** Base URL override (defaults to https://3.basecampapi.com/{accountId}) */
+    baseUrl?: string;
+    /** User-Agent header (defaults to basecamp-sdk-ts/VERSION) */
+    userAgent?: string;
+    /** Enable ETag-based caching (defaults to false) */
+    enableCache?: boolean;
+    /** Enable automatic retry on 429/503 (defaults to true) */
+    enableRetry?: boolean;
+    /** Hooks for observability (logging, metrics, tracing) */
+    hooks?: BasecampHooks;
+}
+/**
+ * Creates a type-safe Basecamp API client with built-in middleware for:
+ * - Authentication (Bearer token)
+ * - Retry with exponential backoff (respects Retry-After header)
+ * - ETag-based HTTP caching
+ *
+ * @example
+ * ```ts
+ * import { createBasecampClient } from "@37signals/basecamp";
+ *
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: process.env.BASECAMP_TOKEN!,
+ * });
+ *
+ * const { data, error } = await client.GET("/projects.json");
+ * ```
+ */
+export declare function createBasecampClient(options: BasecampClientOptions): BasecampClient;
+/**
+ * Normalizes a URL path by replacing numeric IDs with placeholder tokens.
+ * For example: /12345/todos/456 → /{accountId}/todos/{todoId}
+ */
+export declare function normalizeUrlPath(url: string): string;
+/**
+ * Fetches all pages of a paginated resource using Link header pagination.
+ * Automatically follows rel="next" links until no more pages exist.
+ *
+ * @example
+ * ```ts
+ * const response = await client.GET("/projects.json");
+ *
+ * const allProjects = await fetchAllPages(
+ *   response.response,
+ *   (r) => r.json()
+ * );
+ * ```
+ */
+export declare function fetchAllPages<T>(initialResponse: Response, parse: (response: Response) => Promise<T[]>, authHeader?: string): Promise<T[]>;
+/**
+ * Async generator that yields pages of results one at a time.
+ * Useful for processing large datasets without loading everything into memory.
+ *
+ * @example
+ * ```ts
+ * for await (const page of paginateAll(response.response, (r) => r.json())) {
+ *   console.log(`Processing ${page.length} items`);
+ * }
+ * ```
+ */
+export declare function paginateAll<T>(initialResponse: Response, parse: (response: Response) => Promise<T[]>, authHeader?: string): AsyncGenerator<T[], void, unknown>;
+export { parseNextLink, resolveURL, isSameOrigin };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}