Quickstart · TypeScript / JavaScript · ~5 min

TypeScript / JavaScript SDK

Behavioral intelligence for any JS runtime — Node 18+, Deno, Bun, and modern browsers. Ships full TypeScript types and a one-line wrap for any of 20+ providers (OpenAI, Anthropic, Gemini, Groq, Ollama, Bedrock, and more).

1. Install

bash

npm i @humane-ai/sdk
# or pnpm add @humane-ai/sdk
# or bun add @humane-ai/sdk

2. Your first call

typescript

import { HumaneClient } from "@humane-ai/sdk";

const client = new HumaneClient({ apiKey: process.env.HUMANE_KEY! });

const r = await client.process({
  userId: "patient_42",
  message: "I'm really struggling with this",
});

console.log(r.response);              // AI response shaped by behavioral context
console.log(r.user.mood);             // 0.28
console.log(r.safety.action);         // "PROCEED" | "HOLD" | "BLOCK"
console.log(r.analysis?.reasons);     // ["'struggling' → sadness (negative)"]

3. One-line wrap for OpenAI

Drop-in wrapper — every chat.completions.create() call now carries a .humane property with the full behavioral payload.

typescript

import OpenAI from "openai";
import { wrap } from "@humane-ai/sdk";

const client = wrap(new OpenAI(), { humaneKey: process.env.HUMANE_KEY! });

const resp = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "I'm anxious" }],
  user: "patient_42",
});

console.log(resp.choices[0].message.content);
console.log((resp as any).humane.user.mood);       // 0.31
console.log((resp as any).humane.safety.action);   // PROCEED | BLOCK

Blocked messages never hit OpenAI

If Humane's safety gate returns BLOCK, the wrapper short-circuits before calling OpenAI — no token spend on blocked messages.

4. Streaming

typescript

for await (const ev of client.stream({ userId: "patient_42", message: "tell me more" })) {
  if (ev.type === "metadata") {
    console.log("mood:", ev.data.user.mood, "safety:", ev.data.safety.action);
  } else if (ev.type === "token") {
    process.stdout.write(ev.data.content);
  } else if (ev.type === "final") {
    // Full text + metadata — reconcile state here.
  }
}

5. Verifying webhook signatures

Webhook receivers MUST verify the X-Humane-Signatureheader. Import the helper from the sub-path @humane-ai/sdk/webhook:

typescript

import express from "express";
import { verifyWebhookSignature } from "@humane-ai/sdk/webhook";

const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-Humane-Signature");
  if (!verifyWebhookSignature(process.env.HUMANE_WEBHOOK_SECRET!, req.body, sig)) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // handle event ...
  res.sendStatus(200);
});

6. Safe retries

typescript

await client.process({
  userId: "patient_42",
  message: "hi",
  idempotencyKey: "req_8f3c9a1b4d",   // same key + same body → cached reply
});

7. Durable history

typescript

const history = await client.getHistory("patient_42", 200);
// → [{ role, content, timestamp }, ...] from the platform DB

await client.clearHistory("patient_42");  // GDPR right-to-erasure

Next steps

Python Quickstart

cURL Quickstart