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

package/src/Credentials.ts

@@ -1,18 +1,8 @@
 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 { lazyCredentials } from "alchemy/Auth/Resolve";
 import * as Layer from "effect/Layer";
-import * as Match from "effect/Match";
-import {
-  AXIOM_AUTH_PROVIDER_NAME,
-  type AxiomAuthConfig,
-  type AxiomResolvedCredentials,
-} from "./AuthProvider.ts";
+import { AXIOM_AUTH_PROVIDER_NAME, type AxiomResolvedCredentials } from "./AuthProvider.ts";
 
 export {
   Credentials,
@@ -28,41 +18,9 @@ export {
 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,
-      );
-    }),
+    lazyCredentials<AxiomResolvedCredentials, ConfigError>()(AXIOM_AUTH_PROVIDER_NAME, (creds) => ({
+      apiKey: creds.apiToken,
+      apiBaseUrl: creds.apiBaseUrl,
+      orgId: creds.orgId,
+    })),
   );

package/src/Dashboard.ts

@@ -14,17 +14,28 @@ export type Dashboard = Resource<
     /** Stable Axiom dashboard `uid` (used as the path identifier). */
     uid: string;
     id: string;
-    createdAt: string;
-    createdBy: string;
-    updatedAt: string;
-    updatedBy: string;
+    /** Axiom omits the audit fields on some dashboards. */
+    createdAt: string | undefined;
+    createdBy: string | undefined;
+    updatedAt: string | undefined;
+    updatedBy: string | undefined;
     /** The full dashboard document as returned by Axiom. */
     dashboard: Axiom.DashboardWriteResponse["dashboard"]["dashboard"];
   },
   never,
-  Providers
+  Providers,
+  DashboardLookup
 >;
 
+/**
+ * Props for {@link Dashboard.lookup}: find a dashboard this stack
+ * doesn't manage by its id.
+ */
+export interface DashboardLookup {
+  /** Axiom dashboard id. */
+  uid: string;
+}
+
 /**
  * An Axiom dashboard — a named, layout-driven collection of charts. Each
  * dashboard takes a full document (`charts` + `layout` array of grid cells +
@@ -114,6 +125,16 @@ export type Dashboard = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing dashboard
+ * `Dashboard.lookup` references a dashboard Alchemy doesn't manage (created in
+ * the Axiom console or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Reference an existing dashboard
+ * ```typescript
+ * const ref = Axiom.Dashboard.lookup({ uid: "abc123" });
+ * ```
+ *
  * @resource
  * @product Dashboard
  */
@@ -132,19 +153,19 @@ export const DashboardProvider = () =>
       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,
+        createdAt: envelope.dashboard.createdAt ?? undefined,
+        createdBy: envelope.dashboard.createdBy ?? undefined,
+        updatedAt: envelope.dashboard.updatedAt ?? undefined,
+        updatedBy: envelope.dashboard.updatedBy ?? undefined,
         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,
+        createdAt: current.createdAt ?? undefined,
+        createdBy: current.createdBy ?? undefined,
+        updatedAt: current.updatedAt ?? undefined,
+        updatedBy: current.updatedBy ?? undefined,
         dashboard: current.dashboard,
       });
 
@@ -157,7 +178,7 @@ export const DashboardProvider = () =>
           // by re-creating.
           const observed = output?.uid
             ? yield* get({ uid: output.uid }).pipe(
-                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+                Effect.catchTag("NotFound", () => Effect.undefined),
               )
             : undefined;
 
@@ -174,11 +195,18 @@ export const DashboardProvider = () =>
         delete: Effect.fn(function* ({ output }) {
           yield* del({ uid: output.uid }).pipe(Effect.catchTag("NotFound", () => Effect.void));
         }),
+        lookup: Effect.fn(function* ({ uid }) {
+          return yield* get({ uid }).pipe(
+            Effect.map(toAttrsFromGet),
+            Effect.catchTag("NotFound", () => Effect.undefined),
+          );
+        }),
+
         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)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
         }),
         // Enumerate every dashboard visible to the caller. `GET /v2/dashboards`

