TypeScript SDK · TeamGrid Developer

@teamgrid/api-client is the official TypeScript client for API v1. It parses credential location hints, derives the regional endpoint, enforces bounded response sizes and timeouts, applies safe retries, exposes cursor iterators, and returns stable error classes without retaining the bearer secret.

Use the complete SDK reference for every public method, exact parameter type, scope, HTTP operation, and response contract. The reference is generated from the pinned package source and reconciled with the capability policy and OpenAPI v1 contract.

Install the exact verified stable package version:

npm install @teamgrid/api-client@1.1.0

Pin the exact version in reproducible deployments. Node.js 22.14 through 24 is supported.

Resource clients

One TeamGridClient exposes the complete current API v1 surface:

Client	Operations
`system`, `workspace`	API discovery, authenticated workspace metadata, capabilities, and entitlements
`workspaceSettings`	Read and idempotently compare-and-set the safe six-field workspace-settings projection
`events`	Read the authorization-filtered webhook event catalog
`projects`	List, get, create, update, read/replace sharing, complete, reopen, archive, restore
`projectLifecycleOperations`	Get and wait for asynchronous project lifecycle operations
`tasks`	List, get, create, update, duplicate, move, atomically replace checklist, archive, restore, complete, reopen, timer start and stop
`taskRecurrences`	Preview, list, get, create, update, lifecycle, owner, template, event-ingress, and recheck workflows
`taskRecurrenceVersions`	List, get, and restore immutable recurring-task definition versions
`taskRecurrenceOccurrences`	List, get, override, clear, and retry occurrence-ledger entries with explicit preconditions
`taskRecurrenceOperations`	Get, wait for, and cancel bounded asynchronous recurrence operations
`timeEntries`	List, get, create, update, read/update billing, archive, restore, and cursor page iteration
`contacts`	List, get, create, update
`callNotes`	List, get, create, archive, restore
`contactGroups`	List, get, create, update, archive, restore
`users`	List workspace users
`lists`, `services`, `tags`	List, get, create, update, archive, restore
`customFieldDefinitions`	List, get, create, update, archive, restore
`customFieldValues`	Get one or a bounded batch, compare-and-set, and compare-and-clear resource values
`projectTemplates`	List, get, create, update, archive, restore, instantiate
`projectTemplateInstantiations`	Get and wait for credential-owned instantiation status
`plannedWork`	List a bounded window, get a task schedule, atomically replace a task schedule
`plannedWorkOperations`	Get and wait for credential-owned replacement status
`appointments`, `absences`	Bounded list, get, create, compare-and-set update, archive, restore
`availability`	Read derived user availability in an explicit time zone and bounded interval
`activity`	List activity for an authorized contact, project, or task
`comments`	List, get, create, archive, and restore plain-text target comments
`documents`	List, get, create, compare-and-set update, archive, and restore documents
`files`	List, get, rename, archive, restore, and create private download intents
`fileUploadIntents`	Create, finalize, and cancel private upload intents
`products`	List, get, create, update, archive
`productGroups`	List, get, create, update, archive
`projectStatements`	List, get, create, update, archive, restore
`auditEvents`	List credential and mutation audit events with actor, time, credential, event, outcome, request, source, and target filters
`webhooks`	List, get, create, remove, reveal a replay-safe signing-secret rotation, and queue real-pipeline test deliveries
`webhookDeliveries`	List and get credential-owned delivery metadata
`members`	List, get, change role, and remove workspace members
`invitations`	List, get, create, resend, and cancel invitations
`roles`, `groups`	List, get, create, compare-and-set update, and remove administration resources
`search`	Federated search across explicitly authorized resource types
`exports`	Create and inspect bounded jobs, create download intents, and download buffered or streamed data through the header-only capability
`automationActions`	Read the public automation action catalog
`automationDefinitions`, `automationDefinitionVersions`	Manage versioned automation definitions and inspect immutable versions
`automationRuns`	List and get runs, or abort one with a strong revision
`integrationInstallations`	Read redacted provider-installation status
`authorization`	Inspect or permanently revoke exactly the current credential, and compensate a failed local CLI credential-storage handoff
`personalAccessTokens`	List, create, rotate, and revoke reveal-once personal credentials
`serviceAccounts`	Manage principals, credentials, and compare-and-set resource grants
`changes`	Create checkpoints, list/pages catch-up, and run snapshot-then-catch-up

Paginated clients also expose pages() async iterators. Creates and asynchronous lifecycle starts accept an idempotency key through mutation options. Every method uses the scopes documented in the API reference; the SDK never adds authority beyond the supplied credential.

The compatible package checkpoint for this contract is 1.1.0; pin that exact version in reproducible deployments. Tasks, projects, and project templates expose developer revisions and require typed ifMatch options for their 18 protected mutations. Project lifecycle changes and template instantiation remain asynchronous and also accept a stable idempotency key. Another 47 protected operations retain domain-specific revision types.

Types model finance-gated fields as optional. Product purchasePrice is present only with products:finance:read; project-statement budget entries and purchasePrice require project-statements:finance:read. Supplying acquisition cost on writes requires the corresponding finance write overlay. Webhook delivery objects deliberately omit URLs, request and response data, headers, secrets, and tenant-routing internals.

Runtime behavior

GET requests can be retried after bounded transient failures.
POST requests are retried only when they include an idempotency key.
Planned-work PUT requests are retried only with their idempotency key and strong compare-and-set precondition. Other PUT, PATCH, and DELETE requests are not retried automatically.
Redirects are not followed.
Responses larger than the configured safety limit are rejected.
Workspace-settings updates require a strong wst1 precondition and idempotency key. The SDK binds the response ETag to its returned revision and rejects extra internal settings fields.
Webhook get/create/rotation responses bind their strong whk1 ETag to the returned configuration or rotation revision. A rotation secret exists only in the no-store result and should be moved directly into a secret manager rather than logged or serialized with unrelated data.
exports.download(id, { intentToken, maxBytes }) carries the opaque intent only in X-TeamGrid-Export-Download-Intent, never in a URL, and returns bounded binary data without exposing a private-storage URL.
exports.downloadStream(id, { intentToken, maxBytes }) returns a one-shot Web ReadableStream, verifies any advertised content length, and cancels the upstream response on caller cancellation or a byte-ceiling breach.
authorization.getContext() returns only the exact current credential’s safe no-store metadata; authorization.revokeCurrentCredential() permanently revokes that bearer credential.
webhooks.testDelivery(id, { idempotencyKey }) validates the no-store replay receipt for a synthetic delivery sent through the production queue, worker, signing, HTTPS, and history path.
API and local client failures use separate error classes.
Every success envelope and error exposes immutable transport metadata for request IDs, attempts, status, response headers, rate limits, retry timing, and idempotency replays.
Project lifecycle helpers poll the operation resource; they do not hide an unbounded background job behind a synchronous project response.
Custom-field-value and planned-work writes require the latest resource revision. The SDK accepts either that unquoted revision or the corresponding strong ETag and never sends wildcards.
Project, task, and project-template mutations require ifMatch; the client canonicalizes the typed revision and validates the returned strong ETag before accepting the response.
Template instantiation and planned-work replacement expose the accepted operation; bounded wait() helpers poll credential-owned status without changing operation semantics.
Project lifecycle and template-instantiation wait helpers accept the validated acceptedOperation. When supplied, every poll must preserve its operation identity, target, and action where applicable; CLI --wait always supplies this binding.

Transport metadata is non-enumerable on success envelopes. Existing JSON output and CLI pipelines therefore stay stable while application code can inspect response.transport.

Start with the SDK quickstart, then use: