JavaScript SDK

Install, and a first call

The SDK is framework-agnostic and has no runtime dependencies. It runs in a browser and in Node 18+ (anywhere fetch exists, or you can inject one).

Not on npm yet. @cg/sdk is currently a private workspace package inside the CivicGate monorepo, so npm install @cg/sdk will not resolve. Until it is published, the two supported paths are the browser bundle below and vendoring the source. Everything else on this page describes the surface you get either way.

In a browser, with no build step

<script src="https://www.civicgate.org/widget/civicgate-widget.js" async></script>
<script>
  CivicGate.configure({ apiKey: "cg_live_…" });   // only for account-scoped widgets
</script>

<!-- one bill's public wall — no credential needed -->
<div data-cg-widget="wall" data-type="bill" data-id="hr-22-119"></div>

Every widget and every attribute is documented on widgets.

In an app with a bundler

import { createClient } from "@cg/sdk";

const cg = createClient({ apiKey: "cg_live_…" });

// A bill's public wall needs no credential at all:
const page = await cg.subjectFeed("bill", "hr-22-119", 10);
for (const e of page.events) {
  console.log(e.occurredAt, e.title, e.url);
}

There are two things called CivicGate, and they are not the same object. The browser bundle defines window.CivicGate = the widget runtime (configure, mount, refresh, takeLoginVerifier). The SDK exports a CivicGate of its own = the kernel namespace (configure, client, cache, people, resource, refresh, reset). Only configure and refresh exist on both, and they take different options. Reaching for CivicGate.people after loading the bundle gets you undefined.

createClient

One client holds the endpoint and the credential, so a host page configures once and every call shares it. A client with neither credential is still useful — most of CivicGate is public.

import { createClient } from "@cg/sdk";

// Third-party page: a read-only key, safe to ship in the markup.
const cg = createClient({ apiKey: "cg_live_…" });

// First-party page: a GETTER for the session bearer, read fresh on every call.
const cg = createClient({ token: () => localStorage.getItem("cg-token") });

// Public data only. No sign-up, no key.
const cg = createClient();

Which credential

A key being read-only is a property of the server, not of this client: the gateway refuses every mutation on a key-authenticated request. So a key pasted into a public page cannot change the account it belongs to, and cannot widen what that page can see. Create and scope keys at Settings → API keys; details on API keys.

Every method

All 23 methods on the client, grouped. Each is a thin, typed wrapper over query(), so anything the typed surface does not cover is still reachable through that — and every query, mutation and type is enumerated in the generated schema reference.

Every read takes an optional trailing AbortSignal. Pass one from your component's teardown and a cancelled request surfaces as an ABORTED error you can ignore, rather than a state update into an unmounted view.

Three feed sources, not one filtered query. feed() can only ever return events from subjects the caller already follows, so filtering it by someone else's id shows a visitor an empty page. Use subjectFeed() for a subject's public wall and placeFeed() for a place — a place is not a subject, it is a set of them.

Filtering a feed

FeedFilter takes subjectGroups (families), subjectTypes (concrete types, unioned with the groups), eventTypes, a limit of 1–50 (default 10), a cursor, and sort of newest (default) or oldest.

const page = await cg.feed({
  subjectGroups: ["bills"],
  eventTypes: ["bill_status", "bill_vote"],
  limit: 20,
});

// Paging: pass nextCursor back VERBATIM. It is opaque — do not parse it.
if (page.hasMore) {
  const older = await cg.feed({ subjectGroups: ["bills"], limit: 20, cursor: page.nextCursor });
}

The four subject groups, generated below from the same @cg/core/feed catalog the gateway and the ingestion signals import — so this table cannot go stale when a type is added:

That is 18 subject types and 38 event types in total. Rather than copying either list, fetch it at runtime with catalog() — or, if you build against the monorepo, import SUBJECT_TYPES / EVENT_TYPES from @cg/core/feed directly. Every value is enumerated on widgets → reference.

createFeedStore — the SWR layer

A raw feed() call gives you a page. createFeedStore() gives you a live list: it paints from cache on the first frame, revalidates behind that, and keeps polling politely for as long as anyone is looking at it. It is a plain subscribe / getSnapshot store, so Preact, React, Vue or hand-written DOM can all drive from it.

import { createClient, createFeedStore } from "@cg/sdk";

const cg = createClient({ apiKey: "cg_live_…" });
const store = createFeedStore(cg, { filter: { subjectGroups: ["bills"] }, limit: 20 });

const off = store.subscribe((s) => render(s));   // called on every meaningful change
render(store.getSnapshot());                     // paint NOW, synchronously
store.start();                                   // cached snapshot, then fetch, then poll

