https://hellogram.ai/sdk/hellogram.js

1/**
2 * Hellogram SDK v1 — the relationship memory layer for devices.
3 * Works in browsers, Node 18+, Deno and Bun (anything with fetch).
4 *
5 *   import { Hellogram } from "https://hellogram.ai/sdk/hellogram.js";
6 *   const hg = new Hellogram({ apiKey: "hg_live_..." });
7 *   const session = await hg.startSession({ externalId: "device-1:sean", displayName: "Sean" });
8 *   const reply = await hg.chat({ externalId: "device-1:sean", messages: [{ role: "user", content: "hi" }] });
9 */
10
11const DEFAULT_BASE_URL = "https://ustetfwhlulvpqwtptfd.supabase.co/functions/v1/hellogram-api";
12
13export class HellogramError extends Error {
14  constructor(message, status) {
15    super(message);
16    this.name = "HellogramError";
17    this.status = status;
18  }
19}
20
21export class Hellogram {
22  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, fetchImpl } = {}) {
23    if (!apiKey) throw new HellogramError("apiKey is required", 0);
24    this.apiKey = apiKey;
25    this.baseUrl = baseUrl.replace(/\/$/, "");
26    this.fetch = fetchImpl || globalThis.fetch.bind(globalThis);
27  }
28
29  async request(path, body = {}) {
30    const res = await this.fetch(`${this.baseUrl}${path}`, {
31      method: "POST",
32      headers: {
33        Authorization: `Bearer ${this.apiKey}`,
34        "Content-Type": "application/json",
35      },
36      body: JSON.stringify(body),
37    });
38    const data = await res.json().catch(() => ({}));
39    if (!res.ok) throw new HellogramError(data.error || `Request failed (${res.status})`, res.status);
40    return data;
41  }
42
43  /** Open a session. Increments the session counter and returns remembered context. */
44  startSession({ externalId, displayName } = {}) {
45    return this.request("/v1/sessions/start", { external_id: externalId, display_name: displayName });
46  }
47
48  /** Read remembered context without starting a session. */
49  getContext({ externalId } = {}) {
50    return this.request("/v1/context", { external_id: externalId });
51  }
52
53  /** Store one or more durable facts about the person. */
54  remember({ externalId, facts, source } = {}) {
55    return this.request("/v1/remember", {
56      external_id: externalId,
57      facts: Array.isArray(facts) ? facts : [facts],
58      source,
59    });
60  }
61
62  /** Delete one fact, or every fact for this person. */
63  forget({ externalId, factId, all } = {}) {
64    return this.request("/v1/forget", { external_id: externalId, fact_id: factId, all });
65  }
66
67  /** Memory-aware reply. Returns { say, remembered, facts }. */
68  chat({ externalId, messages, persona } = {}) {
69    return this.request("/v1/chat", { external_id: externalId, messages, persona });
70  }
71
72  health() {
73    return this.request("/v1/health");
74  }
75}
76
77export default Hellogram;