package/src/Dataset.ts

@@ -6,10 +6,16 @@ import * as Provider from "alchemy/Provider";
 import { Resource } from "alchemy/Resource";
 import { Stack } from "alchemy/Stack";
 import { Stage } from "alchemy/Stage";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import { otelDatasetHeader } from "./OtelHeaders.ts";
 import type { Providers } from "./Providers.ts";
 
+export class DatasetUnexpectedResponse extends Data.TaggedError("DatasetUnexpectedResponse")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
 export type DatasetKind =
   | "otel:metrics:v1"
   | "otel:traces:v1"
@@ -82,9 +88,19 @@ export type Dataset = Resource<
     otelHeaders: Record<string, string>;
   },
   never,
-  Providers
+  Providers,
+  DatasetLookup
 >;
 
+/**
+ * Props for {@link Dataset.lookup}: find a dataset this stack
+ * doesn't manage by its name.
+ */
+export interface DatasetLookup {
+  /** Dataset name. */
+  name: string;
+}
+
 /**
  * An Axiom dataset — the top-level container that stores events, logs,
  * traces, or metrics. Pick a `kind` up-front: it determines schema and how
@@ -132,6 +148,16 @@ export type Dataset = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing dataset
+ * `Dataset.lookup` references a dataset Alchemy doesn't manage (created in
+ * the Axiom console or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Ingest into an existing dataset
+ * ```typescript
+ * const logs = Axiom.Dataset.lookup({ name: "logs" });
+ * ```
+ *
  * @resource
  * @product Dataset
  */
