@distilled.cloud/axiom 0.30.3 → 1.0.0-rc.10

package/src/index.ts

@@ -1,21 +1,43 @@
 /**
- * Axiom SDK for Effect
+ * @distilled.cloud/axiom — 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:
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models
+ * in `.generated-specs` (written by `scripts/convert.ts` from the three
+ * OpenAPI specs in specs/docs/restapi/versions). Everything else in this
+ * folder is hand-written.
+ *
+ * The v2 control-plane API lives under `Services.v2`; the v1 edge APIs are
+ * also available under their own subpath imports:
  *
  * @example
- * \`\`\`ts
- * import * as Operations from "@distilled.cloud/axiom";
+ * ```ts
+ * import * as Axiom from "@distilled.cloud/axiom";
  * import * as EdgeIngest from "@distilled.cloud/axiom/edge-ingest";
  * import * as EdgeQuery from "@distilled.cloud/axiom/edge-query";
- * \`\`\`
+ *
+ * const datasets = yield* Axiom.Services.v2.getDatasets({});
+ * ```
  */
 export * from "./credentials.ts";
-export * as Category from "./category.ts";
+export * from "./errors.ts";
 export * as T from "./traits.ts";
+export {
+  AxiomProtocol,
+  stripNulls,
+  type AxiomOpError,
+  type AxiomOpContext,
+} from "./protocol.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";
+export * as Services from "./services/index.ts";
+// v0-parity surface: the v2 control-plane operations live on the package
+// root (edge-ingest / edge-query stay behind their subpath exports).
+// The service-local typed error classes shadow the same-named shared ones
+// from ./errors.ts — the ops actually raise the service-local classes.
+export * from "./services/v2.ts";
+export {
+  BadRequest,
+  Conflict,
+  Forbidden,
+  NotFound,
+  UnprocessableEntity,
+} from "./services/v2.ts";

package/src/protocol.ts

@@ -0,0 +1,111 @@
+/**
+ * AxiomProtocol — hand-written.
+ *
+ * Axiom speaks plain bearer-authenticated JSON REST (no response envelope),
+ * so the whole protocol is one `makeRestProtocol` call from
+ * `core/protocol-rest`:
+ *
+ *   request:  credentials → `Authorization: Bearer <apiKey>` (+ optional
+ *             `X-Axiom-Org-ID` for Personal Access Tokens) + base URL
+ *             (default https://api.axiom.co), resolved from the calling
+ *             fiber on every request
+ *
+ *   response: 2xx JSON is the payload, with explicit JSON `null` properties
+ *             recursively dropped first ({@link stripNulls} — Axiom's Go
+ *             backend serializes nil slices/omitted optionals as `null`);
+ *             non-2xx bodies map to the operation's typed error classes by
+ *             status, then the shared HTTP-status classes, then
+ *             {@link UnknownAxiomError}. Axiom returns two error envelope
+ *             shapes — `{ code, message }` (control-plane / edge-ingest) and
+ *             `{ error, message }` (edge-query) — unified by a lenient
+ *             extractor; the HTTP status stays the authoritative signal.
+ */
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as API from "@distilled.cloud/core/api";
+import {
+  makeRestProtocol,
+  type RestErrorEnvelope,
+} from "@distilled.cloud/core/protocol-rest";
+import type { API_ERRORS, ConfigError } from "@distilled.cloud/core/errors";
+import { Credentials, type Config } from "./credentials.ts";
+import { UnknownAxiomError } from "./errors.ts";
+
+/**
+ * Error channel shared by every generated Axiom operation. Generated service
+ * files annotate operations with `API.OperationMethod<I, O, AxiomOpError,
+ * AxiomOpContext>` explicitly so the compiler never infers these back out of
+ * the schema generics.
+ */
+export type AxiomOpError =
+  | InstanceType<(typeof API_ERRORS)[number]>
+  | UnknownAxiomError
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated Axiom operation. */
+export type AxiomOpContext = Credentials | HttpClient.HttpClient;
+
+/**
+ * Axiom's backend (Go) serializes nil slices and omitted optional fields as
+ * JSON `null`. The generated output schemas model these as optional members
+ * (value or absent), so `null` trips decoding. Recursively drop explicit
+ * `null` properties before decoding so optional fields are treated as
+ * absent. Keys that are genuinely nullable in the API are patched to
+ * nullable in the spec — this hook exists for the far more common "Go nil
+ * slice" case.
+ */
+export 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;
+};
+
+/**
+ * Unify Axiom's two error envelope shapes (`{ code, message }` and
+ * `{ error, message }`, some endpoints plain `{ message }`) into one
+ * `{ code?, message? }` pair — v0 semantics: `message ?? error`,
+ * `code ?? error`.
+ */
+const errorEnvelope = (body: unknown): RestErrorEnvelope | undefined => {
+  if (body === null || typeof body !== "object") return undefined;
+  const b = body as Record<string, unknown>;
+  const error = typeof b.error === "string" ? b.error : undefined;
+  const code =
+    typeof b.code === "string" || typeof b.code === "number" ? b.code : error;
+  const message = typeof b.message === "string" ? b.message : error;
+  return { code, message };
+};
+
+export const AxiomProtocol: Layer.Layer<API.Protocol> =
+  makeRestProtocol<Config>({
+    // The Credentials service holds an effect — resolving it here (per
+    // request, on the calling fiber) picks up context-provided credentials.
+    credentials: Effect.gen(function* () {
+      const resolve = yield* Credentials;
+      return yield* resolve;
+    }),
+    baseUrl: (creds) => creds.apiBaseUrl,
+    headers: (creds) => ({
+      Authorization: `Bearer ${Redacted.value(creds.apiKey)}`,
+      ...(creds.orgId ? { "X-Axiom-Org-ID": creds.orgId } : {}),
+    }),
+    errorEnvelope,
+    transformResponse: stripNulls,
+    unknownError: ({ code, message, body }) =>
+      new UnknownAxiomError({
+        code: typeof code === "number" ? String(code) : code,
+        message,
+        body,
+      }),
+  });

