sailfork / t3code-github / .repos/ alchemy-effect/ packages/ axiom/ src/ Annotation.ts

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";

export type AnnotationProps = Axiom.CreateAnnotationRequest;

export type Annotation = Resource<
  "Axiom.Annotation",
  AnnotationProps,
  Axiom.Annotation,
  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
 *
 * ### 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",
 * });
 * ```
 *
 * @resource
 * @product Dataset
 */
export const Annotation = Resource<Annotation>("Axiom.Annotation");

export const AnnotationProvider = () =>
  Provider.effect(
    Annotation,
    Effect.gen(function* () {
      const create = yield* Axiom.createAnnotation;
      const update = yield* Axiom.updateAnnotation;
      const get = yield* Axiom.getAnnotation;
      const del = yield* Axiom.deleteAnnotation;
      const listAnnotations = yield* Axiom.getAnnotations;

      return {
        stables: ["id"],
        // Axiom exposes a flat, account-wide `GET /v2/annotations` list that
        // returns every annotation's full record in one (non-paginated)
        // response — the exact same shape `get`/`read` produce. Hand each
        // record back directly as the resource's Attributes.
        list: () =>
          listAnnotations({}).pipe(Effect.map((annotations) => annotations.map((a) => ({ ...a })))),
        reconcile: Effect.fn(function* ({ news, output }) {
          // Observe — Axiom assigns the annotation id server-side, so the
          // only handle to a previously-created annotation is the cached
          // `output.id`. Probe for live state with that id; treat NotFound
          // (deleted out-of-band, or never created) as "no observed state".
          const observed = output?.id
            ? yield* get({ id: output.id }).pipe(
                Effect.catchTag("NotFound", () => Effect.undefined),
              )
            : undefined;

          // Ensure — when no observed annotation exists, POST creates one
          // and Axiom assigns the id.
          if (observed === undefined) {
            return yield* create(news);
          }

          // Sync — the annotation exists; apply desired props with PUT and
          // preserve the stable id and original time as fallbacks.
          const result = yield* update({ ...news, id: observed.id! });
          return {
            ...result,
            id: observed.id!,
            time: result.time ?? output?.time ?? news.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.undefined),
          );
        }),
      };
    }),
  );