@@ -169,7 +195,7 @@ export const DatasetProvider = () =>
   Provider.effect(
     Dataset,
     Effect.gen(function* () {
-      const { apiBaseUrl } = yield* yield* Credentials;
+      const credentials = yield* Credentials;
       const create = yield* Axiom.createDataset;
       const update = yield* Axiom.updateDataset;
       const get = yield* Axiom.getDataset;
@@ -178,10 +204,11 @@ export const DatasetProvider = () =>
 
       const toAttrs = Effect.fn(function* (dataset: Axiom.Dataset) {
         if (!dataset.edgeDeployment || !dataset.edgeDeploymentUrl) {
-          return yield* Effect.fail(
-            new Error(`Axiom dataset "${dataset.name}" is missing its edge deployment metadata`),
-          );
+          return yield* new DatasetUnexpectedResponse({
+            message: `Axiom dataset "${dataset.name}" is missing its edge deployment metadata`,
+          });
         }
+        const { apiBaseUrl } = yield* credentials;
         const apiRoot = apiBaseUrl.replace(/\/$/, "");
         const otelRoot = dataset.edgeDeploymentUrl.replace(/\/$/, "");
         return {
@@ -246,7 +273,7 @@ export const DatasetProvider = () =>
           // here mutation is safe.
           const datasetId = output?.id ?? news.name;
           const observed = yield* get({ dataset_id: datasetId }).pipe(
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
 
           // Ensure — POST creates the dataset. Tolerate Conflict/
@@ -303,13 +330,20 @@ export const DatasetProvider = () =>
             Effect.catchTag("NotFound", () => Effect.void),
           );
         }),
+        lookup: Effect.fn(function* ({ name }) {
+          const existing = yield* get({ dataset_id: name }).pipe(
+            Effect.catchTag("NotFound", () => Effect.undefined),
+          );
+          return existing === undefined ? undefined : yield* toAttrs(existing);
+        }),
+
         read: Effect.fn(function* ({ id, olds, output }) {
           const stack = yield* Stack;
           const stage = yield* Stage;
           const datasetId = output?.id ?? olds?.name;
           if (!datasetId) return undefined;
           const existing = yield* get({ dataset_id: datasetId }).pipe(
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
           if (!existing) return undefined;
           const ownership = parseMarker(existing.description);

package/src/Monitor.ts

@@ -12,9 +12,19 @@ export type Monitor = Resource<
   MonitorProps,
   Axiom.CreateMonitorResponse,
   never,
-  Providers
+  Providers,
+  MonitorLookup
 >;
 
+/**
+ * Props for {@link Monitor.lookup}: find a monitor this stack
+ * doesn't manage by its id.
+ */
+export interface MonitorLookup {
+  /** Axiom monitor id. */
+  id: string;
+}
+
 /**
  * An Axiom monitor — a scheduled APL/MPL query that evaluates on a fixed
  * cadence and fires alerts via {@link Notifier notifiers} when its
@@ -79,6 +89,16 @@ export type Monitor = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing monitor
+ * `Monitor.lookup` references a monitor Alchemy doesn't manage (created in
+ * the Axiom console or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Reference an existing monitor
+ * ```typescript
+ * const ref = Axiom.Monitor.lookup({ id: "m_abc123" });
+ * ```
+ *
  * @resource
  * @product Monitor
  */
@@ -121,7 +141,7 @@ export const MonitorProvider = () =>
           // re-creating.
           const observed = output?.id
             ? yield* get({ id: output.id }).pipe(
-                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+                Effect.catchTag("NotFound", () => Effect.undefined),
               )
             : undefined;
 
@@ -137,10 +157,14 @@ export const MonitorProvider = () =>
         delete: Effect.fn(function* ({ output }) {
           yield* del({ id: output.id }).pipe(Effect.catchTag("NotFound", () => Effect.void));
         }),
+        lookup: Effect.fn(function* ({ id }) {
+          return yield* get({ id }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));
+        }),
+
         read: Effect.fn(function* ({ output }) {
           if (!output?.id) return undefined;
           return yield* get({ id: output.id }).pipe(
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
         }),
       };

package/src/Notifier.ts

@@ -11,9 +11,19 @@ export type Notifier = Resource<
   NotifierProps,
   Axiom.CreateNotifierResponse & { id: string },
   never,
-  Providers
+  Providers,
+  NotifierLookup
 >;
 
+/**
+ * Props for {@link Notifier.lookup}: find a notifier this stack
+ * doesn't manage by its id.
+ */
+export interface NotifierLookup {
+  /** Axiom notifier id. */
+  id: string;
+}
+
 /**
  * An Axiom notifier — an alert destination (Slack, email, PagerDuty,
  * Opsgenie, Discord, Microsoft Teams, generic webhook, or a fully custom
@@ -65,6 +75,16 @@ export type Notifier = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing notifier
+ * `Notifier.lookup` references a notifier Alchemy doesn't manage (created in
+ * the Axiom console or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Reference an existing notifier
+ * ```typescript
+ * const ref = Axiom.Notifier.lookup({ id: "n_abc123" });
+ * ```
+ *
  * @resource
  * @product Monitor
  */
@@ -100,7 +120,7 @@ export const NotifierProvider = () =>
           // by re-creating.
           const observed = output?.id
             ? yield* get({ id: output.id }).pipe(
-                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+                Effect.catchTag("NotFound", () => Effect.undefined),
               )
             : undefined;
 
@@ -121,6 +141,13 @@ export const NotifierProvider = () =>
         delete: Effect.fn(function* ({ output }) {
           yield* del({ id: output.id }).pipe(Effect.catchTag("NotFound", () => Effect.void));
         }),
+        lookup: Effect.fn(function* ({ id }) {
+          return yield* get({ id }).pipe(
+            Effect.map((current) => ({ ...current, id: current.id ?? id })),
+            Effect.catchTag("NotFound", () => Effect.undefined),
+          );
+        }),
+
         read: Effect.fn(function* ({ output }) {
           if (!output?.id) return undefined;
           return yield* get({ id: output.id }).pipe(
@@ -128,7 +155,7 @@ export const NotifierProvider = () =>
               ...current,
               id: current.id ?? output.id,
             })),
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
         }),
       };

package/src/View.ts

@@ -19,9 +19,19 @@ export type View = Resource<
     id: string;
   },
   never,
-  Providers
+  Providers,
+  ViewLookup
 >;
 
+/**
+ * Props for {@link View.lookup}: find a view this stack
+ * doesn't manage by its id.
+ */
+export interface ViewLookup {
+  /** Axiom view id. */
+  id: string;
+}
+
 /**
  * An Axiom saved view — a named, shareable APL query. Useful for building
  * starter dashboards, providing canned "open in Axiom" links from your app,
@@ -60,6 +70,16 @@ export type View = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing view
+ * `View.lookup` references a view Alchemy doesn't manage (created in
+ * the Axiom console or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Reference an existing view
+ * ```typescript
+ * const ref = Axiom.View.lookup({ id: "v_abc123" });
+ * ```
+ *
  * @resource
  * @product Dashboard
  */
@@ -101,7 +121,7 @@ export const ViewProvider = () =>
           // current `news.name` always agree by the time we land here.
           const viewId = output?.id ?? news.name;
           const observed = yield* get({ id: viewId }).pipe(
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
 
           // Ensure — POST creates the view under `news.name`.
@@ -118,11 +138,18 @@ export const ViewProvider = () =>
         delete: Effect.fn(function* ({ output }) {
           yield* del({ id: output.id }).pipe(Effect.catchTag("NotFound", () => Effect.void));
         }),
+        lookup: Effect.fn(function* ({ id }) {
+          return yield* get({ id }).pipe(
+            Effect.map((current) => ({ ...current, id })),
+            Effect.catchTag("NotFound", () => Effect.undefined),
+          );
+        }),
+
         read: Effect.fn(function* ({ output }) {
           if (!output?.id) return undefined;
           return yield* get({ id: output.id }).pipe(
             Effect.map((current) => ({ ...current, id: output.id })),
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
         }),
       };

package/src/VirtualField.ts

@@ -12,9 +12,19 @@ export type VirtualField = Resource<
   VirtualFieldProps,
   Axiom.CreateVirtualFieldResponse,
   never,
-  Providers
+  Providers,
+  VirtualFieldLookup
 >;
 
+/**
+ * Props for {@link VirtualField.lookup}: find a virtual field this stack
+ * doesn't manage by its id.
+ */
+export interface VirtualFieldLookup {
+  /** Axiom virtual field id. */
+  id: string;
+}
+
 /**
  * An Axiom virtual field — a saved APL expression that appears as a derived
  * column on a dataset at query time. Use these to standardise common
@@ -47,6 +57,16 @@ export type VirtualField = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing virtual field
+ * `VirtualField.lookup` references a virtual field Alchemy doesn't manage (created in
+ * the Axiom console or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Reference an existing virtual field
+ * ```typescript
+ * const ref = Axiom.VirtualField.lookup({ id: "vf_abc123" });
+ * ```
+ *
  * @resource
  * @product Dataset
  */
@@ -96,7 +116,7 @@ export const VirtualFieldProvider = () =>
           // re-creating.
           const observed = output?.id
             ? yield* get({ id: output.id }).pipe(
-                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+                Effect.catchTag("NotFound", () => Effect.undefined),
               )
             : undefined;
 
@@ -112,10 +132,14 @@ export const VirtualFieldProvider = () =>
         delete: Effect.fn(function* ({ output }) {
           yield* del({ id: output.id }).pipe(Effect.catchTag("NotFound", () => Effect.void));
         }),
+        lookup: Effect.fn(function* ({ id }) {
+          return yield* get({ id }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));
+        }),
+
         read: Effect.fn(function* ({ output }) {
           if (!output?.id) return undefined;
           return yield* get({ id: output.id }).pipe(
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("NotFound", () => Effect.undefined),
           );
         }),
       };