SDK reference

import { connect } from "@hub-ki/app-sdk";

const hub = await connect();

const hub = await connect({
  timeoutMs: 10_000, // reject if the host doesn't answer (default 10s)
});

document.documentElement.dataset.theme = hub.context.theme;
const stop = hub.onContextChange((context) => {
  document.documentElement.dataset.theme = context.theme;
});

if (hub.hasScope("responses:run")) {
  showSummarizeButton();
}

const user = await hub.getUser(); // { id, name, email }

const { coreUrl, iamUrl, organizationId } = await hub.getConnection();

let token: string | null = null;
const stop = hub.onToken((next) => {
  token = next; // delivered immediately, then on every refresh
});

await hub.getToken(); // or pull a fresh token on demand

await hub.store.set("theme", "dark");
const theme = await hub.store.get("theme"); // string | null
await hub.store.setJSON("prefs", { compact: true });
const prefs = await hub.store.getJSON<Prefs>("prefs"); // Prefs | null
await hub.store.keys(); // string[]
await hub.store.remove("theme");

const { documents } = await hub.workspace.list(); // documents and files, each with a `kind`
const file = await hub.workspace.createFile({ name: "board.json", content });
await hub.workspace.updateFile({ fileId: file.id, content });

const docs = await hub.listDocuments({ limit: 20 });
const { markdown } = await hub.getDocument(docs[0].id);

await hub.publishEvent("board-updated", { boardId });
const stop = hub.onEvent(({ event, payload }) => {
  /* another session changed something */
});

const response = await hub.responses.create(
  { input: "Summarize this board" },
  {
    onEvent: (event) => {
      if (event.type === "response.output_text.delta") {
        append(event.delta); // streamed output
      }
    },
  }
);
console.log(response.output_text);

// Continue the conversation
const followUp = await hub.responses.create({
  input: "Shorter, please",
  previousResponseId: response.id,
});

// Structured output
const structured = await hub.responses.create({
  input: "List the three most urgent cards",
  text: {
    format: {
      type: "json_schema",
      name: "urgent_cards",
      schema: {
        type: "object",
        properties: { cards: { type: "array", items: { type: "string" } } },
        required: ["cards"],
      },
    },
  },
});
const { cards } = JSON.parse(structured.output_text);

await hub.toast({ message: "Saved", variant: "success" });
await hub.setTitle("My board"); // sets the browser tab title
await hub.share(file.id); // opens the host share dialog for a workspace entry

import { HubError } from "@hub-ki/app-sdk";

try {
  await hub.getConnection();
} catch (error) {
  if (error instanceof HubError && error.code === "TIMEOUT") {
    /* … */
  }
}

hub.disconnect(); // detach the bridge listener

const hub = await connect({
  mock: {
    scopes: ["workspace:own", "documents:read"],
    hostContext: { theme: "dark" },
    documents: [
      { id: "d1", kind: "document", title: "Notes", markdown: "# Notes" },
    ],
  },
});

const hub = await connect({
  mock: {
    onCall: (method) =>
      method === "user.current"
        ? { id: "u1", name: "Test User", email: "test@example.test" }
        : undefined,
  },
});

const hub = await connect({
  mock: {
    scopes: ["store:own"],
    onCall: (method, params) => {
      if (method === "store.set") {
        localStorage.setItem(params.key, params.value);
        return { ok: true };
      }
      if (method === "store.get") return localStorage.getItem(params.key);
      return undefined;
    },
  },
});

const hub = await connect({
  mock: {
    scopes: ["responses:run"],
    responses: {
      create: (params) => ({
        response: {
          id: "resp_1",
          status: "completed",
          output_text: `echo: ${params.input}`,
        },
      }),
    },
  },
});