@axivoy/api 0.0.0 → 1.0.0

package/README.md

@@ -1,5 +1,19 @@
 # @axivoy/api
 
-This 0.0.0 version only reserves the package name. Install 1.0.0 or later for the typed Axivoy API client.
+Typed client for the [Axivoy API](https://app.axivoy.ai/developers): every published operation, webhook payload types, refusals as errors and webhook signature checks. Generated from the public OpenAPI reference; no runtime dependencies.
 
-Documentation: https://app.axivoy.ai/developers
+```typescript
+import { clientCredentials, createAxivoyClient } from '@axivoy/api';
+
+const axivoy = createAxivoyClient({
+  token: clientCredentials({ clientId: process.env.AXIVOY_CLIENT_ID!, clientSecret: process.env.AXIVOY_CLIENT_SECRET! }),
+});
+
+const page = await axivoy.call('loads.list', { limit: 25 });
+```
+
+Guide: [Client libraries](https://app.axivoy.ai/developers/guides/client-libraries). Node 20+, Deno, Bun and browsers.
+
+## Maintainers
+
+Source lives in the Axivoy TMS repository under `clients/typescript` and is released by the `client-libraries` workflow when the reference changes. `npm run generate` rebuilds `src/generated/schema.ts` from `docs/api/openapi-public.json`; `npm run build`, `npm test`; `npm run smoke` runs against a live install (see `scripts/smoke.mjs`).

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_TOKEN_URL = "https://app.axivoy.ai/oauth/token";
+export interface ClientCredentialsOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Defaults to `https://app.axivoy.ai/oauth/token`. */
+    tokenUrl?: string;
+    fetch?: typeof fetch;
+}
+/**
+ * A token source for an API key: exchanges its client ID and secret for an
+ * access token and reuses it until a minute before it expires.
+ */
+export declare function clientCredentials(options: ClientCredentialsOptions): () => Promise<string>;

package/dist/auth.js

@@ -0,0 +1,41 @@
+import { AxivoyError } from './errors.js';
+export const DEFAULT_TOKEN_URL = 'https://app.axivoy.ai/oauth/token';
+/**
+ * A token source for an API key: exchanges its client ID and secret for an
+ * access token and reuses it until a minute before it expires.
+ */
+export function clientCredentials(options) {
+    const fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+    let cached = null;
+    let pending = null;
+    const exchange = async () => {
+        const response = await fetcher(options.tokenUrl ?? DEFAULT_TOKEN_URL, {
+            method: 'POST',
+            headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'client_credentials',
+                client_id: options.clientId,
+                client_secret: options.clientSecret,
+            }).toString(),
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok || typeof body.access_token !== 'string') {
+            throw new AxivoyError(response.status, {
+                code: typeof body.error === 'string' ? body.error : 'token_failed',
+                message: typeof body.error_description === 'string' ? body.error_description : `Token request failed with HTTP ${response.status}.`,
+            });
+        }
+        const lifetime = typeof body.expires_in === 'number' ? body.expires_in : 3600;
+        cached = { token: body.access_token, expiresAt: Date.now() + Math.max(0, lifetime - 60) * 1000 };
+        return body.access_token;
+    };
+    return async () => {
+        if (cached !== null && Date.now() < cached.expiresAt) {
+            return cached.token;
+        }
+        pending ??= exchange().finally(() => {
+            pending = null;
+        });
+        return pending;
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+import type { paths } from './generated/schema.js';
+type OperationPath = Extract<keyof paths, `/ops/${string}`>;
+/** Every operation key the public reference publishes, such as `loads.list`. */
+export type OperationKey = OperationPath extends `/ops/${infer Key}` ? Key : never;
+type Post<K extends OperationKey> = paths[`/ops/${K}`] extends {
+    post: infer P;
+} ? P : never;
+/** The JSON body an operation takes. */
+export type OperationInput<K extends OperationKey> = Post<K> extends {
+    requestBody?: {
+        content: {
+            'application/json': infer Body;
+        };
+    };
+} ? Body : Record<string, never>;
+/** The `result` an operation answers with. */
+export type OperationResult<K extends OperationKey> = Post<K> extends {
+    responses: {
+        200: {
+            content: {
+                'application/json': {
+                    result: infer Result;
+                };
+            };
+        };
+    };
+} ? Result : unknown;
+/** The dry-run answer: what would happen, with nothing written. */
+export interface DryRunResult {
+    outcome: 'would_run' | 'would_propose';
+    input: Record<string, unknown>;
+    simulation?: unknown;
+}
+export type TokenSource = string | (() => string | Promise<string>);
+export interface AxivoyClientOptions {
+    /** An access token, or a function returning a fresh one (OAuth or client credentials). */
+    token: TokenSource;
+    /** Defaults to `https://api.axivoy.ai/v1`. */
+    baseUrl?: string;
+    /** Retries after a network error, 429, 409 `in_flight` or 5xx. Defaults to 3. */
+    maxRetries?: number;
+    /** Replace `fetch` (tests, proxies). */
+    fetch?: typeof fetch;
+}
+export interface CallOptions {
+    /** Same key and body replays the first answer. Generated per call when omitted, and kept across retries. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export declare const DEFAULT_BASE_URL = "https://api.axivoy.ai/v1";
+export declare class AxivoyClient {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly fetcher;
+    constructor(options: AxivoyClientOptions);
+    /**
+     * Runs one operation. Resolves with its `result`; rejects with
+     * `AxivoyError` when refused and `AxivoyProposal` when sent for approval.
+     */
+    call<K extends OperationKey>(key: K, input?: OperationInput<K>, options?: CallOptions): Promise<OperationResult<K>>;
+    /** Validates and authorizes without running anything (`Axivoy-Dry-Run`). */
+    dryRun<K extends OperationKey>(key: K, input?: OperationInput<K>, options?: CallOptions): Promise<DryRunResult>;
+    private post;
+    private token;
+}
+export declare function createAxivoyClient(options: AxivoyClientOptions): AxivoyClient;
+export {};

package/dist/client.js

@@ -0,0 +1,93 @@
+import { AxivoyError, AxivoyProposal } from './errors.js';
+export const DEFAULT_BASE_URL = 'https://api.axivoy.ai/v1';
+const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+export class AxivoyClient {
+    options;
+    baseUrl;
+    maxRetries;
+    fetcher;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.maxRetries = options.maxRetries ?? 3;
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Runs one operation. Resolves with its `result`; rejects with
+     * `AxivoyError` when refused and `AxivoyProposal` when sent for approval.
+     */
+    async call(key, input, options = {}) {
+        const body = await this.post(key, input, options, false);
+        return body.result;
+    }
+    /** Validates and authorizes without running anything (`Axivoy-Dry-Run`). */
+    async dryRun(key, input, options = {}) {
+        const body = await this.post(key, input, options, true);
+        return body.dry_run;
+    }
+    async post(key, input, options, dryRun) {
+        const idempotencyKey = options.idempotencyKey ?? globalThis.crypto.randomUUID();
+        const payload = JSON.stringify(input ?? {});
+        for (let attempt = 0;; attempt++) {
+            const headers = {
+                Authorization: `Bearer ${await this.token()}`,
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                'Idempotency-Key': idempotencyKey,
+            };
+            if (dryRun) {
+                headers['Axivoy-Dry-Run'] = 'true';
+            }
+            let response;
+            try {
+                response = await this.fetcher(`${this.baseUrl}/ops/${encodeURIComponent(key)}`, {
+                    method: 'POST',
+                    headers,
+                    body: payload,
+                    signal: options.signal,
+                });
+            }
+            catch (error) {
+                if (options.signal?.aborted || attempt >= this.maxRetries) {
+                    throw error;
+                }
+                await sleep(backoff(attempt));
+                continue;
+            }
+            const body = (await response.json().catch(() => ({})));
+            if (response.status === 200) {
+                return body;
+            }
+            if (response.status === 202 && body.proposal) {
+                throw new AxivoyProposal(body.proposal);
+            }
+            const error = (body.error ?? { code: 'unexpected', message: `HTTP ${response.status}` });
+            const retryable = RETRY_STATUSES.has(response.status) || (response.status === 409 && error.reason === 'in_flight');
+            if (!retryable || attempt >= this.maxRetries) {
+                throw new AxivoyError(response.status, error);
+            }
+            await sleep(retryAfter(response) ?? backoff(attempt));
+        }
+    }
+    async token() {
+        const source = this.options.token;
+        return typeof source === 'function' ? await source() : source;
+    }
+}
+export function createAxivoyClient(options) {
+    return new AxivoyClient(options);
+}
+function backoff(attempt) {
+    return Math.min(8000, 500 * 2 ** attempt) + Math.floor(Math.random() * 250);
+}
+function retryAfter(response) {
+    const header = response.headers.get('Retry-After');
+    if (header === null) {
+        return null;
+    }
+    const seconds = Number(header);
+    return Number.isFinite(seconds) ? Math.min(60_000, seconds * 1000) : null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/** The `error` body every refused call answers with. */
+export interface AxivoyErrorBody {
+    code: string;
+    reason?: string;
+    message: string;
+    fields?: Record<string, string[]>;
+}
+/** A refused call: `status` is the HTTP status, `code` the stable refusal code. */
+export declare class AxivoyError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly reason: string | undefined;
+    readonly fields: Record<string, string[]>;
+    constructor(status: number, body: AxivoyErrorBody);
+}
+/** The proposal envelope: nothing ran yet; a person approves it in Axivoy. */
+export interface ProposalBody {
+    id: string;
+    status: 'proposed';
+    approval_url?: string;
+    message: string;
+}
+/**
+ * Thrown when a write was sent for approval (HTTP 202). Check its outcome
+ * later with `approvals.list` and `proposal_id`.
+ */
+export declare class AxivoyProposal extends Error {
+    readonly id: string;
+    readonly approvalUrl: string | undefined;
+    constructor(body: ProposalBody);
+}

package/dist/errors.js

@@ -0,0 +1,29 @@
+/** A refused call: `status` is the HTTP status, `code` the stable refusal code. */
+export class AxivoyError extends Error {
+    status;
+    code;
+    reason;
+    fields;
+    constructor(status, body) {
+        super(body.message);
+        this.name = 'AxivoyError';
+        this.status = status;
+        this.code = body.code;
+        this.reason = body.reason;
+        this.fields = body.fields ?? {};
+    }
+}
+/**
+ * Thrown when a write was sent for approval (HTTP 202). Check its outcome
+ * later with `approvals.list` and `proposal_id`.
+ */
+export class AxivoyProposal extends Error {
+    id;
+    approvalUrl;
+    constructor(body) {
+        super(body.message);
+        this.name = 'AxivoyProposal';
+        this.id = body.id;
+        this.approvalUrl = body.approval_url;
+    }
+}