JavaScript / TypeScript

Constructors

import { Incld, IncldBrowser } from "@incld/client"

const server = new Incld({
 apiKey: process.env.INCLD_SECRET_KEY!,
 baseUrl: "https://api.incld.dev",
 scope: {
  organizationId: session.organization.id,
  userId: session.user.id, // omit for organization-wide server work
 },
 timeoutMs: 10_000,
 fetch: customFetch, // optional
})

const browser = new IncldBrowser({
 baseUrl: "/api/incld",
 timeoutMs: 10_000,
 fetch: customFetch, // optional
})

Option	Incld	IncldBrowser
apiKey	Required bearer credential	Not accepted
baseUrl	Absolute API origin; defaults to https://api.incld.dev	Same-origin relative path; defaults to /api/incld
timeoutMs	10,000 ms default	10,000 ms default
scope	Recommended tenant boundary: organizationId plus optional userId	Derived by resolveContext; not accepted from the browser
fetch	Optional Fetch-compatible transport	Optional Fetch-compatible transport

Capability	Incld (trusted server)	IncldBrowser (same origin)
Credential	Project secret key	Application session through your proxy
Actions	List, get, define	List and get; define is blocked
Bulk	Read, create, cancel	Read and cancel; create is blocked
Identity fields	Caller supplies trusted IDs	Removed and injected from resolveContext
Custom headers	RequestOptions.headers forwarded	Ignored
React components	Do not pass this client	Provider creates or accepts this client

Never instantiate Incld in a client component

A project secret grants server-level access. Browser code must use IncldBrowser through a framework adapter, even if an environment system can technically expose the key.

Scope tenant server clients at construction

A client without scope is a project administrator. For request-path work, construct a client with the authenticated organization ID. Add the authenticated user ID when the operation must also be isolated to one end user. The protected headers are then applied to list and direct-ID operations alike and cannot be overridden per request.

Resource properties

Property	Service
actions	Action registry
schedules	Schedules, previews, schedule runs, and schedule Audit events
runs	Project-wide run history
approvals	Requests, checks, decisions, commands, and events
approvalPolicies	Approval policy CRUD
auditEvents	Audit queries and manual events
bulkOperations	Operations, chunks, events, and cancellation
sessions	Scoped end-user session tokens

Actions, schedules, and runs

actions.list(params?, options?)

List declared action metadata.

Returns Promise<Page<Action>>

actions.get(identifier, options?)

Get one action by stable identifier.

Returns Promise<Action>

actions.define(input, options?)

Define or update identifier, displayName, description, payloadSchema, and configuration. Server only.

Returns Promise<Action>

schedules.list(params?, options?)

Filter by externalOrganizationId, externalUserId, action, status, limit, and cursor.

Returns Promise<Page<Schedule>>

schedules.get(id, options?)

Get a schedule.

Returns Promise<Schedule>

schedules.create(input, options?)

Create from action, recurrence, timezone, payload, required organization and owner scope, overlapPolicy, and misfirePolicy.

Returns Promise<Schedule>

schedules.update(id, partialInput, options?)

Partially update schedule configuration.

Returns Promise<Schedule>

schedules.remove(id, options?)

Delete future scheduling while returning the final resource.

Returns Promise<Schedule>

schedules.preview(input, options?)

Return a canonical recurrence summary and future occurrences.

Returns Promise<SchedulePreview>

schedules.pause(id, options?) / resume(id, options?)

Control schedule activity.

Returns Promise<Schedule>

schedules.runs(id, page?, options?)

List runs for one schedule.

Returns Promise<Page<Run>>

schedules.events(id, page?, options?)

List schedule lifecycle events.

Returns Promise<Page<AuditEvent>>

runs.list(params?, options?)

Filter by owner, status, action, scheduleId, search, limit, and cursor.

Returns Promise<Page<Run>>

runs.get(id, options?)

Get one run.

Returns Promise<Run>

Approvals and policies

approvals.list(params?, options?)

Filter by resourceId, requesterId, approverId, status, view, limit, and cursor.

Returns Promise<Page<Approval>>

approvals.get(id, options?)

Includes policy snapshot, decisions, and events.

Returns Promise<Approval>

approvals.check(input, options?)

Return approved, status, and optional approvalId for a resource/action/requester.

Returns Promise<ApprovalCheck>

approvals.create(input, options?)

Create a durable request; browser proxy injects requesterId.

Returns Promise<Approval>

approvals.update(id, input, options?)

Update title, description, metadata, or expiresAt while valid.

Returns Promise<Approval>

approvals.decide(id, {decision, reason?, approverId?}, options?)

Canonical approved/rejected decision command.

Returns Promise<Approval>

approvals.approve(id, reason?, options?) / reject(...)

Convenience methods over decide().

Returns Promise<Approval>

approvals.cancel(id, reason?, options?) / revoke(...)

Cancel pending or revoke approved state.

Returns Promise<Approval>

approvals.events(id, page?, options?)

List the append-only lifecycle event page.

Returns Promise<Page<ApprovalEvent>>

approvals.remove(id, options?)

Delete through the API lifecycle command.

Returns Promise<Approval>

approvalPolicies.list(params?, options?)

List policies.

Returns Promise<Page<ApprovalPolicy>>

approvalPolicies.get/create/update/remove

Complete policy CRUD using CreateApprovalPolicyInput and partial updates.

Returns Promise<ApprovalPolicy>

Audit, Bulk, and sessions

auditEvents.list(params?, options?)

Filter components, event type, actor, subject, viewer, time window, and cursor.

Returns Promise<Page<AuditEvent>>

auditEvents.get(id, options?)

Get one event.

Returns Promise<AuditEvent>

auditEvents.create(input, options?)

Create an idempotent manual application event.

Returns Promise<AuditEvent>

auditEvents.tombstone(id, {reason, actorId?}, options?)

Trusted-server PII erasure that preserves the event envelope and appends a reason-coded tombstone.

Returns Promise<AuditEvent>

bulkOperations.list(params?, options?)

Filter by status, action, limit, and cursor.

Returns Promise<Page<BulkOperation>>

bulkOperations.get(id, options?)

Get progress and terminal state.

Returns Promise<BulkOperation>

bulkOperations.create(input, options?)

Server-only creation from action, items, chunkSize, and metadata.

Returns Promise<BulkOperation>

bulkOperations.chunks(id, page?, options?)

Inspect durable chunk attempts and outcomes.

Returns Promise<Page<BulkChunk>>

bulkOperations.events(id, page?, options?)

List operation events.

Returns Promise<Page<BulkEvent>>

bulkOperations.cancel(id, reason?, options?)

Cancel remaining queued work.

Returns Promise<BulkOperation>

sessions.create({claims}, options?)

Create a scoped session token; the browser proxy injects trusted user and organization claims.

Returns Promise<SessionToken>

Transport, pages, and errors

interface RequestOptions {
 signal?: AbortSignal
 idempotencyKey?: string
 headers?: Record<string, string> // Incld only
}

interface Page<T> {
 data: T[]
 meta: { nextCursor: string | null; hasMore: boolean }
}

class IncldError extends Error {
 status: number
 code: string
 fields?: Record<string, string[]>
 requestId?: string
}

Specialized errors are AuthenticationError, ForbiddenError, NotFoundError, and ValidationError.