@distilled.cloud/axiom 0.0.0 → 0.13.0

package/lib/traits.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export the shared traits system from sdk-core.
+ */
+export * from "@distilled.cloud/core/traits";
+//# sourceMappingURL=traits.d.ts.map

package/lib/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,8BAA8B,CAAC"}

package/lib/traits.js

@@ -0,0 +1,5 @@
+/**
+ * Re-export the shared traits system from sdk-core.
+ */
+export * from "@distilled.cloud/core/traits";
+//# sourceMappingURL=traits.js.map

package/lib/traits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.js","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,8BAA8B,CAAC"}

package/package.json

@@ -1,15 +1,93 @@
 {
   "name": "@distilled.cloud/axiom",
-  "version": "0.0.0",
-  "module": "index.ts",
+  "version": "0.13.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alchemy-run/distilled",
+    "directory": "packages/axiom"
+  },
   "type": "module",
+  "sideEffects": false,
+  "module": "src/index.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./Category": {
+      "types": "./lib/category.d.ts",
+      "bun": "./src/category.ts",
+      "default": "./lib/category.js"
+    },
+    "./Client": {
+      "types": "./lib/client.d.ts",
+      "bun": "./src/client.ts",
+      "default": "./lib/client.js"
+    },
+    "./Credentials": {
+      "types": "./lib/credentials.d.ts",
+      "bun": "./src/credentials.ts",
+      "default": "./lib/credentials.js"
+    },
+    "./Errors": {
+      "types": "./lib/errors.d.ts",
+      "bun": "./src/errors.ts",
+      "default": "./lib/errors.js"
+    },
+    "./edge-ingest": {
+      "types": "./lib/edge-ingest.d.ts",
+      "bun": "./src/edge-ingest.ts",
+      "default": "./lib/edge-ingest.js"
+    },
+    "./edge-query": {
+      "types": "./lib/edge-query.d.ts",
+      "bun": "./src/edge-query.ts",
+      "default": "./lib/edge-query.js"
+    },
+    "./Retry": {
+      "types": "./lib/retry.d.ts",
+      "bun": "./src/retry.ts",
+      "default": "./lib/retry.js"
+    },
+    "./Sensitive": {
+      "types": "./lib/sensitive.d.ts",
+      "bun": "./src/sensitive.ts",
+      "default": "./lib/sensitive.js"
+    },
+    "./Traits": {
+      "types": "./lib/traits.d.ts",
+      "bun": "./src/traits.ts",
+      "default": "./lib/traits.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsgo",
+    "build": "tsgo -b",
+    "fmt": "oxfmt --write src",
+    "lint": "oxlint --fix src",
+    "check": "tsgo && oxlint src && oxfmt --check src",
+    "test": "bunx vitest run test",
+    "publish:npm": "bun run build && bun publish --access public",
+    "generate": "bun run scripts/generate.ts && oxlint --fix src && oxfmt --write src && oxfmt --write src",
+    "specs:fetch": "git submodule update --force --init --recursive --depth=1 specs/docs && git -C specs/docs checkout -- .",
+    "specs:update": "git -C specs/docs fetch && git -C specs/docs checkout main && git -C specs/docs pull"
+  },
+  "dependencies": {
+    "@distilled.cloud/core": "0.13.0",
+    "effect": "4.0.0-beta.58"
+  },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "^1.3.0",
+    "@types/node": "^25.3.5",
+    "dotenv": "^16.5.0",
+    "vitest": "^3.2.3"
   },
   "peerDependencies": {
-    "typescript": "^5"
-  },
-  "repository": {
-    "type": "git"
+    "effect": "4.0.0-beta.58"
   }
 }

package/src/category.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export the shared category system from sdk-core.
+ */
+export * from "@distilled.cloud/core/category";

package/src/client.ts

