import * as Axiom from "@distilled.cloud/axiom";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import type { Providers } from "./Providers.ts";
/** Dashboard input. */
export type DashboardProps = Axiom.CreateDashboardRequest;
export type Dashboard = Resource<
"Axiom.Dashboard",
DashboardProps,
{
/** Stable Axiom dashboard `uid` (used as the path identifier). */
uid: string;
id: string;
createdAt: string;
createdBy: string;
updatedAt: string;
updatedBy: string;
/** The full dashboard document as returned by Axiom. */
dashboard: Axiom.DashboardWriteResponse["dashboard"]["dashboard"];
},
never,
Providers
>;
/**
* An Axiom dashboard — a named, layout-driven collection of charts. Each
* dashboard takes a full document (`charts` + `layout` array of grid cells +
* `timeWindow` + `refreshTime`) at version `schemaVersion: 2`.
*
* Charts are typed via {@link Chart} (a discriminated union over the
* Axiom-validated chart kinds — `TimeSeries`, `Table`, `Pie`, `Statistic`,
* `Heatmap`, `LogStream`, `Note`). The `id` on each chart is a free-form
* string the author picks; layout cells join via `LayoutCell.i`.
*
* The path identifier is `uid` (auto-assigned by Axiom). `id` is also
* exposed as an output but the API uses `uid` everywhere.
*
* Notes from probing `POST /v2/dashboards`:
*
* - Relative time windows must use the `qr-now-{duration}` form (e.g.
* `"qr-now-7d"` / `"qr-now"`); plain `"now-7d"` is rejected.
* - When authenticating with an API token, `dashboard.owner` must be `""`
* (Axiom rewrites this to the org-shared `X-AXIOM-EVERYONE`); per-user
* "private" dashboards aren't allowed for tokens.
* - The chart payload is strict: only `id`, `name`, `type`, `query`. Extra
* keys (e.g. `dataset`, `description`) trigger
* `Unrecognized keys: "<name>"`.
* @see https://axiom.co/docs/query-data/dashboards
*
* ### Creating a Dashboard
* **Example:** Minimal empty dashboard
* ```typescript
* yield* Axiom.Dashboard("ops", {
* dashboard: {
* name: "Ops Overview",
* owner: "", // org-shared (required for API tokens)
* description: "Top-level service health",
* charts: [],
* layout: [],
* refreshTime: 60, // seconds: 15 | 60 | 300
* schemaVersion: 2,
* timeWindowStart: "qr-now-1h",
* timeWindowEnd: "qr-now",
* },
* });
* ```
*
* **Example:** One-chart dashboard
* ```typescript
* import type { Chart, LayoutCell } from "@alchemy.run/axiom";
*
* const errors: Chart = {
* id: "errors-5m",
* name: "5xx errors / 5m",
* type: "TimeSeries",
* query: {
* apl: `['my-app-traces']
* | where status >= 500
* | summarize count() by bin_auto(_time)`,
* },
* };
*
* yield* Axiom.Dashboard("errors", {
* dashboard: {
* name: "Errors",
* owner: "",
* refreshTime: 60,
* schemaVersion: 2,
* timeWindowStart: "qr-now-24h",
* timeWindowEnd: "qr-now",
* charts: [errors],
* layout: [{ i: errors.id, x: 0, y: 0, w: 12, h: 6 } satisfies LayoutCell],
* },
* });
* ```
*
* **Example:** Compare to last 24h
* ```typescript
* yield* Axiom.Dashboard("compare", {
* dashboard: {
* name: "Compare vs yesterday",
* owner: "",
* refreshTime: 300,
* schemaVersion: 2,
* timeWindowStart: "qr-now-1h",
* timeWindowEnd: "qr-now",
* against: "-1d", // overlay the same window from 24h ago
* charts: [],
* layout: [],
* },
* });
* ```
*
* @resource
* @product Dashboard
*/
export const Dashboard = Resource<Dashboard>("Axiom.Dashboard");
export const DashboardProvider = () =>
Provider.effect(
Dashboard,
Effect.gen(function* () {
const create = yield* Axiom.createDashboard;
const update = yield* Axiom.updateDashboard;
const get = yield* Axiom.getDashboard;
const del = yield* Axiom.deleteDashboard;
const listAll = yield* Axiom.listDashboards;
const toAttrsFromCreate = (envelope: Axiom.DashboardWriteResponse) => ({
uid: envelope.dashboard.uid,
id: envelope.dashboard.id,
createdAt: envelope.dashboard.createdAt,
createdBy: envelope.dashboard.createdBy,
updatedAt: envelope.dashboard.updatedAt,
updatedBy: envelope.dashboard.updatedBy,
dashboard: envelope.dashboard.dashboard,
});
const toAttrsFromGet = (current: Axiom.DashboardResource) => ({
uid: current.uid,
id: current.id,
createdAt: current.createdAt,
createdBy: current.createdBy,
updatedAt: current.updatedAt,
updatedBy: current.updatedBy,
dashboard: current.dashboard,
});
return {
stables: ["uid", "id", "createdAt", "createdBy"],
reconcile: Effect.fn(function* ({ news, output }) {
// Observe — `uid` is server-assigned at create time. We probe
// Axiom for the dashboard via the cached uid; treat NotFound
// (deleted out-of-band) as "no observed state" so we converge
// by re-creating.
const observed = output?.uid
? yield* get({ uid: output.uid }).pipe(
Effect.catchTag("NotFound", () => Effect.undefined),
)
: undefined;
// Ensure — POST mints a new dashboard with a fresh uid.
if (observed === undefined) {
return toAttrsFromCreate(yield* create(news));
}
// Sync — `overwrite: true` short-circuits Axiom's optimistic-
// concurrency check (otherwise the API requires the caller to
// echo back the server-side `version`, which we don't track).
return toAttrsFromCreate(yield* update({ ...news, uid: observed.uid, overwrite: true }));
}),
delete: Effect.fn(function* ({ output }) {
yield* del({ uid: output.uid }).pipe(Effect.catchTag("NotFound", () => Effect.void));
}),
read: Effect.fn(function* ({ output }) {
if (!output?.uid) return undefined;
return yield* get({ uid: output.uid }).pipe(
Effect.map(toAttrsFromGet),
Effect.catchTag("NotFound", () => Effect.undefined),
);
}),
// Enumerate every dashboard visible to the caller. `GET /v2/dashboards`
// returns the full collection in one response (no pagination wrapper);
// each item carries the same shape as `getDashboard`, so we map through
// the shared `toAttrsFromGet` hydrator to produce the exact `read`
// Attributes shape.
list: () => listAll({}).pipe(Effect.map((dashboards) => dashboards.map(toAttrsFromGet))),
};
}),
);