@agentryhq/typescript-sdk

Type-safe TypeScript client for the Agentry API.

The SDK is backed by Agentry OpenAPI types and exposes:

• ergonomic resource methods (client.agent.inboxes.list(), etc.)
• scoped low-level methods (client.agent.get("/inboxes"))
• automatic auth header injection (Bearer <apiKey>)
• retries with exponential backoff
• request timeout and abort support
• normalized AgentryClientError errors

Installation

npm i @agentryhq/typescript-sdk

Quickstart

import { createAgentryClient } from "@agentryhq/typescript-sdk";

const client = createAgentryClient({
	baseUrl: "https://api.agentry.to",
	apiKey: process.env.AGENTRY_API_KEY,
});

const inboxes = await client.agent.inboxes.list();
const inbox = await client.agent.inboxes.get("[email protected]");
const message = await client.agent.messages.getRaw(
	"[email protected]",
	"msg_123",
);

API style

Use either style depending on your needs:

1. Ergonomic resource methods (recommended):

await client.agent.inboxes.list();
await client.human.auth.createUrl({
	body: { provider: "google_oauth", human_user_id: "user_123" },
});
await client.organization.pods.get("pod_123");

2. Scoped low-level methods (typed, useful for advanced cases):

// Relative scoped path (preferred for low-level namespace calls)
await client.agent.get("/inboxes");

// Absolute OpenAPI path also works
await client.agent.get("/agent/v0/inboxes");

// Global raw client is available when you need full-path access
await client.raw.get("/agent/v0/inboxes");

Constructor options

const client = createAgentryClient({
	baseUrl: "https://api.agentry.to", // required
	apiKey: process.env.AGENTRY_API_KEY, // optional
	timeoutMs: 60_000, // default: 60_000
	maxRetries: 2, // default: 2
	retryBaseDelayMs: 150, // default: 150
	headers: { "X-Custom-Header": "value" }, // optional
	fetch: async (request) => fetch(request), // optional custom fetch
	logger: consoleLikeLogger, // optional logger
});

logger must implement:

{
	debug(message: string, meta?: Record<string, unknown>): void;
	info(message: string, meta?: Record<string, unknown>): void;
	warn(message: string, meta?: Record<string, unknown>): void;
	error(message: string, meta?: Record<string, unknown>): void;
}

Error handling

The SDK throws AgentryClientError for API and network failures.

import {
	AgentryClientError,
	createAgentryClient,
} from "@agentryhq/typescript-sdk";

const client = createAgentryClient({
	baseUrl: "https://api.agentry.to",
	apiKey: process.env.AGENTRY_API_KEY,
});

try {
	await client.agent.inboxes.list();
} catch (error) {
	if (error instanceof AgentryClientError) {
		console.error(error.message);
		console.error(error.statusCode);
		console.error(error.code);
		console.error(error.errorBody);
	}
	throw error;
}

Retries, timeout, and aborting

• Retries are automatic for 408, 429, and 5xx responses.
• Retry count and base delay are configurable with maxRetries and retryBaseDelayMs.
• Timeout is controlled with timeoutMs.
• You can pass an AbortSignal in operation init via OpenAPI init options.

Development

From the package directory:

• install: pnpm install
• build: pnpm run build
• typecheck: pnpm run typecheck
• test: pnpm run test

Optional smoke tests against a deployed API:

• set AGENTRY_SDK_SMOKE=1, AGENTRY_SDK_SMOKE_BASE_URL, AGENTRY_SDK_SMOKE_API_KEY
• run pnpm run test:smoke

OpenAPI parity and convenience-wrapper coverage gates run in monorepo CI before publishing.