@@ -0,0 +1,112 @@
+/**
+ * Axiom API Client.
+ *
+ * Wraps the shared REST client from sdk-core with Axiom-specific
+ * error matching and credential handling.
+ */
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { makeAPI } from "@distilled.cloud/core/client";
+import {
+  HTTP_STATUS_MAP,
+  UnknownAxiomError,
+  AxiomParseError,
+} from "./errors.ts";
+
+// Re-export for backwards compatibility
+export { UnknownAxiomError } from "./errors.ts";
+import { Credentials } from "./credentials.ts";
+
+/**
+ * Axiom returns two error envelope shapes:
+ *   - control-plane / edge-ingest: `{ "code": "...", "message": "..." }`
+ *   - edge-query:                  `{ "error": "...", "message": "..." }`
+ * Plus some endpoints return plain `{ message: "..." }`.
+ * We accept all of them and extract a unified `message`/`code` pair.
+ */
+const ApiErrorResponse = Schema.Struct({
+  code: Schema.optional(Schema.Union([Schema.String, Schema.Number])),
+  error: Schema.optional(Schema.String),
+  message: Schema.optional(Schema.String),
+});
+
+/**
+ * Match an Axiom API error response to the appropriate error class based on
+ * HTTP status.
+ *
+ * Strategy: HTTP status is the authoritative signal. We always try status-based
+ * matching first, then enrich with a message parsed from the body if we can.
+ * Non-JSON responses (plain text "Forbidden", empty bodies, HTML error pages)
+ * still map to the correct typed error via status code.
+ */
+const matchError = (
+  status: number,
+  errorBody: unknown,
+): Effect.Effect<never, unknown> => {
+  const ErrorClass = (HTTP_STATUS_MAP as any)[status];
+  let message = "";
+  let code: string | number | undefined;
+  try {
+    const parsed = Schema.decodeUnknownSync(ApiErrorResponse)(errorBody);
+    message = parsed.message ?? parsed.error ?? "";
+    code = parsed.code ?? parsed.error;
+  } catch {
+    if (typeof errorBody === "string") {
+      message = errorBody;
+    }
+  }
+  if (ErrorClass) {
+    return Effect.fail(new ErrorClass({ message }));
+  }
+  return Effect.fail(
+    new UnknownAxiomError({
+      code: typeof code === "number" ? String(code) : code,
+      message,
+      body: errorBody,
+    }),
+  );
+};
+
+/**
+ * Axiom's backend (Go) serializes nil slices and omitted optional fields as
+ * JSON `null`. The generated output schemas model these as `Schema.optional(…)`
+ * which accepts only the value or `undefined`, so `null` trips decoding.
+ *
+ * Recursively drop explicit `null` properties before decoding so optional
+ * fields simply get treated as absent. Keys that are genuinely nullable in
+ * the API should be patched to `Schema.NullOr(…)` in the spec — this hook
+ * exists for the far more common "Go nil slice" case.
+ */
+const stripNulls = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(stripNulls);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (v === null) continue;
+      out[k] = stripNulls(v);
+    }
+    return out;
+  }
+  return value;
+};
+
+/**
+ * Axiom API client.
+ */
+export const API = makeAPI({
+  credentials: Credentials as any,
+  getBaseUrl: (creds: any) => creds.apiBaseUrl,
+  getAuthHeaders: (creds: any) => {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${Redacted.value(creds.apiKey)}`,
+    };
+    if (creds.orgId) {
+      headers["X-Axiom-Org-ID"] = creds.orgId;
+    }
+    return headers;
+  },
+  matchError,
+  ParseError: AxiomParseError as any,
+  transformResponse: stripNulls,
+});

package/src/credentials.ts

@@ -0,0 +1,51 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import * as Context from "effect/Context";
+import { ConfigError } from "@distilled.cloud/core/errors";
+
+/** Default base URL for Axiom Cloud. Self-hosted users can override via AXIOM_URL. */
+export const DEFAULT_API_BASE_URL = "https://api.axiom.co";
+
+export interface Config {
+  readonly apiKey: Redacted.Redacted<string>;
+  readonly apiBaseUrl: string;
+  /**
+   * Optional organization ID. Required when authenticating with a Personal
+   * Access Token (PAT); optional for API tokens scoped to a single org.
+   * Sent on every request as the `X-Axiom-Org-ID` header when set.
+   */
+  readonly orgId?: string;
+}
+
+export class Credentials extends Context.Service<Credentials, Config>()(
+  "AxiomCredentials",
+) {}
+
+/**
+ * Build {@link Credentials} from environment variables.
+ *
+ * - `AXIOM_TOKEN` or `AXIOM_API_KEY` (required) — Axiom API token or PAT.
+ * - `AXIOM_URL` (optional) — override the API base URL (for self-hosted or
+ *   regional edge deployments). Defaults to `https://api.axiom.co`.
+ * - `AXIOM_ORG_ID` (optional) — organization ID, required for PATs.
+ */
+export const CredentialsFromEnv = Layer.effect(
+  Credentials,
+  Effect.gen(function* () {
+    const apiKey = process.env.AXIOM_TOKEN ?? process.env.AXIOM_API_KEY;
+
+    if (!apiKey) {
+      return yield* new ConfigError({
+        message:
+          "AXIOM_TOKEN (or AXIOM_API_KEY) environment variable is required",
+      });
+    }
+
+    return {
+      apiKey: Redacted.make(apiKey),
+      apiBaseUrl: process.env.AXIOM_URL ?? DEFAULT_API_BASE_URL,
+      orgId: process.env.AXIOM_ORG_ID,
+    };
+  }),
+);

package/src/edge-ingest.ts

@@ -0,0 +1 @@
+export * from "./operations/v1-edge-ingest/index.ts";

package/src/edge-query.ts

@@ -0,0 +1 @@
+export * from "./operations/v1-edge-query/index.ts";

package/src/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * Axiom-specific error types.
+ *
+ * Re-exports common HTTP errors from sdk-core and adds Axiom-specific
+ * error matching and API error types.
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  Locked,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+export type { DefaultErrors } from "@distilled.cloud/core/errors";
+
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+// Unknown Axiom error - returned when an error code is not recognized
+export class UnknownAxiomError extends Schema.TaggedErrorClass<UnknownAxiomError>()(
+  "UnknownAxiomError",
+  {
+    code: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+    body: Schema.Unknown,
+  },
+).pipe(Category.withServerError) {}
+
+// Schema parse error wrapper
+export class AxiomParseError extends Schema.TaggedErrorClass<AxiomParseError>()(
+  "AxiomParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Axiom SDK for Effect
+ *
+ * The package root re-exports the v2 (control-plane) operations. The v1 edge
+ * APIs are available under their own subpath imports:
+ *
+ * @example
+ * \`\`\`ts
+ * import * as Operations from "@distilled.cloud/axiom";
+ * import * as EdgeIngest from "@distilled.cloud/axiom/edge-ingest";
+ * import * as EdgeQuery from "@distilled.cloud/axiom/edge-query";
+ * \`\`\`
+ */
+export * from "./credentials.ts";
+export * as Category from "./category.ts";
+export * as T from "./traits.ts";
+export * as Retry from "./retry.ts";
+export { API } from "./client.ts";
+export * from "./errors.ts";
+export { SensitiveString, SensitiveNullableString } from "./sensitive.ts";
+export * from "./operations/index.ts";

package/src/operations/index.ts

@@ -0,0 +1 @@
+export * from "./v2/index.ts";

package/src/operations/v1-edge-ingest/index.ts

@@ -0,0 +1 @@
+export * from "./ingestToDataset";

package/src/operations/v1-edge-ingest/ingestToDataset.ts

@@ -0,0 +1,46 @@
+import * as Schema from "effect/Schema";
+import { API } from "../../client";
+import * as T from "../../traits";
+import { BadRequest, NotFound, UnprocessableEntity } from "../../errors";
+
+// Input Schema
+export const IngestToDatasetInput = /*@__PURE__*/ /*#__PURE__*/ Schema.Struct({
+  "dataset-id": Schema.String.pipe(T.PathParam()),
+  "timestamp-field": Schema.optional(Schema.String),
+  "timestamp-format": Schema.optional(Schema.String),
+  "csv-delimiter": Schema.optional(Schema.String),
+}).pipe(T.Http({ method: "POST", path: "/v1/datasets/{dataset-id}/ingest" }));
+export type IngestToDatasetInput = typeof IngestToDatasetInput.Type;
+
+// Output Schema
+export const IngestToDatasetOutput = /*@__PURE__*/ /*#__PURE__*/ Schema.Struct({
+  blocksCreated: Schema.Number,
+  failed: Schema.Number,
+  failures: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        error: Schema.String,
+        timestamp: Schema.String,
+      }),
+    ),
+  ),
+  ingested: Schema.Number,
+  processedBytes: Schema.Number,
+  walLength: Schema.Number,
+});
+export type IngestToDatasetOutput = typeof IngestToDatasetOutput.Type;
+
+// The operation
+/**
+ *
+ * @param timestamp-field - The name of the field to use as the timestamp. If not specified, the timestamp will be the time the event was received by Axiom.
+ * @param timestamp-format - The date-time format of the timestamp field. The reference time is `Mon Jan 2 15:04:05 -0700 MST 2006`, as specified in https://pkg.go.dev/time/?tab=doc#Parse
+ * @param csv-delimiter - The delimiter to use when parsing CSV data. If not specified, the default delimiter is `,`.
+ * @param X-Axiom-CSV-Fields - A list of optional comma separated fields to use for CSV ingestion. If not specified, the first line of the CSV will be used as the field names.
+ * @param X-Axiom-Event-Labels - An optional JSON encoded object with additional labels to add to all events in the request
+ */
+export const ingestToDataset = /*@__PURE__*/ /*#__PURE__*/ API.make(() => ({
+  inputSchema: IngestToDatasetInput,
+  outputSchema: IngestToDatasetOutput,
+  errors: [BadRequest, NotFound, UnprocessableEntity] as const,
+}));

package/src/operations/v1-edge-query/index.ts

@@ -0,0 +1 @@
+export * from "./queryApl";

package/src/operations/v1-edge-query/queryApl.ts

@@ -0,0 +1,84 @@
+import * as Schema from "effect/Schema";
+import { API } from "../../client";
+import * as T from "../../traits";
+
+// Input Schema
+export const QueryAplInput = /*@__PURE__*/ /*#__PURE__*/ Schema.Struct({
+  format: Schema.Literals(["legacy", "tabular", "tabular-rows"]),
+  nocache: Schema.optional(Schema.Boolean),
+  saveAsKind: Schema.optional(Schema.String),
+  id: Schema.optional(Schema.String),
+  "streaming-duration": Schema.optional(Schema.String),
+  "apl-source": Schema.optional(Schema.String),
+  "apl-source-id": Schema.optional(Schema.String),
+  totals: Schema.optional(Schema.Boolean),
+  apl: Schema.String,
+  cursor: Schema.optional(Schema.String),
+  defaultLimit: Schema.optional(Schema.Number),
+  defaultOrder: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        desc: Schema.optional(Schema.Boolean),
+        field: Schema.optional(Schema.String),
+      }),
+    ),
+  ),
+  endTime: Schema.optional(Schema.String),
+  includeCursor: Schema.optional(Schema.Boolean),
+  includeCursorField: Schema.optional(Schema.Boolean),
+  libraries: Schema.optional(Schema.Array(Schema.String)),
+  maxBinAutoGroups: Schema.optional(Schema.Number),
+  queryEdgeDeployment: Schema.optional(Schema.String),
+  queryOptions: Schema.optional(
+    Schema.Struct({
+      against: Schema.optional(Schema.String),
+      againstStart: Schema.optional(Schema.String),
+      againstTimestamp: Schema.optional(Schema.String),
+      aggChartOpts: Schema.optional(Schema.String),
+      caseSensitive: Schema.optional(Schema.String),
+      containsTimeFilter: Schema.optional(Schema.String),
+      datasets: Schema.optional(Schema.String),
+      displayNull: Schema.optional(Schema.String),
+      editorContent: Schema.optional(Schema.String),
+      endColumn: Schema.optional(Schema.String),
+      endLineNumber: Schema.optional(Schema.String),
+      endTime: Schema.optional(Schema.String),
+      integrationsFilter: Schema.optional(Schema.String),
+      nanosecondPrecision: Schema.optional(Schema.String),
+      openIntervals: Schema.optional(Schema.String),
+      overlayCharts: Schema.optional(Schema.String),
+      queryObject: Schema.optional(Schema.String),
+      quickRange: Schema.optional(Schema.String),
+      resolution: Schema.optional(Schema.String),
+      resultsHistogram: Schema.optional(Schema.String),
+      selection: Schema.optional(Schema.String),
+      shownColumns: Schema.optional(Schema.String),
+      startColumn: Schema.optional(Schema.String),
+      startLineNumber: Schema.optional(Schema.String),
+      startTime: Schema.optional(Schema.String),
+      timeSeriesVariant: Schema.optional(Schema.String),
+      timeSeriesView: Schema.optional(Schema.String),
+    }),
+  ),
+  queryRegion: Schema.optional(Schema.String),
+  startTime: Schema.optional(Schema.String),
+  variables: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+}).pipe(T.Http({ method: "POST", path: "/v1/datasets/_apl?format=tabular" }));
+export type QueryAplInput = typeof QueryAplInput.Type;
+
+// Output Schema
+export const QueryAplOutput = /*@__PURE__*/ /*#__PURE__*/ Schema.Unknown;
+export type QueryAplOutput = typeof QueryAplOutput.Type;
+
+// The operation
+/**
+ *
+ * @param id - when saveAsKind is true, this parameter indicates the id of the associated dataset
+ * @param apl-source - contains the source of the APL query (for example console, dashboard, etc.)
+ * @param apl-source-id - contains the id of the source, for example dashboard_id
+ * @param totals - Include a totals table (only supported in MetricsDB)
+ */
+export const queryApl = /*@__PURE__*/ /*#__PURE__*/ API.make(() => ({
+  inputSchema: QueryAplInput,
+  outputSchema: QueryAplOutput,
+}));