alchemy 2.0.0-beta.18 → 2.0.0-beta.19

package/src/Axiom/Annotation.ts

@@ -0,0 +1,95 @@
+import * as Operations from "@distilled.cloud/axiom/Operations";
+import * as Effect from "effect/Effect";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import type { Providers } from "./Providers.ts";
+
+export type AnnotationProps = Operations.CreateAnnotationInput;
+
+export type Annotation = Resource<
+  "Axiom.Annotation",
+  AnnotationProps,
+  Operations.CreateAnnotationOutput,
+  never,
+  Providers
+>;
+
+/**
+ * An Axiom annotation — a vertical marker overlaid on charts to flag a
+ * deploy, incident, feature flag flip, or any other point/range event you
+ * want correlated with telemetry.
+ *
+ * Annotations are scoped to one or more `datasets`. Use a single `time` for
+ * a point marker or `time` + `endTime` for a range. The `type` (e.g.
+ * `"deploy"`, `"incident"`) groups markers visually in the UI.
+ *
+ * Although typically created at deploy/release time (out-of-band of
+ * regular IaC), modelling them as resources makes per-environment
+ * annotation history reproducible.
+ *
+ * @see https://axiom.co/docs/query-data/annotate-charts
+ *
+ * @section Creating an Annotation
+ * @example Point-in-time deploy marker
+ * ```typescript
+ * yield* Axiom.Annotation("deploy-1.2.3", {
+ *   type: "deploy",
+ *   title: "Release 1.2.3",
+ *   description: "https://github.com/acme/app/releases/tag/v1.2.3",
+ *   datasets: ["my-app-traces", "my-app-logs"],
+ *   time: new Date().toISOString(),
+ *   url: "https://github.com/acme/app/releases/tag/v1.2.3",
+ * });
+ * ```
+ *
+ * @example Incident time-range
+ * ```typescript
+ * yield* Axiom.Annotation("inc-2026-04-27", {
+ *   type: "incident",
+ *   title: "Database failover",
+ *   datasets: ["my-app-traces"],
+ *   time:    "2026-04-27T18:05:00Z",
+ *   endTime: "2026-04-27T18:32:00Z",
+ *   url: "https://incident.io/incidents/abc123",
+ * });
+ * ```
+ */
+export const Annotation = Resource<Annotation>("Axiom.Annotation");
+
+export const AnnotationProvider = () =>
+  Provider.effect(
+    Annotation,
+    Effect.gen(function* () {
+      const create = yield* Operations.createAnnotation;
+      const update = yield* Operations.updateAnnotation;
+      const get = yield* Operations.getAnnotation;
+      const del = yield* Operations.deleteAnnotation;
+
+      return {
+        stables: ["id"],
+        create: Effect.fn(function* ({ news }) {
+          return yield* create(news);
+        }),
+        update: Effect.fn(function* ({ news, output }) {
+          const result = yield* update({ ...news, id: output.id });
+          return { ...result, id: output.id, time: result.time ?? output.time };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* del({ id: output.id }).pipe(
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.id) return undefined;
+          return yield* get({ id: output.id }).pipe(
+            Effect.map((current) => ({
+              ...current,
+              id: current.id ?? output.id,
+              time: current.time ?? output.time,
+            })),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+      };
+    }),
+  );

package/src/Axiom/ApiToken.ts

@@ -0,0 +1,125 @@
+import * as Operations from "@distilled.cloud/axiom/Operations";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { deepEqual, isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import type { Providers } from "./Providers.ts";
+
+export type ApiTokenProps = Omit<Operations.CreateAPITokenInput, never>;
+
+export type ApiToken = Resource<
+  "Axiom.ApiToken",
+  ApiTokenProps,
+  Omit<Operations.CreateAPITokenOutput, "token"> & {
+    /**
+     * The bearer token. Returned only by `create` (and `regenerate`); Axiom
+     * does not return it on subsequent reads. Persisted in resource state via
+     * `Redacted` — handle with care.
+     */
+    token: Redacted.Redacted<string>;
+  },
+  never,
+  Providers
+>;
+
+/**
+ * An Axiom API token — a scoped bearer token used to authenticate API
+ * requests (ingest, query, admin). Capabilities are pinned at creation time;
+ * changing any field triggers a **replacement** because Axiom does not
+ * expose an update endpoint.
+ *
+ * The raw token value is returned only by `create`. After that, Axiom
+ * never echoes it back, so it is captured into `output.token` (as a
+ * {@link Redacted}) on initial create and persisted in resource state.
+ * Treat resource state as sensitive — anyone with read access can recover
+ * the token. Pair with a secret store for downstream consumption.
+ *
+ * @see https://axiom.co/docs/reference/tokens
+ *
+ * @section Creating an API Token
+ * @example Ingest-only token scoped to one dataset
+ * ```typescript
+ * const ingest = yield* Axiom.ApiToken("ingest", {
+ *   name: "prod-ingest",
+ *   description: "OTEL collector ingest",
+ *   datasetCapabilities: {
+ *     "my-app-traces": { ingest: ["create"] },
+ *   },
+ * });
+ * ```
+ *
+ * @example Read-only query token
+ * ```typescript
+ * yield* Axiom.ApiToken("query", {
+ *   name: "grafana-reader",
+ *   datasetCapabilities: {
+ *     "my-app-traces": { query: ["read"] },
+ *     "my-app-logs":   { query: ["read"] },
+ *   },
+ * });
+ * ```
+ *
+ * @section Consuming the Token
+ * @example Forward the token via Cloudflare Secrets
+ * ```typescript
+ * const secret = yield* Cloudflare.Secret("axiom-token", {
+ *   value: ingest.token,
+ * });
+ * ```
+ */
+export const ApiToken = Resource<ApiToken>("Axiom.ApiToken");
+
+export const ApiTokenProvider = () =>
+  Provider.effect(
+    ApiToken,
+    Effect.gen(function* () {
+      const create = yield* Operations.createAPIToken;
+      const get = yield* Operations.getAPIToken;
+      const del = yield* Operations.deleteAPIToken;
+
+      return {
+        stables: ["id", "token"],
+        diff: Effect.fn(function* ({ olds, news, output }) {
+          if (!isResolved(news)) return undefined;
+          // First create — let the engine create normally.
+          if (output == null) return undefined;
+          // Axiom has no update endpoint for tokens, so any actual change
+          // to the inputs forces a replacement (which mints a new bearer
+          // value). If nothing changed, fall through to `noop` so we don't
+          // needlessly rotate the token on every deploy.
+          if (deepEqual(olds, news)) return undefined;
+          return { action: "replace" } as const;
+        }),
+        create: Effect.fn(function* ({ news }) {
+          const result = yield* create(news);
+          if (!result.token) {
+            return yield* Effect.die(
+              new Error("Axiom did not return a token on create"),
+            );
+          }
+          return {
+            ...result,
+            token: Redacted.make(result.token),
+          };
+        }),
+        update: Effect.fn(function* ({ output }) {
+          // Diff returns "replace" for every change, so update should never
+          // run. If invoked, just return current state unchanged.
+          return output;
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* del({ id: output.id }).pipe(
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.id) return undefined;
+          return yield* get({ id: output.id }).pipe(
+            Effect.map((current) => ({ ...current, token: output.token })),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+      };
+    }),
+  );

package/src/Axiom/AuthProvider.ts

@@ -0,0 +1,341 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Match from "effect/Match";
+import * as Redacted from "effect/Redacted";
+import {
+  AuthError,
+  AuthProviderLayer,
+  type ConfigureContext,
+} from "../Auth/AuthProvider.ts";
+import {
+  deleteCredentials,
+  displayRedacted,
+  readCredentials,
+  writeCredentials,
+} from "../Auth/Credentials.ts";
+import { getEnv, getEnvRedacted, retryOnce } from "../Auth/Env.ts";
+import * as Clank from "../Util/Clank.ts";
+import { DEFAULT_API_BASE_URL } from "@distilled.cloud/axiom/Credentials";
+
+const STORAGE_KEY = "axiom-stored";
+
+const options: Array<{
+  value: AxiomAuthConfig["method"];
+  label: string;
+  hint?: string;
+}> = [
+  {
+    value: "env",
+    label: "Environment Variables",
+    hint: "AXIOM_TOKEN (or AXIOM_API_KEY) + optional AXIOM_ORG_ID, AXIOM_URL",
+  },
+  {
+    value: "stored",
+    label: "API Token or Personal Access Token",
+    hint: "enter credentials interactively, stored in ~/.alchemy/credentials",
+  },
+];
+
+export type AxiomAuthConfig =
+  | { method: "env" }
+  | { method: "stored"; credentialType: "apiToken" }
+  | { method: "stored"; credentialType: "pat" };
+
+export type AxiomStoredCredentials =
+  | { type: "apiToken"; apiToken: string; apiBaseUrl?: string; orgId?: string }
+  | { type: "pat"; apiToken: string; apiBaseUrl?: string; orgId: string };
+
+export type AxiomResolvedCredentials =
+  | {
+      type: "apiToken";
+      apiToken: Redacted.Redacted<string>;
+      apiBaseUrl: string;
+      orgId?: string;
+      source: { type: AxiomAuthConfig["method"]; details?: string };
+    }
+  | {
+      type: "pat";
+      apiToken: Redacted.Redacted<string>;
+      apiBaseUrl: string;
+      orgId: string;
+      source: { type: AxiomAuthConfig["method"]; details?: string };
+    };
+
+export const AXIOM_AUTH_PROVIDER_NAME = "Axiom";
+
+/**
+ * Layer that registers the Axiom {@link AuthProvider} into the
+ * {@link AuthProviders} registry when built. Include this in the Axiom
+ * `providers()` layer so `alchemy login` can discover it.
+ */
+export const AxiomAuth = AuthProviderLayer<
+  AxiomAuthConfig,
+  AxiomResolvedCredentials
+>()(AXIOM_AUTH_PROVIDER_NAME, {
+  configure: (profileName, ctx) => configureCredentials(profileName, ctx),
+  logout: (profileName, config) => logout(profileName, config),
+  login: (profileName, config) => login(profileName, config),
+  prettyPrint: (profileName, config) => prettyPrint(profileName, config),
+  read: (profileName, config) => resolveCredentials(profileName, config),
+});
+
+const resolveCredentials = (
+  profileName: string,
+  config: AxiomAuthConfig,
+): Effect.Effect<
+  AxiomResolvedCredentials,
+  AuthError,
+  FileSystem.FileSystem
+> =>
+  Match.value(config).pipe(
+    Match.when(
+      { method: "env" },
+      Effect.fnUntraced(function* () {
+        const apiToken =
+          (yield* getEnvRedacted("AXIOM_TOKEN")) ??
+          (yield* getEnvRedacted("AXIOM_API_KEY"));
+        if (!apiToken) {
+          return yield* new AuthError({
+            message:
+              "Axiom env credentials not found. Set AXIOM_TOKEN (or AXIOM_API_KEY).",
+          });
+        }
+        const apiBaseUrl =
+          (yield* getEnv("AXIOM_URL")) ?? DEFAULT_API_BASE_URL;
+        const orgId = yield* getEnv("AXIOM_ORG_ID");
+        if (orgId) {
+          return {
+            type: "pat" as const,
+            apiToken,
+            apiBaseUrl,
+            orgId,
+            source: { type: "env" as const },
+          };
+        }
+        return {
+          type: "apiToken" as const,
+          apiToken,
+          apiBaseUrl,
+          source: { type: "env" as const },
+        };
+      }),
+    ),
+    Match.when({ method: "stored" }, () =>
+      readCredentials<AxiomStoredCredentials>(profileName, STORAGE_KEY).pipe(
+        Effect.flatMap((creds) =>
+          creds == null
+            ? Effect.fail(
+                new AuthError({
+                  message:
+                    "Axiom stored credentials not found. Run: alchemy login --configure",
+                }),
+              )
+            : Effect.succeed(
+                Match.value(creds).pipe(
+                  Match.when({ type: "apiToken" }, (c) => ({
+                    type: "apiToken" as const,
+                    apiToken: Redacted.make(c.apiToken),
+                    apiBaseUrl: c.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+                    orgId: c.orgId,
+                    source: { type: "stored" as const },
+                  })),
+                  Match.when({ type: "pat" }, (c) => ({
+                    type: "pat" as const,
+                    apiToken: Redacted.make(c.apiToken),
+                    apiBaseUrl: c.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+                    orgId: c.orgId,
+                    source: { type: "stored" as const },
+                  })),
+                  Match.exhaustive,
+                ),
+              ),
+        ),
+      ),
+    ),
+    Match.exhaustive,
+  );
+
+const logout = (profileName: string, config: AxiomAuthConfig) =>
+  Match.value(config).pipe(
+    Match.when({ method: "env" }, () => Effect.void),
+    Match.when({ method: "stored" }, () =>
+      deleteCredentials(profileName, STORAGE_KEY).pipe(
+        Effect.andThen(Clank.success("Axiom: stored credentials removed")),
+      ),
+    ),
+    Match.exhaustive,
+  );
+
+const login = (profileName: string, config: AxiomAuthConfig) =>
+  Match.value(config)
+    .pipe(
+      Match.when({ method: "env" }, () => Effect.void),
+      Match.when({ method: "stored" }, () =>
+        readCredentials<AxiomStoredCredentials>(profileName, STORAGE_KEY).pipe(
+          Effect.flatMap((creds) =>
+            creds == null ? loginStored(profileName) : Effect.void,
+          ),
+        ),
+      ),
+      Match.exhaustive,
+    )
+    .pipe(
+      Effect.mapError(
+        (e) => new AuthError({ message: "login failed", cause: e }),
+      ),
+    );
+
+const configureCredentials = (profileName: string, ctx: ConfigureContext) =>
+  Effect.gen(function* () {
+    if (ctx.ci) {
+      return { method: "env" as const };
+    }
+    return yield* configureInteractive(profileName);
+  }).pipe(
+    Effect.mapError(
+      (e) =>
+        new AuthError({
+          message: "failed to configure credentials",
+          cause: e,
+        }),
+    ),
+  );
+
+const configureInteractive = (profileName: string) =>
+  Clank.select({
+    message: "Axiom authentication method",
+    options,
+  }).pipe(
+    Effect.flatMap((method) =>
+      Match.value(method).pipe(
+        Match.when("env", () => Effect.succeed({ method: "env" as const })),
+        Match.when("stored", () => loginStored(profileName)),
+        Match.exhaustive,
+      ),
+    ),
+  );
+
+const loginStored = Effect.fnUntraced(function* (profileName: string) {
+  const credentialType = yield* Clank.select({
+    message: "Axiom credential type",
+    options: [
+      {
+        value: "apiToken" as const,
+        label: "API Token",
+        hint: "recommended — scoped to specific datasets/actions",
+      },
+      {
+        value: "pat" as const,
+        label: "Personal Access Token",
+        hint: "full account control, requires Org ID",
+      },
+    ],
+  }).pipe(retryOnce);
+
+  const apiBaseUrlPrompt = yield* Clank.text({
+    message: "Axiom API Base URL (Enter for default)",
+    placeholder: DEFAULT_API_BASE_URL,
+    defaultValue: DEFAULT_API_BASE_URL,
+  }).pipe(retryOnce);
+  const apiBaseUrl =
+    apiBaseUrlPrompt && apiBaseUrlPrompt.length > 0
+      ? apiBaseUrlPrompt
+      : undefined;
+
+  return yield* Match.value(credentialType).pipe(
+    Match.when("apiToken", () =>
+      Effect.gen(function* () {
+        const apiToken = yield* Clank.password({
+          message: "Axiom API Token",
+          validate: (v) => (v.length === 0 ? "Required" : undefined),
+        }).pipe(retryOnce);
+        const orgId = yield* promptOrgId(false);
+
+        yield* writeCredentials<AxiomStoredCredentials>(
+          profileName,
+          STORAGE_KEY,
+          {
+            type: "apiToken",
+            apiToken,
+            apiBaseUrl,
+            orgId: orgId && orgId.length > 0 ? orgId : undefined,
+          },
+        );
+        yield* Clank.success("Axiom: credentials saved.");
+        return {
+          method: "stored" as const,
+          credentialType: "apiToken" as const,
+        };
+      }),
+    ),
+    Match.when("pat", () =>
+      Effect.gen(function* () {
+        const apiToken = yield* Clank.password({
+          message: "Axiom Personal Access Token",
+          validate: (v) => (v.length === 0 ? "Required" : undefined),
+        }).pipe(retryOnce);
+        const orgId = yield* promptOrgId(true);
+
+        yield* writeCredentials<AxiomStoredCredentials>(
+          profileName,
+          STORAGE_KEY,
+          { type: "pat", apiToken, apiBaseUrl, orgId },
+        );
+        yield* Clank.success("Axiom: credentials saved.");
+        return {
+          method: "stored" as const,
+          credentialType: "pat" as const,
+        };
+      }),
+    ),
+    Match.exhaustive,
+  );
+});
+
+const promptOrgId = (required: boolean) =>
+  getEnv("AXIOM_ORG_ID").pipe(
+    Effect.flatMap((envOrgId) =>
+      Clank.text({
+        message: required
+          ? "Axiom Org ID (required for PAT)"
+          : "Axiom Org ID (Enter to skip)",
+        placeholder: envOrgId ?? "",
+        defaultValue: envOrgId ?? "",
+        validate: required
+          ? (v) => (v.length === 0 ? "Required" : undefined)
+          : undefined,
+      }).pipe(retryOnce),
+    ),
+  );
+
+const prettyPrint = (profileName: string, config: AxiomAuthConfig) =>
+  resolveCredentials(profileName, config).pipe(
+    Effect.tap((creds) => {
+      const sourceStr = creds.source.details
+        ? `${creds.source.type} - ${creds.source.details}`
+        : creds.source.type;
+      return Match.value(creds).pipe(
+        Match.when({ type: "apiToken" }, (c) =>
+          Effect.all([
+            Console.log(`  apiToken: ${displayRedacted(c.apiToken, 9)}`),
+            Console.log(`  apiBaseUrl: ${c.apiBaseUrl}`),
+            Console.log(`  orgId: ${c.orgId ?? "(none)"}`),
+            Console.log(`  source: ${sourceStr}`),
+          ]),
+        ),
+        Match.when({ type: "pat" }, (c) =>
+          Effect.all([
+            Console.log(`  apiToken: ${displayRedacted(c.apiToken, 9)}`),
+            Console.log(`  apiBaseUrl: ${c.apiBaseUrl}`),
+            Console.log(`  orgId: ${c.orgId}`),
+            Console.log(`  source: ${sourceStr}`),
+          ]),
+        ),
+        Match.exhaustive,
+      );
+    }),
+    Effect.catch((e) =>
+      Console.error(`  Failed to retrieve credentials: ${e}`),
+    ),
+  );

package/src/Axiom/Chart.ts

@@ -0,0 +1,94 @@
+/**
+ * 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";
+
+/**
+ * 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";
+}
+
+export interface NoteChart extends BaseChart {
+  readonly type: "Note";
+}
+
+export type Chart =
+  | TimeSeriesChart
+  | TableChart
+  | PieChart
+  | StatisticChart
+  | HeatmapChart
+  | LogStreamChart
+  | NoteChart;
+
+/**
+ * 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;
+}