package/src/retry.ts

@@ -1,10 +1,9 @@
 /**
  * Axiom retry configuration.
  *
- * Defines the per-SDK `Retry` Context.Service tag that
- * `packages/axiom/src/client.ts` wires into `makeAPI`. Callers can
- * install a blanket retry policy at the layer level and have every
- * Axiom API call below it pick it up:
+ * Defines the per-SDK `Retry` Context.Service tag that generated operations
+ * wire into `API.make`. Callers can install a blanket retry policy at the
+ * layer level and have every Axiom API call below it pick it up:
  *
  * @example
  * ```ts

package/src/services/edge_ingest.ts

@@ -0,0 +1,122 @@
+// AUTO-GENERATED by scripts/generate.ts from .generated-specs (specs/docs restapi/versions). Do not edit.
+import * as S from "@distilled.cloud/core/schema";
+import * as API from "@distilled.cloud/core/api";
+import * as C from "@distilled.cloud/core/category";
+import * as T from "../traits.ts";
+import {
+  AxiomProtocol,
+  type AxiomOpError,
+  type AxiomOpContext,
+} from "../protocol.ts";
+import { UnknownAxiomError } from "../errors.ts";
+import * as Retry from "../retry.ts";
+
+export type { AxiomOpError, AxiomOpContext };
+
+export class BadRequest
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<BadRequest>()("BadRequest", {
+      code: S.Number,
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [{ status: 400 }],
+  ) {}
+
+export class NotFound
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<NotFound>()("NotFound", {
+      code: S.Number,
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [{ status: 404 }],
+  ) {}
+
+export class UnprocessableEntity
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<UnprocessableEntity>()("UnprocessableEntity", {
+      code: S.Number,
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [{ status: 422 }],
+  ) {}
+
+export interface IngestToDatasetRequest {
+  dataset_id: string;
+  /** 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. */
+  timestamp_field?: string;
+  /** 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 */
+  timestamp_format?: string;
+  /** The delimiter to use when parsing CSV data. If not specified, the default delimiter is `,`. */
+  csv_delimiter?: string;
+  body: string;
+}
+export const IngestToDatasetRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    dataset_id: S.String.pipe(T.Label()),
+    timestamp_field: S.optional(S.String.pipe(T.Query("timestamp-field"))),
+    timestamp_format: S.optional(S.String.pipe(T.Query("timestamp-format"))),
+    csv_delimiter: S.optional(S.String.pipe(T.Query("csv-delimiter"))),
+    body: S.String.pipe(T.HttpBody()),
+  }).pipe(
+    T.Http({
+      method: "POST",
+      uri: "/v1/datasets/{dataset_id}/ingest",
+      code: 200,
+    }),
+  ),
+).annotate({
+  identifier: "IngestToDatasetRequest",
+}) as any as S.Schema<IngestToDatasetRequest>;
+
+export interface IngestFailure {
+  error: string;
+  timestamp: string;
+}
+export const IngestFailure = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    error: S.String,
+    timestamp: S.String,
+  }),
+).annotate({ identifier: "IngestFailure" }) as any as S.Schema<IngestFailure>;
+
+export type IngestStatusFailuresList = Array<IngestFailure>;
+export const IngestStatusFailuresList = /*@__PURE__*/ S.Array(
+  IngestFailure,
+) as any as S.Schema<IngestStatusFailuresList>;
+
+export interface IngestStatus {
+  blocksCreated: number;
+  failed: number;
+  failures?: IngestStatusFailuresList;
+  ingested: number;
+  processedBytes: number;
+  walLength: number;
+}
+export const IngestStatus = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    blocksCreated: S.Number,
+    failed: S.Number,
+    failures: S.optional(IngestStatusFailuresList),
+    ingested: S.Number,
+    processedBytes: S.Number,
+    walLength: S.Number,
+  }),
+).annotate({ identifier: "IngestStatus" }) as any as S.Schema<IngestStatus>;
+
+export type IngestToDatasetError =
+  | BadRequest
+  | NotFound
+  | UnprocessableEntity
+  | AxiomOpError;
+export const ingestToDataset: API.OperationMethod<
+  IngestToDatasetRequest,
+  IngestStatus,
+  IngestToDatasetError,
+  AxiomOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: IngestToDatasetRequest,
+  output: IngestStatus,
+  errors: [BadRequest, NotFound, UnprocessableEntity, UnknownAxiomError],
+  protocol: AxiomProtocol,
+  retry: Retry.Retry,
+}));

