@aster/sdk

Canonical source: packages/sdk/README.md · Edit the source file

Low-level JavaScript and TypeScript client for Aster, plus root-level helpers for starting a local Aster server.

Install

npm install @aster/sdk

Quick Start

import { createAsterClient } from "@aster/sdk"

const client = createAsterClient({
  baseUrl: "http://127.0.0.1:4040",
  authToken: process.env.ASTER_AUTH_TOKEN,
})

const health = await client.gateway.health()
console.log(health)

createAsterClient() returns the composed AsterClient, which exposes:

• client.gateway for low-level HTTP gateway methods
• client.runtime for managed runtime socket subscriptions
• client.assistant for prompt, command, abort, and run-stream helpers

External local apps should use @aster/sdk/apps, which handles pairing and scoped app credentials:

import { Aster } from "@aster/sdk/apps"

const aster = Aster.make({
  app: {
    id: "com.example.obsidian",
    name: "Obsidian",
  },
  scopes: ["events.submit", "turns.submit"],
})

await aster.pair()
await aster.events.submit({
  content: "Summarize the current note.",
})

Local Server Helpers

The package root also exports helpers for local development and integration testing:

import { createAster } from "@aster/sdk"

const { client, server } = await createAster({
  port: 4041,
})

try {
  await client.gateway.health()
} finally {
  await server.close()
}

Public Entrypoints

Entrypoint	Contents
@aster/sdk	createAsterClient(), createAsterGatewayClient(), runtime socket helpers, generated gateway types, createAsterServer(), and createAster().
@aster/sdk/gate/client	createAsterClient(), createAsterGatewayClient(), createAsterRuntimeSocketClient(), runtime socket helpers, and generated gateway types.
@aster/sdk/gate/server	Server process helpers.
@aster/sdk/apps	Pairing-first local app SDK with spaces, sessions, turns, runtime, dictation, interactions, and app events.
@aster/sdk/react	React hooks on top of @aster/sdk/apps for pairing state and app event subscriptions.

Source Of Truth

• REST API shape comes from packages/sdk/openapi.json.
• Generated client code lives under src/gate/gen/.
• The gateway runtime is implemented in packages/gate.
• The default product graph is assembled in packages/distro.
• The public docs site and generated reference pages live in products/docs.

Related Packages

• packages/sdk/src/apps provides the local Apps SDK.
• packages/sdk/src/react provides React hooks for the local Apps SDK.
• packages/gate provides the gateway runtime that this client talks to.
• packages/distro provides the default Aster distribution.
• products/docs publishes the generated API and SDK reference.