SDK Reference

@type-dot-com/sdk is the official TypeScript SDK for Type. Use it to write code automations, custom webhook adapters, and scripts that call the Type API.

Install

bun

bun add @type-dot-com/sdk zod@4 neverthrow@8

npm

npm install @type-dot-com/sdk zod@4 neverthrow@8

The SDK runs in Bun. It also includes ESM JavaScript and type declarations for Node 22 or later. Install zod and neverthrow directly, because automation code imports them.

Which SDK version runs your code

Caution

Your automation does not run with the SDK version that you install. Type runs all automation code with the SDK that is part of the current Type server release. The version on your computer is for types and editor help only.

• Type typechecks your code against its own SDK when you deploy. A deploy can fail even if your local typecheck passes.
• The npm release can be older than the SDK in Type. Some exports, for example SlackMessageEvent and replyInSlackThread, are in Type before they are on npm. If an import is missing locally, deploy to check it, or use the type from this reference.
• Type records the automation API version for each saved revision. If a later Type release changes the API, Type marks older automations as upgrade_available or unsupported. See Create and Manage Automations.

Allowed imports in automation code

Automation code runs in a QuickJS VM, not in Node or Bun. It can import only these modules:

Module	Use it for
@type-dot-com/sdk	TypeApiError and shared types.
@type-dot-com/sdk/automations	Automation types and helpers.
@type-dot-com/sdk/webhooks	Webhook adapter types and helpers. Use it in adapter files.
zod	Schemas.
neverthrow	Result, ResultAsync, ok, and err.
Relative files, for example ./format.ts	Your own modules in the same project.

These are not available: fetch, Node APIs, Bun APIs, the file system, a shell, other npm packages, and compiler macros. Use ctx.tools, ctx.read, and ctx.write for network access. Use sandbox commands for shell work.

Entry points

Import path	Contents
@type-dot-com/sdk	The Type API client, TypeApiError, defineAutomation and defineTask for skill scripts, z, and shared types.
@type-dot-com/sdk/automations	Code automation types, event contracts, and helpers. See below.
@type-dot-com/sdk/webhooks	IntegrationWebhook, webhookEvent(), and adapter context types. See Webhook Adapter API.
@type-dot-com/sdk/rpc	createTypeRpcClient(), the client that Type CLI uses.
@type-dot-com/sdk/contracts/*	Zod wire schemas, for example contracts/api and contracts/automation-matchers.
@type-dot-com/sdk/apps, /apps/react, /apps/templates	The SDK for Type Apps. React and Convex are optional peer dependencies.

@type-dot-com/sdk/automations

Types for automation code

Export	Kind	Meaning
AutomationDeployment	Type	The shape of the deployment export. See Deployment API.
DeploymentSubscription	Type	One entry in deployment.subscriptions.
AutomationContext	Type	The ctx argument. See Context reference.
RecurringEvent	Type	{ scheduledAt: string }. The event for a recurring source.
IntegrationEvent<Data>	Type	The envelope of an integration event.
SlackMessageEvent	Type	A Slack message event.
AutomationCheckpoint	Type	{ value, version }.
AutomationExecutionIdentity	Type	The fields of ctx.identity.
AutomationMutationOptions	Type	{ effectKey, signal?, timeoutMs? } for writes.
AutomationMatcher	Type	The match field.
AutomationDebounce	Type	The debounce field.
AutomationExpiration	Type	The expiration field.
IntegrationEventSource, RecurringSource	Type	The source field.
AutomationJevRequest, AutomationJevResult	Type	AI questions and answers.
Action, ActionLog, AutomationActions	Type	ctx.action and ctx.mutativeAction.
SubscriptionHandlers<Events>	Type	Maps subscription keys to method signatures.

Helpers

Export	Meaning
replyInSlackThread(ctx, event, { connectionId, text, effectKey? })	Replies in the Slack thread of the message that started the run. Resolves to { channelId, threadTs, ts }. The default effect key is slack-reply:<channel>:<ts>.
slackMessageEventSchema	The Zod schema for SlackMessageEvent.

replyInSlackThread posts under the message, or in the thread that the message is already in. It fails if Slack does not confirm that the reply is in that thread. In a fixture, its request is:

{
  "service": "slack",
  "name": "slack_post_message",
  "organizationIntegrationId": "orgint_...",
  "arguments": { "channel_id": "C0123456789", "thread_ts": "1712345678.000100", "text": "..." }
}

Schemas

These Zod schemas validate the same shapes on the server. Use them for your own checks.

automationDebounceSchema, automationExpirationSchema, automationMatcherSchema, automationJevRequestSchema, automationJevResultSchema, integrationEventSourceSchema, recurringSourceSchema, recurringEventSchema, subscriptionDefinitionSchema, automationManifestSchema.

Older APIs

The module also exports Automation, integrationEvent(), recurring(), SubscribedAutomation, PureCodeAutomation, CanTriggerAgentAutomation, and WillAlwaysTriggerAgentAutomation. These are for automations that were saved in older formats. Do not use them in new code. Use the deployment export and a default class.

TypeApiError

All SDK errors are TypeApiError objects.

class TypeApiError extends Error {
  readonly code: TypeErrorCode;
  readonly status?: number; // HTTP status, if any
  readonly details?: unknown; // structured API details, if any
  get isVersionConflict(): boolean; // true for HTTP 409 version_conflict
}

code	Meaning
configuration	The client has a missing or wrong setting.
authentication	Type did not accept the credentials.
network	The request did not get a response. A write can still be complete.
timeout	The request took too long. A write can still be complete.
aborted	The signal stopped the request.
invalid_response	The response did not match the expected shape or your schema.
http_error	Type returned an HTTP error. Read status and details.
invalid_input	The input was not valid.

Create your own errors with the same class:

return err(new TypeApiError("The order has no ID", "invalid_response"));

See Errors for messages that the deploy and the runtime return.

The Type API client

Type is a client for the Type agent HTTP API. Use it in scripts and skill code, not in automation code. In automation code, use ctx, which gives the same operations with automation access checks.

import { Type } from "@type-dot-com/sdk";

const type = Type.fromEnvironment(process.env);
const result = await type.search.workspace("quarterly plan");
if (result.isErr()) console.error(result.error.code, result.error.message);

Resource	Operations
data	read, record, list, delete, withSchema
tools	services, find, call, callWithSchema
integrations	search, connect, request, requestWithSchema, webhooks
skills	list, create, update, delete, files, readFile, addFile, updateFile, deleteFile, versions
tasks	list, get, create, update, testCode, delete
spaces	list, messages
threads	list, messages, batch
search	workspace, messages
messages	send

• Each method accepts a last argument { signal, timeoutMs }. The default timeout is 60 seconds.
• The client does not retry. After a timeout or a network error, a write can still be complete.
• Type.fromEnvironment() reads TYPE_SERVER_URL, TYPE_ACCESS_TOKEN, TYPE_AGENT_ID, TYPE_CHANNEL_ID, and TYPE_AUTOMATION_ID.
• tasks.delete archives the task. It does not delete it permanently.

Skill scripts are not automations

defineAutomation and defineTask from @type-dot-com/sdk are for skill scripts. They are not code automations. A skill script runs when an agent or a person runs the skill. A code automation runs on a schedule or an event. To make a code automation, use the deployment export and a default class.