Get access

SDKs and tools · 20 / 42

TypeScript

Use the platform fetch API to call Northsun over the frozen public caller-memory contract. This keeps your integration pinned to the three stable REST endpoints without an SDK dependency.

Node 18 or newer includes the required global fetch.

Create a small client

const baseUrl = "https://mcp.northsun.ai";
const apiKey = process.env.NORTHSUN_API_KEY!;

async function northsun<T>(path: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(`${baseUrl}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Northsun ${response.status}: ${body}`);
  }

  return response.status === 204
    ? (undefined as T)
    : ((await response.json()) as T);
}

Production applications should add a request timeout, structured error parsing, and the retry policy in Errors and retries.

Recall before the interaction

const packet = await northsun<{
  known: boolean;
  caller: { name: string | null };
  memory: { summary: string };
  enrichment: {
    person: { name: string | null; title?: string | null; company?: string | null } | null;
    company: { name: string | null } | null;
    phone: { carrier: string | null; line_type: string | null } | null;
  };
}>("/v1/recall_and_enrich", {
  method: "POST",
  body: JSON.stringify({
    phone_number: "+15551234567",
    trigger: "answered",
    session_id: "call_01",
  }),
});

console.log(packet.caller.name);
console.log(packet.memory.summary);
console.log(packet.enrichment.phone?.line_type);

Enrichment fields may be null. Treat enrichment as additional context, not as a condition for continuing the call.

Write back after hangup

await northsun<void>("/v1/calls/end", {
  method: "POST",
  body: JSON.stringify({
    phone_number: "+15551234567",
    session_id: "call_01",
    transcript: [
      { role: "user", text: "Please call me Tuesday.", ts_ms: 0 },
      { role: "agent", text: "I will note that request.", ts_ms: 2_400 },
    ],
    duration_s: 18,
    outcome: "callback_requested",
  }),
});

The endpoint returns 204 No Content on success.

Read without enrichment

const phone = encodeURIComponent("+15551234567");
const caller = await northsun(`/v1/caller/${phone}`);

This endpoint does not create a caller and does not trigger enrichment. An unknown number returns 404 with code not_found.

npm client status

A published npm client exists under its current scope, and the Northsun-scoped name is in progress. Its current release (0.2.2) maps its methods onto the three frozen routes; the earlier 0.2.0 release predates that mapping and should not be used for a new integration. The examples here use native fetch, which is the supported path. If you use the client, pass the base URL https://mcp.northsun.ai explicitly: the published release defaults to an earlier hostname that serves the same surface.

Next steps