@alchemy.run/axiom 0.0.0 → 2.0.0-beta.84

package/src/Chart.ts

@@ -0,0 +1,156 @@
+/**
+ * Typed view of the Axiom dashboard chart-JSON subset.
+ *
+ * Axiom's `CreateDashboardInput` declares
+ * `dashboard.charts: ReadonlyArray<unknown>` (see
+ * `@distilled.cloud/axiom/.../v2/createDashboard.ts`); these
+ * interfaces give callers compile-time safety when building the
+ * payload by hand.
+ *
+ * `chart.id` is a free-form string the author picks — Axiom
+ * doesn't validate the format. It joins to the matching
+ * `LayoutCell.i` in `dashboard.layout`.
+ */
+
+/**
+ * Axiom-validated chart kinds. Discovered by probing
+ * `POST /v2/dashboards`: anything else returns
+ * `dashboard validation failed at [charts N type]: Invalid input`.
+ */
+export type ChartKind =
+  | "TimeSeries"
+  | "Table"
+  | "Pie"
+  | "Statistic"
+  | "Heatmap"
+  | "LogStream"
+  | "Note"
+  | "SmartFilter";
+
+/**
+ * Minimum chart payload Axiom's `POST /v2/dashboards` accepts.
+ * Any unknown keys (e.g. `dataset`, `description`) trigger
+ * `Unrecognized keys: "<name>"`, so this struct is intentionally
+ * narrow. The dataset is implicit via the APL query.
+ */
+export interface BaseChart {
+  readonly id: string;
+  readonly name: string;
+  readonly type: ChartKind;
+  readonly query: { readonly apl: string };
+}
+
+export interface TimeSeriesChart extends BaseChart {
+  readonly type: "TimeSeries";
+}
+
+export interface TableChart extends BaseChart {
+  readonly type: "Table";
+}
+
+export interface PieChart extends BaseChart {
+  readonly type: "Pie";
+}
+
+export interface StatisticChart extends BaseChart {
+  readonly type: "Statistic";
+}
+
+export interface HeatmapChart extends BaseChart {
+  readonly type: "Heatmap";
+}
+
+export interface LogStreamChart extends BaseChart {
+  readonly type: "LogStream";
+}
+
+/**
+ * A free-form markdown note. Unlike data charts, `Note` has no `query`
+ * or `name` — Axiom's payload is strictly `{ id, type, text, variant? }`.
+ */
+export interface NoteChart {
+  readonly id: string;
+  readonly type: "Note";
+  /** Markdown body rendered in the note cell. */
+  readonly text: string;
+  readonly variant?: "default";
+}
+
+/**
+ * A dashboard filter bar (Axiom calls it `SmartFilter` on the wire,
+ * `Filter bar` in the UI). Holds one or more filters whose IDs can
+ * be referenced from other charts' APL via
+ * `declare query_parameters (<filter-id>:string = "")`.
+ *
+ * Unlike data charts, `SmartFilter` has no top-level `query` field —
+ * each filter inside `filters` may carry its own option-source APL.
+ */
+export interface SmartFilterChart {
+  readonly id: string;
+  readonly type: "SmartFilter";
+  /** Optional display name for the filter bar element. */
+  readonly name?: string;
+  readonly filters: readonly SmartFilter[];
+}
+
+/**
+ * One filter inside a {@link SmartFilterChart}. Either a free-text
+ * `search` filter or a dropdown `select` filter. Select filters draw
+ * their options from either an inline `list` or an APL `query`.
+ */
+export type SmartFilter = SmartFilterSearch | SmartFilterSelect;
+
+export interface SmartFilterSearch {
+  readonly id: string;
+  readonly type: "search";
+  readonly name?: string;
+  readonly active?: boolean;
+}
+
+export interface SmartFilterSelect {
+  readonly id: string;
+  readonly type: "select";
+  readonly name?: string;
+  readonly active?: boolean;
+  /** `"list"` for inline `options`, `"apl"` for a query-driven dropdown. */
+  readonly selectType?: "list" | "apl";
+  /**
+   * APL query that returns rows shaped `{ key, value }`. Axiom shows
+   * `key` in the dropdown and substitutes `value` into chart queries.
+   */
+  readonly apl?: { readonly apl: string };
+  /** Inline key/value options when `selectType === "list"`. */
+  readonly options?: readonly {
+    readonly id?: string;
+    readonly key: string;
+    readonly value: string;
+    readonly default?: boolean;
+  }[];
+}
+
+export type Chart =
+  | TimeSeriesChart
+  | TableChart
+  | PieChart
+  | StatisticChart
+  | HeatmapChart
+  | LogStreamChart
+  | NoteChart
+  | SmartFilterChart;
+
+/**
+ * Mirrors Axiom's `CreateDashboardInput.dashboard.layout` cell schema.
+ * `i` references a chart by its `id`.
+ */
+export interface LayoutCell {
+  readonly i: string;
+  readonly x: number;
+  readonly y: number | null;
+  readonly w: number;
+  readonly h: number;
+  readonly minW?: number;
+  readonly minH?: number;
+  readonly maxW?: number;
+  readonly maxH?: number;
+  readonly static?: boolean;
+}