// later
await store.loadMore();   // append the next (older) page
await store.refresh();    // force a check now, bypassing the interval
store.stop();             // stop polling and abort anything in flight
off();

What it guarantees

• Synchronous first paint. start() reads the last page out of localStorage and publishes it before anything is awaited, so a returning visitor sees real content on frame one instead of a spinner. Only the first page is persisted — deeper pages are cheap to refetch and would bloat storage.
• Background refresh every ~12s (refreshMs, default 12000; 0 disables polling). The refresh replaces page one and keeps the older pages already loaded, so a loadMore() result does not vanish under a poll.
• Polling pauses on a hidden tab and fires one immediate tick when the tab becomes visible again, so a returning reader never waits out the interval they just missed. A backgrounded tab hammering the API all day is the easiest way to look like abuse.
• A failed refresh never blanks a working feed. On error the events already on screen are kept, error is populated and loading goes false. Render the list and the error; never treat a non-null error as "show nothing".
• start() is idempotent. Calling it twice — a re-mount in dev — does not double the interval.

For someone else's wall, pass subject, not a filter. createFeedStore(cg, { subject: { type: "user", id: "handle" } }) calls subjectFeed(). Writing { filter: { subjectId: "…" } } instead filters the reader's own feed, which shows a visitor an empty profile. Everything else — SWR, paging, persistence — is identical, which is why both live in one store.

The kernel — one cache for a page of widgets

A page can carry a dozen CivicGate widgets, and three cards for the same member is the ordinary case rather than the edge case. The kernel is what makes that cost one request: it owns the endpoint and credential, one cache, one in-flight request per key, and error normalisation. Split any of those across widgets and the sharing evaporates.

import { CivicGate } from "@cg/sdk";

CivicGate.configure({ apiKey: "cg_live_…" });

// Three widgets calling this in the same tick = ONE network request.
const card = await CivicGate.people.get("ted_cruz");
// → { id, name, party, state, role, roles[], imageUrl, internalUrl, updatedAt }

CivicGate.people.peek("ted_cruz");   // synchronous cached read, for a first paint
await CivicGate.refresh();           // revalidate every loaded widget; never rejects

• configure() is safe to call twice. Re-configuring with the same endpoint and credential returns the existing kernel untouched, so a second widget's defensive call cannot throw away the first one's warm cache. The cache is wiped only when the credential itself changes — a cache that outlives a sign-out is exactly how a signed-in payload lands on an anonymous screen.
• createKernel() builds a standalone one, outside the singleton. Use it only when a page hosts two genuinely independent embeds that must not share a cache or a credential.
• Link to card.internalUrl, not to a URL you rebuilt. A person owns several resolving slugs; the gateway returns the canonical one, and every other form 301-redirects onto it.
• The cache picks IndexedDB → localStorage → memory by itself, bounds itself at 500 entries, evicts on write (a TTL checked only on read frees nothing), and never throws — a widget must not die because Safari is in private mode.
• Everything on the kernel today is public, viewer-independent data, which is what makes one shared cache safe. A service that ever returns viewer-dependent data has to scope its own key first.

CivicGate.resource({ key, fetcher }) is the extension point: it builds an SWR resource on the kernel's cache and deduper, with the same loading | stale | fresh | error status vocabulary. Reuse it rather than writing a second SWR layer.

Import from the leaf, not the index

This one is measured, and it is expensive. Import the feed catalog from @cg/core/feed — the leaf module. Importing the package index (@cg/core) drags zod into the bundle and takes a widget from 29 kB to 355 kB. Nothing errors; the widget simply gets twelve times heavier, which is why it survived unnoticed.

import { SUBJECT_TYPES, EVENT_TYPES } from "@cg/core/feed";   // ✅ 29kb
import { SUBJECT_TYPES } from "@cg/core";                     // ❌ 355kb — pulls in zod

@cg/sdk follows the same discipline: it is sideEffects: false and every module is also a leaf entry point, so a bundle that only renders a person card does not carry the feed store, the upload helpers or the catalog.

Error handling

Three completely different failure shapes reach a caller through the same method: a DOMException when a component unmounts mid-request, a bare TypeError when the network or an ad-blocker kills it, and a GraphQL error whose extensions.code is the only one that carries meaning. A UI cannot render three shapes, so the SDK normalises them into one.

The raw client throws a GqlError, which has code and traceId but no retryable. That flag lives on CivicGateError, which you get by passing the thrown value through normalizeError() (the kernel and its services do this for you). Reading e.retryable off a raw client rejection gets undefined, which is falsy — so every failure would look permanent and a rate limit would never be retried.

import { createClient, normalizeError, isAborted } from "@cg/sdk";

