TypeScript SDK · Qualia

@qualiaso/sdk is the official TypeScript client for the Qualia API. It gives you one typed method per endpoint, so your editor knows every request field and every response field. This page covers installing it, configuring a client, and the calls you will make.

Install

npm install @qualiaso/sdk

The SDK needs Node.js 20 or later. It is an ES module, so load it with import. The examples on this page work with version 0.1.3 and later, except where a section says otherwise.

Create a client

Create one client when your app starts and reuse it. Get an API key from Settings → API Keys first.

lib/qualia.ts

import { Qualia } from "@qualiaso/sdk";

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

Option	Description
`auth`	Your API key, or a function that returns it. A function runs before every request and can be async.
`baseUrl`	The API base URL. Defaults to `https://qualia.so/v1`.
`headers`	Extra headers to send with every request.
`fetch`	A custom `fetch` implementation. Defaults to the global `fetch`.

Each client is independent. You can run several side by side, for example one per API key, or one with a mock fetch in tests.

createActor calls POST /v1/actors:

const { data, error, response } = await qualia.createActor({
  body: {
    email: "anna@ridgeline.co",
    name: "Anna Park",
    source: "signup_form",
    metadata: { company: "Ridgeline" },
  },
});

if (error) {
  console.error("Qualia returned", response.status, error);
} else {
  console.log(data.actorId, data.status); // "created" or "already_exists"
}

Read an actor

getActor calls GET /v1/actors/{actorId}:

const { data: actor } = await qualia.getActor({
  path: { actorId: "q3ab8fnt2kzw7yx1mvd05hce" },
});

if (actor?.status === "enriched") {
  console.log(actor.summary, actor.score);
}

Research takes time, so poll until the actor reaches a final status. Get briefing results has a ready-to-use waitForBriefing helper.

Check your API key

ping calls GET /v1/ping. It needs @qualiaso/sdk 0.2.0 or later. On earlier versions, call the endpoint with fetch or curl, as shown in Manage API keys.

const { data, error, response } = await qualia.ping();

if (error) {
  console.error("The API key did not work", response.status);
} else {
  console.log(data.ok, data.organizationId);
}

The check uses no credits and does not count toward the rate limit.

What every method returns

Every method returns a promise of { data, error, request, response }:

Property	When it is set
`data`	The parsed response body when the request succeeds. `undefined` on an error.
`error`	The parsed error body when the API returns an error status. `undefined` on success.
`response`	The raw `Response`. Always set. Use it to read the status code and headers.
`request`	The `Request` the SDK sent.

An API error does not throw. Check error, or response.status, after each call. Network failures and timeouts do throw, so wrap calls in try/catch where that matters. Errors, retries, and timeouts covers both cases.

Types

The SDK exports a type for every request, response, and error. From version 0.2.0, the error types include every status the API returns, including 402, 413, and 429. Use the types to type your own helpers:

import type { CreateActorData, GetActorResponse } from "@qualiaso/sdk";

type NewSignup = CreateActorData["body"];

function isQualified(actor: GetActorResponse): boolean {
  return actor.status === "enriched" && (actor.score ?? 0) >= 60;
}

Next steps

Errors, retries, and timeouts. Handle failures and set deadlines.
Send signups to Qualia. Add the SDK to your signup handler.
API reference. Every endpoint, with SDK and HTTP examples.

On this page