SDK

@andesine/sdk is the TypeScript client for the Andesine API. It works in Node.js 22 or later, and in browsers and workers. It is open source under the MIT license.

npm install @andesine/sdk

Create a client

import { createClient } from "@andesine/sdk";

const client = createClient({ apiKey: process.env.ANDESINE_API_KEY });

const tree = await client.content.getTree({ channel: "published" });
const page = await client.content.get({ path: "/Docs/Quickstart", channel: "published" });

Without apiKey, the client reads ANDESINE_API_KEY from the environment. baseURL defaults to https://api.andesine.app; set it for a self-hosted instance.

Each operation of the API reference is a method, such as client.entries.get() or client.publishing.publishEntry(). Methods take one object with all the fields, and return the data.

In the browser

Use a publishable key in browser code:

const client = createClient({ apiKey: "adn_pk_..." });

const results = await client.search.published({ query: "install", channel: "published" });

A publishable key can read, search, and, if allowed, answer questions about the published content of its collections. It works only on its allowed origins. See API overview.

For a user

To act for a signed-in user, pass an OAuth access token, and the workspace in a header:

const client = createClient({
  accessToken,
  headers: { "x-workspace-id": workspaceID }
});

The SDK does not sign in users or refresh tokens.

Structured content

toStructuredContent() returns the properties and fragments of an entry as two maps, keyed by field:

import { toStructuredContent } from "@andesine/sdk";

const page = await client.content.get({ path: "/Changelog/v2", channel: "published" });
const { properties, fragments } = toStructuredContent(page);

console.log(properties.releaseDate, fragments.content);

For typed fields, generate content types.

Read a consistent set of pages

Pin related reads to the snapshot of the first read, so all pages come from the same publish:

const tree = await client.content.getTree({ channel: "published" });
const content = client.atSnapshot(tree.snapshotID);
const entry = await content.get({ entryID: "ent_..." });

To list entries with their content, filtered by properties:

const page = await client.content.listEntries({
  channel: "published",
  collectionPath: "/Tutorials",
  descendants: true,
  includeContent: true,
  filters: [{ kind: "text", key: "audience", values: ["beginner"] }]
});

Pagination

import { paginate } from "@andesine/sdk";

for await (const entry of paginate((cursor) => client.entries.list({ cursor }))) {
  console.log(entry.name);
}

Use paginatePages() to work page by page and save the cursor.

AI answers

const result = await client.search.askPublished({
  channel: "published",
  collectionPath: "/Docs",
  question: "How do I install the CLI?"
});

console.log(result.answer, result.sources);

[1] in the answer refers to the source with id 1. Call AI answers from your server with a secret key, or from the browser with a publishable key that allows AI answers. Each answer uses 10 AI credits.

Stream an answer

askPublishedStream and askCurrentStream send the answer while it is written. They take the same input as askPublished and askCurrent:

const controller = new AbortController();
const events = await client.search.askPublishedStream(
  { channel: "published", collectionPath: "/Docs", question: "How do I install the CLI?" },
  { signal: controller.signal, timeout: 120_000 }
);

for await (const event of events) {
  if (event.type === "sources") console.log(event.sources);
  if (event.type === "textDelta") process.stdout.write(event.text);
  if (event.type === "completed") console.log(event.answer);
}

The stream sends one sources event, then textDelta events, then one completed event with the full answer. The text is plain text that can contain Markdown. An answer without sources can complete without textDelta events.

• To stop, call controller.abort() or break from the loop. If you do not read the stream, call await events.return?.() to close it.

• The timeout is for the full stream. timeout: 0 turns it off.

• The SDK does not reconnect or retry a stream.

• An error before the stream starts is an AndesineAPIError. An error during the stream is an AndesineStreamError. A stream that is not complete or not valid gives an AndesineStreamProtocolError.

An answer uses credits when the generation starts, also if it fails or you cancel it later.

Forward a stream to the browser

Keep your secret key on your server. @andesine/sdk/streaming forwards the stream from your server to the browser:

import { toAnswerResponse } from "@andesine/sdk/streaming";

export async function POST(request: Request): Promise<Response> {
  const { question } = await request.json();
  const events = await client.search.askPublishedStream(
    { channel: "published", collectionPath: "/Docs", question },
    { signal: request.signal, timeout: 120_000 }
  );

  return toAnswerResponse(events);
}

toAnswerResponse uses only standard Fetch types and sends no headers or credentials from Andesine. Handle errors that occur before it with your normal error handler. Your hosting platform must support streamed responses.

In the browser, read the response with readAnswerStream:

import { readAnswerStream } from "@andesine/sdk/streaming";

const response = await fetch("/api/ask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ question: "How do I install the CLI?" })
});

for await (const event of await readAnswerStream(response)) {
  console.log(event);
}

Errors

Failed requests throw AndesineAPIError with status, code, message, hints, and data:

import { AndesineAPIError } from "@andesine/sdk";

try {
  await client.entries.update({ id: "ent_...", name: "Installation" });
} catch (error) {
  if (error instanceof AndesineAPIError && error.is("TOO_MANY_REQUESTS")) {
    console.log(error.data?.limit, error.data?.retryAfterSeconds);
  }
}

Timeouts and retries

Requests time out after 30 seconds; set timeout to change it, or 0 to turn it off. Retries are off by default. Set retries: 2 to retry reads and safe writes after network errors and 429 or 5xx responses. Writes that create or update entries and versions send an idempotency key, so a retry never applies them twice.

Webhooks

client.webhooks manages webhooks, and @andesine/sdk/webhooks verifies incoming events. See Webhooks.