@companybook/contexthouse-sdk

Typed client for https://api.contexthouse.no/v1, generated from the API's OpenAPI document (openapi.json in this package, also served at https://api.contexthouse.no/v1/openapi.json).

Key

Create a key at https://contexthouse.no/konto/nokler. One key reaches every house you are a member of (or the houses you pick), and loses a house as soon as you leave it. The secret is shown once. A key is read-only unless you tick «Kan også skrive notater».

curl

export CH=ch_…                                   # your key
A=https://api.contexthouse.no/v1

curl -H "Authorization: Bearer $CH" $A/me       # the key, its owner and the houses it reaches
curl -H "Authorization: Bearer $CH" $A/houses/bonum/node-types
curl -H "Authorization: Bearer $CH" "$A/houses/bonum/nodes?q=barolo&type=item"
curl -H "Authorization: Bearer $CH" $A/houses/bonum/nodes/bonum:item:4000128
curl -H "Authorization: Bearer $CH" "$A/houses/bonum/edges?predicate=BOUGHT&dst=bonum:item:4000128"
curl -H "Authorization: Bearer $CH" $A/houses/bonum/marts
curl -H "Authorization: Bearer $CH" "$A/houses/bonum/marts/kpi_overview"
curl -H "Authorization: Bearer $CH" -H 'content-type: application/json' \
  -d '{"sql":"select * from mart.revenue_by_customer order by revenue_ytd desc limit 10"}' \
  $A/houses/bonum/query
curl -H "Authorization: Bearer $CH" -H 'content-type: application/json' \
  -d '{"body":"Ringte kunden, ønsker tilbud på Barolo.","kind":"context"}' \
  $A/houses/bonum/nodes/bonum:customer:22630/notes   # needs a notes key

TypeScript

npm install @companybook/contexthouse-sdk      # ESM, Node 18+ / Bun / Deno / browsers; types included

Inside this repository the same code is the workspace package @contexthouse/sdk ("workspace:*").

import { ContexthouseError, createClient } from "@companybook/contexthouse-sdk";

const ch = createClient({ apiKey: process.env.CONTEXTHOUSE_API_KEY! });
const bonum = ch.house("bonum");

await ch.houses();                                        // [{ slug, name, url }]
await bonum.nodes.search({ q: "barolo", type: "item" });  // NodeSummary[]
const { node, neighbors, notes } = await bonum.nodes.get("bonum:item:4000128");
await bonum.edges({ predicate: "BOUGHT", dst: node.id }); // Edge[]
await bonum.marts.read("kpi_overview");                   // { count, truncated, rows }
await bonum.query("select count(*) as n from graph.nodes");
await bonum.nodes.addNote(node.id, { body: "…", kind: "context" }); // notes key only

try {
  await ch.house("finnesikke").nodeTypes();
} catch (e) {
  if (e instanceof ContexthouseError) console.log(e.status, e.code); // 404 not_found
}

Anything the helpers do not cover is reachable, fully typed, through ch.raw (an openapi-fetch client). Types for every schema are exported as Schemas["NodeDetail"] and so on.

Example: CONTEXTHOUSE_API_KEY=ch_… bun packages/sdk/examples/node-types.ts bonum.

Behaviour worth knowing

• Every call names the house. A house the key does not reach answers exactly like one that does not exist: 404 not_found.
• Errors are { error: { code, message, details? } }; code is one of unauthorized, forbidden, not_found, invalid_request, house_unavailable, internal. message is Norwegian, for people.
• Rate limit: 300 requests per minute per IP (Vercel Firewall, infra/firewall.ts), answered with 429. A burst of many parallel requests can instead get Vercel's DDoS challenge (an HTML 403 with x-vercel-mitigated: challenge) for some minutes. The SDK turns both into ContexthouseError with code rate_limited; back off and keep concurrency low.
• query runs one read-only statement as the house's reader role (schemas graph and mart), 30 s timeout, at most 1000 rows (truncated: true beyond that).
• Numbers from Postgres numeric/bigint arrive as JSON numbers; date columns as ISO timestamps at midnight UTC.
• Responses are never cached (Cache-Control: private, no-store).

Changing the API

The contract is the zod schemas in packages/core plus the route registry in apps/web/src/lib/api/routes.ts. After changing either, run bun run sdk:gen at the repository root; bun run verify fails while openapi.json or src/schema.d.ts is stale.

Publishing

The workspace package is private and exports the TypeScript source. bun run build (part of bun run verify) writes the publishable package to dist/ with its own manifest.

To release, bump version in package.json and land the PR. On merge to main, .github/workflows/sdk-publish.yml tests, builds and runs npm publish from dist/ when that version is not on npm yet. It authenticates with npm trusted publishing (GitHub OIDC), so there is no token and no OTP. Run it by hand with gh workflow run sdk-publish.yml --repo 0-1-no/contexthouse.