const cg = createClient({ apiKey: "cg_live_…" });

async function feedWithRetry(attempt = 0) {
  try {
    return await cg.feed({ limit: 20 });
  } catch (raw) {
    const e = normalizeError(raw);          // ← without this there is no .retryable

    if (isAborted(e)) return null;          // we cancelled on purpose; say nothing

    if (e.code === "RATE_LIMITED" && e.retryable && attempt < 4) {
      // The window is one minute. Back off exponentially with jitter — a fixed
      // retry from many clients re-synchronises them into the next burst.
      const waitMs = Math.min(60_000, 2 ** attempt * 1_000) + Math.random() * 500;
      await new Promise((r) => setTimeout(r, waitMs));
      return feedWithRetry(attempt + 1);
    }

    // Not retryable, or out of attempts. Quote the trace id in a bug report:
    console.error(`CivicGate ${e.code} (trace ${e.traceId ?? "none"}): ${e.message}`);
    throw e;
  }
}

A CivicGateError carries code, status (the HTTP status, or null for a transport failure), traceId (the only handle support has on a live failure — quote it) and retryable. normalizeError() is idempotent, so normalising twice is a no-op as an error passes through layers.

Rate limits

Every request is charged to an identity — the key, the authorising user, or the IP — at that identity's tier. The numbers are tabulated once, on the API guide, generated from the same catalog the gateway enforces from. A limit documented in two places is a limit that will eventually disagree with itself, so it is not repeated here.

A worked example

A live "what's happening with this bill" panel, in plain JavaScript, that would actually run in a browser: no credential, no framework, no build step beyond a bundler resolving the import.

import { createClient, createFeedStore, normalizeError, isAborted } from "@cg/sdk";
import { eventIcon } from "@cg/core/feed";   // the LEAF module — see #imports

const el = document.querySelector("#bill-activity");

// A public wall needs no credential at all.
const cg = createClient();
const store = createFeedStore(cg, {
  subject: { type: "bill", id: "hr-22-119" },
  limit: 10,
  refreshMs: 30_000,   // this panel does not need 12s
});

store.subscribe((s) => {
  // A failed refresh keeps the events it already had, so render the list FIRST
  // and treat the error as an annotation — never as "show nothing".
  if (s.loading) { el.textContent = "Loading…"; return; }

  el.innerHTML = "";

  if (s.events.length === 0 && !s.error) {
    el.textContent = "No recorded activity for this bill yet.";
    return;
  }

  const ul = document.createElement("ul");
  for (const e of s.events) {
    const li = document.createElement("li");
    const a = document.createElement("a");
    a.href = new URL(e.url ?? e.subjectUrl ?? "/", "https://www.civicgate.org").href;
    a.textContent = e.title;
    li.append(`${e.eventIcon ?? eventIcon(e.eventType)} `, a);
    li.append(` — ${new Date(e.occurredAt).toLocaleDateString()}`);
    ul.append(li);
  }
  el.append(ul);

  if (s.error) {
    const p = document.createElement("p");
    p.className = "muted";
    p.textContent = `Could not check for updates: ${s.error}`;
    el.append(p);
  }

  if (s.hasMore) {
    const btn = document.createElement("button");
    btn.textContent = "Older";
    btn.disabled = s.refreshing;
    btn.onclick = () => { void store.loadMore(); };
    el.append(btn);
  }
});

store.start();

// Stop polling when the panel goes away.
window.addEventListener("pagehide", () => store.stop());

The same thing signed in, on the server

import { createClient, normalizeError } from "@cg/sdk";

// Node 18+ has fetch; pass one explicitly if yours does not.
const cg = createClient({ apiKey: process.env.CIVICGATE_API_KEY });

try {
  const subs = await cg.subscriptions({ group: "bills" });
  console.log(`Following ${subs.length} bills`);

  const page = await cg.feed({ subjectGroups: ["bills"], limit: 50 });
  console.log(`${page.events.length} updates, served from ${page.source}`);
} catch (raw) {
  const e = normalizeError(raw);
  // FORBIDDEN here almost always means a mutation was attempted with a key.
  console.error(e.code, e.traceId, e.message);
}

Beyond the feed

The SDK ships a few more pieces, each usable on its own:

Reference

• Public API — endpoint, terms, and what the data covers.
• Schema reference — every query, mutation and type, generated from the live schema. The answer to “what can I ask for”.
• API guide — credentials, rate limits, errors on the wire.
• API keys — creating, scoping and revoking.
• Widgets — every embeddable widget and its parameters.

The API is public-domain civic data and stays free to read. If you build something with it, we would like to hear about it — get in touch.