@automate.ax/integration-contracts 0.125.0 → 0.127.0

package/src/axiom/api.ts

@@ -0,0 +1,252 @@
+import { encodableSchema, type Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+
+const AXIOM_API_ORIGIN = "https://api.axiom.co"
+const AXIOM_SECRET_SCHEMA = z.object({ apiKey: z.string().trim().min(1) })
+
+export interface AxiomResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "axiom"
+}
+
+export interface AxiomRequestOptions<TSchema extends z.ZodType> {
+  body?: Encodable
+  headers?: Record<string, string>
+  method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT"
+  query?: Record<string, boolean | number | string | undefined>
+  responseSchema: TSchema
+  version?: "v1" | "v2"
+}
+
+/** Structured Axiom REST error. */
+export class AxiomApiError extends Error {
+  readonly details: Encodable
+  readonly ingestLimitReset?: number
+  readonly queryLimitReset?: number
+  readonly rateLimitReset?: number
+  readonly retryAfter?: number
+  readonly status: number
+
+  /**
+   * Creates a structured provider error.
+   *
+   * @param options - Error response details and rate-limit metadata.
+   * @param options.details - Parsed provider response body.
+   * @param options.ingestLimitReset - Ingest-limit reset timestamp.
+   * @param options.queryLimitReset - Query-limit reset timestamp.
+   * @param options.rateLimitReset - Request-rate-limit reset timestamp.
+   * @param options.retryAfter - Suggested retry delay in seconds.
+   * @param options.status - HTTP response status.
+   */
+  constructor(options: {
+    details: Encodable
+    ingestLimitReset?: number
+    queryLimitReset?: number
+    rateLimitReset?: number
+    retryAfter?: number
+    status: number
+  }) {
+    const message =
+      isPlainObject(options.details) &&
+      typeof options.details.message === "string"
+        ? options.details.message
+        : undefined
+    super(
+      message
+        ? `Axiom API error (${options.status}): ${message}`
+        : `Axiom API request failed (${options.status}).`,
+    )
+    this.name = "AxiomApiError"
+    this.details = options.details
+    this.ingestLimitReset = options.ingestLimitReset
+    this.queryLimitReset = options.queryLimitReset
+    this.rateLimitReset = options.rateLimitReset
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated, origin-confined Axiom API client.
+ *
+ * @param account - Resolved Axiom integration account.
+ * @param edgeUrl - Optional Axiom edge origin used by version-one endpoints.
+ * @throws When the account method, secret, or edge origin is invalid.
+ */
+export function getAxiomApi(
+  account: AxiomResolvedAccount,
+  edgeUrl = AXIOM_API_ORIGIN,
+) {
+  if (account.connectionMethodId !== "api-token") {
+    throw new Error(
+      `Unsupported Axiom connection method: ${account.connectionMethodId}`,
+    )
+  }
+  const { apiKey } = AXIOM_SECRET_SCHEMA.parse(account.secret)
+  const edgeOrigin = validateAxiomOrigin(edgeUrl)
+
+  /**
+   * Sends one authenticated request and validates its response.
+   *
+   * @param path - Relative Axiom API path.
+   * @param options - Request and response-validation options.
+   * @throws {AxiomApiError} When Axiom returns an unsuccessful response.
+   */
+  async function request<TSchema extends z.ZodType>(
+    path: string,
+    options: AxiomRequestOptions<TSchema>,
+  ): Promise<z.output<TSchema>> {
+    const version = options.version ?? "v2"
+    const url = confinedUrl(
+      version === "v1" ? edgeOrigin : AXIOM_API_ORIGIN,
+      version,
+      path,
+    )
+    for (const [name, value] of Object.entries(options.query ?? {})) {
+      if (value !== undefined) url.searchParams.set(name, String(value))
+    }
+
+    const response = await fetch(url, {
+      body:
+        options.body === undefined
+          ? undefined
+          : JSON.stringify(encodableSchema.parse(options.body)),
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        ...(options.body === undefined
+          ? {}
+          : { "Content-Type": "application/json" }),
+        ...options.headers,
+      },
+      method: options.method ?? "GET",
+      redirect: "manual",
+    })
+    const parsed = parseResponse(await response.text())
+    if (!response.ok || response.status >= 300) {
+      throw new AxiomApiError({
+        details: parsed,
+        ingestLimitReset: parseFiniteNumber(
+          response.headers.get("X-IngestLimit-Reset"),
+        ),
+        queryLimitReset: parseFiniteNumber(
+          response.headers.get("X-QueryLimit-Reset"),
+        ),
+        rateLimitReset: parseFiniteNumber(
+          response.headers.get("X-RateLimit-Reset"),
+        ),
+        retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+        status: response.status,
+      })
+    }
+    return options.responseSchema.parse(parsed)
+  }
+
+  return { request }
+}
+
+/**
+ * Restricts edge traffic to Axiom-owned HTTPS origins on the standard port.
+ *
+ * @param value - Candidate edge URL.
+ * @throws {TypeError} When the URL is not a confined Axiom HTTPS origin.
+ */
+export function validateAxiomOrigin(value: string) {
+  const url = new URL(value)
+  const isAxiomHost =
+    url.hostname === "api.axiom.co" || url.hostname.endsWith(".edge.axiom.co")
+  if (
+    url.protocol !== "https:" ||
+    url.port !== "" ||
+    !isAxiomHost ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new TypeError(
+      "Axiom edge URLs must use api.axiom.co or an HTTPS *.edge.axiom.co host.",
+    )
+  }
+  return url.origin
+}
+
+/**
+ * Resolves a relative path below one confined API-version root.
+ *
+ * @param origin - Validated Axiom origin.
+ * @param version - API version path segment.
+ * @param path - Relative request path.
+ * @throws {TypeError} When the path escapes its API-version root.
+ */
+function confinedUrl(origin: string, version: "v1" | "v2", path: string) {
+  const normalizedPath = path.replace(/^\/+/, "")
+  if (
+    !normalizedPath ||
+    normalizedPath.includes("://") ||
+    normalizedPath.includes("\\")
+  ) {
+    throw new TypeError("Axiom API paths must be relative.")
+  }
+  const root = new URL(`/${version}/`, origin)
+  const url = new URL(normalizedPath, root)
+  if (url.origin !== root.origin || !url.pathname.startsWith(root.pathname)) {
+    throw new TypeError("Axiom API paths must remain below their API version.")
+  }
+  return url
+}
+
+/**
+ * Parses an Axiom response into an encodable value.
+ *
+ * @param text - Raw response body.
+ */
+function parseResponse(text: string): Encodable {
+  if (!text) return null
+  try {
+    return encodableSchema.parse(JSON.parse(text))
+  } catch {
+    return { response: text }
+  }
+}
+
+/**
+ * Parses a finite numeric response header.
+ *
+ * @param value - Raw header value.
+ */
+function parseFiniteNumber(value: string | null) {
+  if (value === null) return undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+/**
+ * Parses a Retry-After header into seconds.
+ *
+ * @param value - Raw header value.
+ */
+function parseRetryAfter(value: string | null) {
+  if (value === null) return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds)) return seconds
+  const timestamp = Date.parse(value)
+  return Number.isFinite(timestamp)
+    ? Math.max(0, Math.ceil((timestamp - Date.now()) / 1_000))
+    : undefined
+}
+
+/**
+ * Checks whether an encodable value is a plain object.
+ *
+ * @param value - Value to inspect.
+ */
+function isPlainObject(value: Encodable): value is Record<string, Encodable> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  )
+}

