Admin

@spoar/sdk/admin is for server code, scripts and CI. It calls the API with a token; never ship it to a browser. It is a thin layer over @spoar/client, which covers every read route as a chainable scope; new code should use that package directly.

import { createAdmin, discord, mail, webhook } from "@spoar/sdk/admin";

type Projects = "remcostoeten.nl" | "skriuw";

const admin = createAdmin<Projects>({
  endpoint: "https://api.analytics.remcostoeten.nl",
  token: process.env.RA_ADMIN_TOKEN,
});

function isHttps(url: string | undefined): url is `https://${string}` {
  return url?.startsWith("https://") ?? false;
}

const discordUrl = process.env.DISCORD_WEBHOOK_URL;
if (!isHttps(discordUrl)) throw new Error("Set DISCORD_WEBHOOK_URL to the Discord webhook URL");

const synced = await admin.alerts.sync("remcostoeten.nl", [
  mail({ to: ["remco@gmail.com"] }),
  discord({ url: discordUrl, on: ["issue.regression"] }),
  webhook({ name: "ops", url: "https://ops.example.com/hooks/analytics" }),
]);

if (!synced.ok) console.error(synced.error.code, synced.error.message);
else console.log(synced.value.secrets.ops);

Every method answers { ok: true, value } or { ok: false, error } and never throws. error.code is a code from the error catalog, or NO_TOKEN, NETWORK, TIMEOUT, ABORTED, BAD_URL or BAD_RESPONSE when the request did not get an answer from the API.

Alert targetsCopy Anchor Link

A target is where one project's alerts go on one channel. The builders fill one in:

name defaults to the channel, so one target per channel needs no name. on defaults to every issue event (issue.new and issue.regression) and enabled to true. speed.drop is opt-in: list it in on to hear when yesterday's Real Experience Score fell 10 points or more, to under 90, against the 7 days before.

secrets holds the signing secret of each new webhook target. It is shown only in the answer to sync, set and rotate; store it where your receiver reads it, such as RA_WEBHOOK_SECRET.

What the editor catchesCopy Anchor Link

AnnotationsCopy Anchor Link

Annotations are dated labels on a project's time series, such as a release, a post, a content update or an incident. Annotations describes the data model.

const release = await admin.annotations.create("remcostoeten.nl", {
  title: "v2.0 released",
  date: new Date(),
  kind: "release",
  url: "https://github.com/remcostoeten/analytics/releases/tag/v2.0.0",
});

await admin.annotations.create("skriuw", {
  title: "Posted on Hacker News",
  date: "2026-10-03",
  endDate: "2026-10-05",
  kind: "post",
});

if (release.ok) {
  await admin.annotations.update("remcostoeten.nl", release.value.id, {
    note: "New onboarding flow",
  });
}

const september = await admin.annotations.list("remcostoeten.nl", {
  from: "2026-09-01T00:00:00Z",
  to: "2026-10-01T00:00:00Z",
});
if (september.ok) console.table(september.value.data);

Dates are a Date, a calendar date such as "2026-10-01" (the start of that day in UTC) or an ISO 8601 timestamp. list works with a read token; the other methods need an admin token that lists the project.

ReadsCopy Anchor Link

The same client reads the stats routes, typed from the contract, for your own dashboard pages and server components:

filter: { country: "NL" } is sent as filter[country]=NL.