terse-sdk
v0.6.4
Published
TypeScript SDK for building workflows on the [Terse](https://useterse.ai) platform.
Readme
terse-sdk
TypeScript SDK for building workflows on the Terse platform.
Terse is the AI workflow platform for coding agents. You write durable TypeScript jobs, pause them for humans, and deploy serverlessly. Full docs at docs.useterse.ai.
Install
npm install terse-sdk zodzod is used for job state and structured trigger payloads.
The fastest way to get started is npm install -g terse-cli && terse init my-project. The CLI scaffolds the project, installs terse-sdk, and generates src/terse.generated.ts for you. See the quickstart.
Example
A Terse workflow is a single TypeScript file. The job below watches a repo for new GitHub issues, triages them with a coding agent, pauses for Slack approval, then opens a PR:
import { createJob, slack, step, waitForInput } from "terse-sdk"
import { $ } from "zx"
import { Repos, SlackChannel, Triggers } from "../terse.generated"
// ^^ Generated based on your workspace
createJob({
name: "Fix GitHub issue with a durable coding agent",
triggers: [Triggers.github.onIssueCreated({ repo: Repos.TerseAI.Terse })],
durable: true,
onTrigger: async event => {
const githubUrl = `https://github.com/${event.repository.owner}/${event.repository.name}.git`
await step($`git clone ${githubUrl} ${repoDir}`)
const decision = await waitForInput({
via: slack({ channel: SlackChannel.AllTerseInc.channelId }),
prompt: `Should I make a PR for ${event.issue.title}?`,
options: [
{ id: "make_pr", label: "Make PR" },
{ id: "stop", label: "Stop" }
]
})
if (decision.choice === "stop") return
await step($({ cwd: repoDir })`gh pr create --title ${`Fix #${event.issue.number}: ${event.issue.title}`} --body ${"Opened by a durable coding agent"}`)
}
})Core concepts
For actor development, run terse actor dev in the actor source project, then terse actor generate in your app project. Both the generator and SDK default to the local server on port 7100, project local, with no API key. Set TERSE_ACTOR_URL and, when required, TERSE_API_KEY only to override those defaults or connect to deployed actors. Regenerate after public API changes. See the local actor development guide.
| Concept | What it is |
|---|---|
| createJob() | Registers a workflow at module load time. |
| step() | Wraps a side effect so it runs exactly once in a durable job. |
| waitForInput() | Posts a Slack prompt and suspends until a human answers. |
| Triggers.* | Per-integration trigger builders, plus Triggers.schedule.cron() and Triggers.webhook.onRequest<Body>(). |
The trigger builders and resource constants come from src/terse.generated.ts, which is produced by terse generate. Do not edit it by hand.
Full reference: docs.useterse.ai/reference/typescript-sdk.
Environment
| Variable | Description |
|---|---|
| TERSE_PROJECT_KEY | Required at runtime. The control plane injects it into Terse Cloud sandboxes; on a self-hosted data plane, terse attach prints one to put in your server's environment. |
| TERSE_API_KEY | Your user token, used by the CLI. Stored per user by terse login. Local runs fall back to it when no project key is set. |