package/src/services/edge_query.ts

@@ -0,0 +1,197 @@
+// AUTO-GENERATED by scripts/generate.ts from .generated-specs (specs/docs restapi/versions). Do not edit.
+import * as S from "@distilled.cloud/core/schema";
+import * as API from "@distilled.cloud/core/api";
+import * as T from "../traits.ts";
+import {
+  AxiomProtocol,
+  type AxiomOpError,
+  type AxiomOpContext,
+} from "../protocol.ts";
+import { UnknownAxiomError } from "../errors.ts";
+import * as Retry from "../retry.ts";
+
+export type { AxiomOpError, AxiomOpContext };
+
+export type QueryAplRequestFormat = "legacy" | "tabular" | "tabular-rows";
+export const QueryAplRequestFormat = S.String;
+
+export interface QueryAplRequestDefaultOrderItem {
+  desc?: boolean;
+  field?: string;
+}
+export const QueryAplRequestDefaultOrderItem = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    desc: S.optional(S.Boolean),
+    field: S.optional(S.String),
+  }),
+).annotate({
+  identifier: "QueryAplRequestDefaultOrderItem",
+}) as any as S.Schema<QueryAplRequestDefaultOrderItem>;
+
+/** The default order to use when no order is specified in the query. */
+export type QueryAplRequestDefaultOrderList =
+  Array<QueryAplRequestDefaultOrderItem>;
+export const QueryAplRequestDefaultOrderList = /*@__PURE__*/ S.Array(
+  QueryAplRequestDefaultOrderItem,
+) as any as S.Schema<QueryAplRequestDefaultOrderList>;
+
+export type QueryAplRequestLibrariesList = Array<string>;
+export const QueryAplRequestLibrariesList = /*@__PURE__*/ S.Array(
+  S.String,
+) as any as S.Schema<QueryAplRequestLibrariesList>;
+
+export interface QueryOptions {
+  against?: string;
+  againstStart?: string;
+  againstTimestamp?: string;
+  aggChartOpts?: string;
+  caseSensitive?: string;
+  containsTimeFilter?: string;
+  datasets?: string;
+  displayNull?: string;
+  editorContent?: string;
+  endColumn?: string;
+  endLineNumber?: string;
+  endTime?: string;
+  integrationsFilter?: string;
+  nanosecondPrecision?: string;
+  openIntervals?: string;
+  overlayCharts?: string;
+  queryObject?: string;
+  quickRange?: string;
+  resolution?: string;
+  resultsHistogram?: string;
+  selection?: string;
+  shownColumns?: string;
+  startColumn?: string;
+  startLineNumber?: string;
+  startTime?: string;
+  timeSeriesVariant?: string;
+  timeSeriesView?: string;
+}
+export const QueryOptions = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    against: S.optional(S.String),
+    againstStart: S.optional(S.String),
+    againstTimestamp: S.optional(S.String),
+    aggChartOpts: S.optional(S.String),
+    caseSensitive: S.optional(S.String),
+    containsTimeFilter: S.optional(S.String),
+    datasets: S.optional(S.String),
+    displayNull: S.optional(S.String),
+    editorContent: S.optional(S.String),
+    endColumn: S.optional(S.String),
+    endLineNumber: S.optional(S.String),
+    endTime: S.optional(S.String),
+    integrationsFilter: S.optional(S.String),
+    nanosecondPrecision: S.optional(S.String),
+    openIntervals: S.optional(S.String),
+    overlayCharts: S.optional(S.String),
+    queryObject: S.optional(S.String),
+    quickRange: S.optional(S.String),
+    resolution: S.optional(S.String),
+    resultsHistogram: S.optional(S.String),
+    selection: S.optional(S.String),
+    shownColumns: S.optional(S.String),
+    startColumn: S.optional(S.String),
+    startLineNumber: S.optional(S.String),
+    startTime: S.optional(S.String),
+    timeSeriesVariant: S.optional(S.String),
+    timeSeriesView: S.optional(S.String),
+  }),
+).annotate({ identifier: "QueryOptions" }) as any as S.Schema<QueryOptions>;
+
+/** Variables is an optional set of additional variables that are inserted into the APL */
+export type QueryAplRequestVariablesMap = {
+  [key: string]: unknown | undefined;
+};
+export const QueryAplRequestVariablesMap = /*@__PURE__*/ S.Record(
+  S.String,
+  S.Unknown,
+) as any as S.Schema<QueryAplRequestVariablesMap>;
+
+export interface QueryAplRequest {
+  format: QueryAplRequestFormat | (string & {});
+  nocache?: boolean;
+  saveAsKind?: string;
+  /** when saveAsKind is true, this parameter indicates the id of the associated dataset */
+  id?: string;
+  streaming_duration?: string;
+  /** contains the source of the APL query (for example console, dashboard, etc.) */
+  apl_source?: string;
+  /** contains the id of the source, for example dashboard_id */
+  apl_source_id?: string;
+  /** Include a totals table (only supported in MetricsDB) */
+  totals?: boolean;
+  /** APL query string */
+  apl: string;
+  /** Pagination cursor */
+  cursor?: string;
+  /** The default limit to use when no limit is specified in the query. */
+  defaultLimit?: number;
+  /** The default order to use when no order is specified in the query. */
+  defaultOrder?: QueryAplRequestDefaultOrderList;
+  /** End time for the query range */
+  endTime?: string;
+  /** Include cursor in response */
+  includeCursor?: boolean;
+  /** Defines if the _cursor field should be projected in the result */
+  includeCursorField?: boolean;
+  libraries?: QueryAplRequestLibrariesList;
+  /** Maximum number of groups to automatically bin into */
+  maxBinAutoGroups?: number;
+  queryOptions?: QueryOptions;
+  /** start and end time for the query, these must be specified as RFC3339 strings or using relative time expressions (e.g. now-1h, now-1d, now-1w, etc) */
+  startTime?: string;
+  /** Variables is an optional set of additional variables that are inserted into the APL */
+  variables?: QueryAplRequestVariablesMap;
+}
+export const QueryAplRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    format: QueryAplRequestFormat.pipe(T.Query()),
+    nocache: S.optional(S.Boolean.pipe(T.Query())),
+    saveAsKind: S.optional(S.String.pipe(T.Query())),
+    id: S.optional(S.String.pipe(T.Query())),
+    streaming_duration: S.optional(
+      S.String.pipe(T.Query("streaming-duration")),
+    ),
+    apl_source: S.optional(S.String.pipe(T.Query("apl-source"))),
+    apl_source_id: S.optional(S.String.pipe(T.Query("apl-source-id"))),
+    totals: S.optional(S.Boolean.pipe(T.Query())),
+    apl: S.String,
+    cursor: S.optional(S.String),
+    defaultLimit: S.optional(S.Number),
+    defaultOrder: S.optional(QueryAplRequestDefaultOrderList),
+    endTime: S.optional(S.String),
+    includeCursor: S.optional(S.Boolean),
+    includeCursorField: S.optional(S.Boolean),
+    libraries: S.optional(QueryAplRequestLibrariesList),
+    maxBinAutoGroups: S.optional(S.Number),
+    queryOptions: S.optional(QueryOptions),
+    startTime: S.optional(S.String),
+    variables: S.optional(QueryAplRequestVariablesMap),
+  }).pipe(T.Http({ method: "POST", uri: "/v1/datasets/_apl", code: 200 })),
+).annotate({
+  identifier: "QueryAplRequest",
+}) as any as S.Schema<QueryAplRequest>;
+
+export type QueryAplResponse = unknown;
+export const QueryAplResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Unknown.pipe(T.RawResponseRoot()),
+).annotate({
+  identifier: "QueryAplResponse",
+}) as any as S.Schema<QueryAplResponse>;
+
+export type QueryAplError = AxiomOpError;
+export const queryApl: API.OperationMethod<
+  QueryAplRequest,
+  QueryAplResponse,
+  QueryAplError,
+  AxiomOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: QueryAplRequest,
+  output: QueryAplResponse,
+  errors: [UnknownAxiomError],
+  protocol: AxiomProtocol,
+  retry: Retry.Retry,
+}));

package/src/services/index.ts

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by scripts/generate.ts. Do not edit.
+export * as edge_ingest from "./edge_ingest.ts";
+export * as edge_query from "./edge_query.ts";
+export * as v2 from "./v2.ts";