SDK quickstart

This guide makes a createActor call and reads the resulting briefing using @qualiaso/sdk.

1. Create a client instance

Do this near app startup. Hold the instance somewhere you can reach from request handlers (a singleton module, your DI container, etc.).

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

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

For multi-tenant servers, instantiate per request with the right bearer token instead. Each instance owns its own underlying client.

2. Create an actor on signup

createActor is idempotent on email, scoped to your organization. Call it from your signup handler. New emails return a created actor and enqueue enrichment; existing emails return already_exists with the original actorId.

// app/signup-handler.ts
import { qualia } from "./qualia";

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

if (error) throw error;

const { actorId, status } = data;
console.log(status, actorId);

status is "created" for a new actor (enrichment is enqueued) or "already_exists" if one with the same email is already on file.

3. Read the briefing

In production, poll the actor until status === "enriched" (success) or "failed" (terminal failure). For a smoke test this is enough:

// app/read-briefing.ts
const { data: actor, error } = await qualia.getActor({
  path: { actorId },
});

if (error) throw error;

console.log(actor.status, actor.intelligence);

Next

• Errors and retries. The discriminated error model and a recommended retry policy.
• API reference. Every operation page with a @qualiaso/sdk snippet alongside curl.
• Concepts. The meaning behind actor and briefing.