package/src/axiom/events.ts

@@ -0,0 +1,31 @@
+import * as z from "zod"
+import { AXIOM_ID_SCHEMA, AXIOM_MONITOR_NOTIFICATION_SCHEMA } from "./schemas"
+
+export const AXIOM_TRIGGER_CONFIG_SCHEMA = z.object({
+  monitorId: AXIOM_ID_SCHEMA,
+})
+
+export const AXIOM_MONITOR_OPENED_SCHEMA =
+  AXIOM_MONITOR_NOTIFICATION_SCHEMA.extend({
+    action: z.literal("Open"),
+  })
+
+export const AXIOM_MONITOR_CLOSED_SCHEMA =
+  AXIOM_MONITOR_NOTIFICATION_SCHEMA.extend({
+    action: z.literal("Closed"),
+  })
+
+export const axiomTriggerContracts = {
+  "axiom.monitorNotification": {
+    configSchema: AXIOM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AXIOM_MONITOR_NOTIFICATION_SCHEMA,
+  },
+  "axiom.monitorOpened": {
+    configSchema: AXIOM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AXIOM_MONITOR_OPENED_SCHEMA,
+  },
+  "axiom.monitorClosed": {
+    configSchema: AXIOM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AXIOM_MONITOR_CLOSED_SCHEMA,
+  },
+} as const

package/src/axiom/index.ts

@@ -0,0 +1,3 @@
+export * from "./api"
+export * from "./events"
+export * from "./schemas"