@automate.ax/integration-contracts 0.125.0 → 0.127.0

package/dist/axiom/api.d.ts

@@ -0,0 +1,60 @@
+import { type Encodable } from "@automate.ax/codec";
+import * as z from "zod";
+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 declare 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;
+    });
+}
+/**
+ * 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 declare function getAxiomApi(account: AxiomResolvedAccount, edgeUrl?: string): {
+    request: <TSchema extends z.ZodType>(path: string, options: AxiomRequestOptions<TSchema>) => Promise<z.output<TSchema>>;
+};
+/**
+ * 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 declare function validateAxiomOrigin(value: string): string;

package/dist/axiom/api.js

@@ -0,0 +1,192 @@
+import { encodableSchema } 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) });
+/** Structured Axiom REST error. */
+export class AxiomApiError extends Error {
+    details;
+    ingestLimitReset;
+    queryLimitReset;
+    rateLimitReset;
+    retryAfter;
+    status;
+    /**
+     * 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) {
+        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, 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(path, options) {
+        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) {
+    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, version, path) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}

package/dist/axiom/events.d.ts

@@ -0,0 +1,104 @@
+import * as z from "zod";
+export declare const AXIOM_TRIGGER_CONFIG_SCHEMA: z.ZodObject<{
+    monitorId: z.ZodString;
+}, z.core.$strip>;
+export declare const AXIOM_MONITOR_OPENED_SCHEMA: z.ZodObject<{
+    event: z.ZodObject<{
+        body: z.ZodString;
+        description: z.ZodString;
+        groupKeys: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        groupValues: z.ZodNullable<z.ZodArray<z.ZodJSONSchema>>;
+        matchedEvent: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        monitorId: z.ZodString;
+        queryEndTime: z.ZodString;
+        queryStartTime: z.ZodString;
+        timestamp: z.ZodString;
+        title: z.ZodString;
+        value: z.ZodNumber;
+    }, z.core.$strip>;
+    action: z.ZodLiteral<"Open">;
+}, z.core.$strip>;
+export declare const AXIOM_MONITOR_CLOSED_SCHEMA: z.ZodObject<{
+    event: z.ZodObject<{
+        body: z.ZodString;
+        description: z.ZodString;
+        groupKeys: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        groupValues: z.ZodNullable<z.ZodArray<z.ZodJSONSchema>>;
+        matchedEvent: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        monitorId: z.ZodString;
+        queryEndTime: z.ZodString;
+        queryStartTime: z.ZodString;
+        timestamp: z.ZodString;
+        title: z.ZodString;
+        value: z.ZodNumber;
+    }, z.core.$strip>;
+    action: z.ZodLiteral<"Closed">;
+}, z.core.$strip>;
+export declare const axiomTriggerContracts: {
+    readonly "axiom.monitorNotification": {
+        readonly configSchema: z.ZodObject<{
+            monitorId: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            action: z.ZodEnum<{
+                Closed: "Closed";
+                Open: "Open";
+            }>;
+            event: z.ZodObject<{
+                body: z.ZodString;
+                description: z.ZodString;
+                groupKeys: z.ZodNullable<z.ZodArray<z.ZodString>>;
+                groupValues: z.ZodNullable<z.ZodArray<z.ZodJSONSchema>>;
+                matchedEvent: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+                monitorId: z.ZodString;
+                queryEndTime: z.ZodString;
+                queryStartTime: z.ZodString;
+                timestamp: z.ZodString;
+                title: z.ZodString;
+                value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    };
+    readonly "axiom.monitorOpened": {
+        readonly configSchema: z.ZodObject<{
+            monitorId: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            event: z.ZodObject<{
+                body: z.ZodString;
+                description: z.ZodString;
+                groupKeys: z.ZodNullable<z.ZodArray<z.ZodString>>;
+                groupValues: z.ZodNullable<z.ZodArray<z.ZodJSONSchema>>;
+                matchedEvent: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+                monitorId: z.ZodString;
+                queryEndTime: z.ZodString;
+                queryStartTime: z.ZodString;
+                timestamp: z.ZodString;
+                title: z.ZodString;
+                value: z.ZodNumber;
+            }, z.core.$strip>;
+            action: z.ZodLiteral<"Open">;
+        }, z.core.$strip>;
+    };
+    readonly "axiom.monitorClosed": {
+        readonly configSchema: z.ZodObject<{
+            monitorId: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            event: z.ZodObject<{
+                body: z.ZodString;
+                description: z.ZodString;
+                groupKeys: z.ZodNullable<z.ZodArray<z.ZodString>>;
+                groupValues: z.ZodNullable<z.ZodArray<z.ZodJSONSchema>>;
+                matchedEvent: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+                monitorId: z.ZodString;
+                queryEndTime: z.ZodString;
+                queryStartTime: z.ZodString;
+                timestamp: z.ZodString;
+                title: z.ZodString;
+                value: z.ZodNumber;
+            }, z.core.$strip>;
+            action: z.ZodLiteral<"Closed">;
+        }, z.core.$strip>;
+    };
+};

package/dist/axiom/events.js

@@ -0,0 +1,25 @@
+import * as z from "zod";
+import { AXIOM_ID_SCHEMA, AXIOM_MONITOR_NOTIFICATION_SCHEMA } from "./schemas.js";
+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,
+    },
+};

package/dist/axiom/index.d.ts

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

package/dist/axiom/index.js

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