@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 agent 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 agent run 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 (namespace-isolated append-log; semantic/keyword/hybrid 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