TypeScript SDK

@qualiaso/sdk is the official TypeScript client for the Qualia API.

Install

npm install @qualiaso/sdk

The SDK ships ESM only and supports Node.js 20 or later.

Instantiate

Get an API key from Settings → API Keys (the plaintext is shown once, copy it then). Then create a client instance:

// app/qualia.ts
import { Qualia } from "@qualiaso/sdk";

const qualia = new Qualia({
  auth: () => process.env.QUALIA_API_KEY!,
});

auth is invoked per request, so rotating the key in your environment takes effect on the next call without reloading the process. The default baseUrl is https://qualia.so/v1; override it for staging or self-hosted deployments.

Calling an operation

// app/signup-handler.ts
const { data, error, response } = await qualia.createActor({
  body: {
    email: "anna@ridgeline.co",
    name: "Anna Park",
    source: "product_signup",
  },
});

if (error) {
  // error is fully typed per status code
  return;
}

const { actorId, status } = data;

1. Method names match the OpenAPI operationId. createActor for POST /v1/actors, getActor for GET /v1/actors/{actorId}.
2. Every method returns { data, error, response }. Exactly one of data or error is populated. Branch on error instead of using try/catch.
3. Each Qualia instance owns its own state. Spin up multiple instances side by side for multi-tenant servers, tests with mock fetches, or per-request bearer tokens.

Next

• SDK quickstart. End-to-end example: create an actor, read the briefing.
• Errors and retries. The error envelope, retry policy, and timeouts.