TypeScript SDK

Set up from source

The SDK is not published to npm yet. From a checkout of telipot/core, run bun install. Save the following as packages/sdk/example.ts; the workspace resolves @telipot/sdk there.

import { Telipot } from "@telipot/sdk";

const token = process.env.TELIPOT_TOKEN;
if (!token) throw new Error("Set TELIPOT_TOKEN before running this example.");

const client = new Telipot({ token, latest: true });
const { output, receipt } = await client.run("hackernews.news.search", {
  query: "agent tools",
  hitsPerPage: 2,
});

console.log(output);
console.log(receipt.call_id, receipt.identity, receipt.charged_usd);

Get a token under API keys and keep it in your server environment. Then run the file from the repository root:

export TELIPOT_TOKEN='tlp_REPLACE_WITH_YOUR_TOKEN'
bun packages/sdk/example.ts

The output contains Hacker News results and a receipt for the anonymous identity at $0 from telipot. Open Audit log to find its call id. Use baseUrl: "http://localhost:3000" when calling a local gateway.

Discover and inspect

const { candidates } = await client.discover({
  task: "Hacker News stories about agent tools",
});
const task = await client.inspect("hackernews.news.search");
console.log(candidates, task.input, task.output, task.price);

These read the catalog without making a provider call. Telipot returns promises on fetch. In Effect, make(options) returns the same four verbs as Effects on the HttpClient in context.

The principal

as on the client sets whom calls act as; as on a call overrides it. Leave it out for the organization, or the end user fixed to a user-bound token.

Once Ana connects her Calendar, run as her explicitly:

const { output: events, receipt } = await client.run(
  "google-calendar.events.list",
  {},
  { as: "user:ana", version: "latest" },
);
console.log(events, receipt.principal);

The catalog version

A provider's pin comes from the call's version, then the client's versions, then TELIPOT_CATALOG_VERSION_<SLUG>. The slug is uppercase with dashes changed to underscores. latest runs the version currently served.

Without a pin, a run fails with VersionRequired unless the client sets latest: true. A stale pin returns catalog_version_mismatch with the served version.

Connect

Create sessions on your backend; never put an organization token in an end user's browser. Add your callback to the redirect allowlist first.

const session = await client.connect("google-calendar", {
  as: "user:ana",
  scopes: ["calendar.readonly"],
  redirect_uri: "https://your-app.example/connected",
});
console.log(session.url, session.session_id, session.expires_at);

Hand session.url to Ana. With no principal named, connect uses the principal fixed to a user-bound token, or the organization.

Follow the end-user connection guide to verify completion, handle refusals and let Ana revoke access.

Refusals

A refused request rejects with the API's tagged error, such as PrincipalForbidden or CatalogVersionMismatch, and its detail. Check the error's tag and supported recovery fields. A provider-key failure never silently switches to a paid credential.