package/src/Contributions.ts

@@ -0,0 +1,9 @@
+import * as Contributions from "alchemy/Contributions";
+
+export default Contributions.make({
+  name: "axiom",
+  auth: Contributions.lazy(
+    () => import("./AuthProvider.ts"),
+    (module) => module.AxiomAuth,
+  ),
+});

package/src/Credentials.ts

@@ -0,0 +1,68 @@
+import { Credentials } from "@distilled.cloud/axiom/Credentials";
+import { ConfigError } from "@distilled.cloud/core/errors";
+import {
+  deferUntilFirstUse,
+  orDieCredentialsUnavailable,
+  resolveProviderConfig,
+} from "alchemy/Auth/Resolve";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Match from "effect/Match";
+import {
+  AXIOM_AUTH_PROVIDER_NAME,
+  type AxiomAuthConfig,
+  type AxiomResolvedCredentials,
+} from "./AuthProvider.ts";
+
+export {
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_API_BASE_URL,
+} from "@distilled.cloud/axiom/Credentials";
+
+/**
+ * Build a `Credentials` layer that resolves Axiom credentials via the Alchemy
+ * AuthProvider using the configured profile (defaults to "default", overridable
+ * with the current Alchemy profile).
+ */
+export const fromAuthProvider = () =>
+  Layer.effect(
+    Credentials,
+    Effect.gen(function* () {
+      // Defer profile lookup and credential resolution until first use, so
+      // building the provider layers never requires a configured profile.
+      const resolve = yield* resolveProviderConfig<AxiomAuthConfig, AxiomResolvedCredentials>(
+        AXIOM_AUTH_PROVIDER_NAME,
+      ).pipe(
+        Effect.flatMap(({ profileName, resolve }) =>
+          resolve.pipe(
+            Effect.map((creds) =>
+              Match.value(creds).pipe(
+                Match.when({ type: "apiToken" }, (c) => ({
+                  apiKey: c.apiToken,
+                  apiBaseUrl: c.apiBaseUrl,
+                  orgId: c.orgId,
+                })),
+                Match.when({ type: "pat" }, (c) => ({
+                  apiKey: c.apiToken,
+                  apiBaseUrl: c.apiBaseUrl,
+                  orgId: c.orgId,
+                })),
+                Match.exhaustive,
+              ),
+            ),
+            Effect.mapError((e) =>
+              ConfigError.make({
+                message: `Failed to resolve Axiom credentials from ${profileName === undefined ? "the CI environment" : `profile '${profileName}'`}: ${(e as { message?: string }).message ?? String(e)}`,
+              }),
+            ),
+          ),
+        ),
+        deferUntilFirstUse,
+      );
+      return yield* resolve.pipe(
+        orDieCredentialsUnavailable(AXIOM_AUTH_PROVIDER_NAME),
+        Effect.cached,
+      );
+    }),
+  );

package/src/Dashboard.ts

@@ -0,0 +1,192 @@
+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.succeed(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.succeed(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))),
+      };
+    }),
+  );