TypeScript SDK

@singulacomp/sdk is the typed client for the SingulaComp platform. It wraps the SingulaComp REST API and OpenCode REST runtime in one interface. The core client is fetch-based and runs in Node, Bun, and browsers.

Install

npm install @singulacomp/sdk

react (18+) and @tanstack/react-query (5.75+) are optional peers, needed only for React hooks.

Create a client

Call createSingulaComp once, with your API base URL and a function that returns your token.

import { createSingulaComp } from '@singulacomp/sdk';

export const singulacomp = createSingulaComp({
  backendUrl: 'https://api.singulacomp.ai/v1',
  getToken: async () => process.env.SINGULACOMP_API_KEY!,
});

backendUrl and getToken are the only required fields. The SDK calls getToken on every request and caches nothing — your host owns token storage and refresh.

Create an API key in your own settings, at Settings → API keys (/settings/tokens). The key starts with singulacomp_pat_ and shows only once. Store it as a secret and return it from getToken. See Auth for token types and scopes.

Call a Connector

A Connector defines callable tools. A Connection stores one authorization for that Connector. Credentials stay server-side.

const connectors = singulacomp.project(projectId).connectors;

await connectors.catalog();
await connectors.search('send email');
await connectors.describe('gmail.send_email');
await connectors.call('gmail.send_email', { to, subject, body });

An agent-minted session token already carries its project scope. Use singulacomp.connectors when the agent does not have a separate projectId value.

Start your first session

1. Create a session in your project.

   const created = await singulacomp.project(projectId).sessions.create();
   const session = singulacomp.session(projectId, created.session_id);

2. Wait for the sandbox to accept work.

   await session.ensureReady();

   ensureReady() starts or resumes the session sandbox. It polls the session's /start endpoint — each call long-polls up to 30 s — until the runtime is ready, hits a terminal stage, or its deadline elapses (default ~3 min, configurable via { readyTimeoutMs }). On a cold boot it keeps polling while the sandbox reports retriable: true; it only throws an ApiError with code: 'RUNTIME_UNAVAILABLE' if the runtime is still not ready when the deadline expires. See Sessions.

3. Send a message to the agent.

   await session.send('Add a README');

   send() calls ensureReady() for you, then sends the message.

createSingulaComp gives you an imperative client: call methods for every action, like projects, sessions, secrets, and triggers. @singulacomp/sdk/react gives you hooks for live UI data — useSession runs a whole session in one hook.