@sapiom/tools

@sapiom/tools

A typed TypeScript client for Sapiom capabilities — sandboxes, git repositories, coding agents, file storage, content generation, search, email, domains, orchestrations, and schedules — authenticated to your tenant.

These are the same capabilities your Sapiom agents call as tools; this package makes them callable directly from your own code.

npm install @sapiom/tools
# or
pnpm add @sapiom/tools

Quickstart

import { createClient } from "@sapiom/tools";

const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });

// Create a repo, have a coding agent build into it, then publish.
const repo = await sapiom.repositories.create("landing-page");
const run = await sapiom.models.coding.run({
  task: "Build a one-page marketing site in index.html.",
  gitRepository: repo, // cloned into the run's sandbox at /workspace/landing-page
});

if (run.result?.success) {
  const { sha } = await repo.pushFromSandbox(run.sandbox, {
    message: "build: landing",
  });
  console.log("published", sha);
}

Authentication

There are two ways to authenticate, both exposing the identical capability surface:

• Explicit — pass a key to createClient. This is the standalone entry point:

  const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });
  await sapiom.sandboxes.create({ name: "demo" });
  

• Ambient — import the namespaces directly and they resolve credentials from SAPIOM_API_KEY (or, inside a Sapiom workflow step, from the client the runtime provides):

  import { sandboxes, repositories, agent } from "@sapiom/tools";
  await sandboxes.create({ name: "demo" });
  

Attribution

Calls can be attributed to an agent and trace so they show up correctly in your transaction history. Attribution is set once, on the client — not per call:

const sapiom = createClient({
  apiKey: process.env.SAPIOM_API_KEY,
  attribution: { agentName: "digest-bot", traceId },
});
// every call this client makes is now attributed to digest-bot / traceId

Inside a Sapiom workflow you don't set this at all — the runtime constructs the client with the running execution's attribution, so every tool call is attributed automatically.

If a single process makes calls on behalf of more than one agent or trace, derive a client per context with sapiom.withAttribution({ ... }).

Capabilities

Each capability is a namespace, importable from the barrel or its own subpath (e.g. @sapiom/tools/sandboxes). Every capability has its own README with usage details, preconditions, and gotchas the type signatures can't express — read it before first use.

Namespace	What it is	Docs
sandboxes	Isolated, ephemeral compute	src/sandboxes
repositories	Private, in-network git repos	src/repositories
agent	Coding agents (LLM execution)	src/agent
fileStorage	Tenant-scoped object storage (presigned URLs)	src/file-storage
contentGeneration	Media generation (images + video; audio soon), with optional storage	src/content-generation
search	Search the web (webSearch), read a page (scrape), and look up professional emails (emailSearch)	src/search
orchestrations	Run a deployed orchestration, or dispatch one from a step and await its result	src/orchestrations
schedules	Schedule a deployed orchestration to run on a cron, or once at a set time	src/schedules
database	On-demand Postgres databases, returned with direct connection credentials	src/database
email	Transactional email — inboxes, messages, sending domains, threads, and inbound webhooks	src/email
domains	Register domain names and manage their DNS records	src/domains
memory	Tenant-scoped long-term memory (append-log; cosine recall, Neon keyword recall)	src/memory

Composing capabilities

Capabilities are designed to work together. A coding agent run hands back the live Sandbox it executed in, and a Repository can publish a working tree straight from that sandbox:

const run = await agent.coding.run({ task, gitRepository: repo });
await repo.pushFromSandbox(run.sandbox);

A useful pattern: let the agent do the open-ended work (writing files) and perform exact, repeatable actions — committing, pushing, deploying — in your own code rather than in the agent's prompt. The agent produces the changes; pushFromSandbox publishes them deterministically.

Some compositions need nothing but a param. contentGeneration.images.create takes an optional storage, and each generated image is persisted into fileStorage as it returns — handing you a durable fileId with no extra call:

const out = await contentGeneration.images.create({
  prompt: "a logo",
  storage: { visibility: "private" },
});
const { downloadUrl } = await fileStorage.getDownloadUrl(
  out.images![0].fileId!,
);

Usage analytics

The SDK can emit anonymous usage analytics — one capability.call event per capability request, carrying the capability name, the request URL path (query strings are stripped, never recorded), HTTP status, duration, and request size (never request or response bodies). Events describe calls to Sapiom's own API only; nothing is captured about any third-party traffic.

By default nothing is sent anywhere: the emitter (see @sapiom/analytics-core) is a no-op unless a collector endpoint is configured. Delivery is batched in the background and can never throw, block, or slow a capability call. Opt out any time with SAPIOM_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.

If your process constructs many clients over its lifetime (one per execution, for example), call await client.shutdown() when you're done with each one: it flushes any buffered events and detaches the emitter's process exit hook. It's idempotent, never rejects, resolves immediately when there's nothing to release, and covers every client derived via withAttribution. One-shot scripts don't need it — events flush on process exit. Capability calls made after shutdown still work; they just no longer emit analytics.

License

MIT