@airfone/api 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AirFone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @airfone/api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for the AirFone API. The types are generated from the public contract
+(`backend/openapi/airfone-v1.yaml`), so a path, its parameters, its body and its response are checked
+by the compiler.
+
+## Install
+
+```sh
+npm install @airfone/api
+```
+
+## Use
+
+```ts
+import { createClient } from '@airfone/api';
+
+const airfone = createClient({ token: process.env.AIRFONE_KEY! }); // af_sk_... or afp_...
+
+const page = await airfone.get('/v1/agents', { query: { limit: 20 } });
+await airfone.post('/v1/messages', { body: { /* typed from the contract */ }, idempotencyKey: crypto.randomUUID() });
+```
+
+Errors are thrown as `AirFoneError` with `status`, `code`, `message` and `requestId`.
+
+`paths`, `components` and `operations` are exported as types, for code that wants the contract's
+shapes without the client.
+
+## Regenerate the types
+
+```sh
+pnpm --filter @airfone/api generate
+```
+
+CI regenerates them and fails when `src/schema.d.ts` is not what the contract produces.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import type { paths } from './schema.js';
+export type { paths, components, operations } from './schema.js';
+type Method = 'get' | 'post' | 'put' | 'patch' | 'delete';
+type Op<P extends keyof paths, M extends Method> = M extends keyof paths[P] ? NonNullable<paths[P][M]> : never;
+type Json<T> = T extends {
+    content: {
+        'application/json': infer B;
+    };
+} ? B : undefined;
+type Ok<O> = O extends {
+    responses: infer R;
+} ? Json<R[Extract<keyof R, 200 | 201 | 202 | '200' | '201' | '202'>]> : never;
+type Body<O> = O extends {
+    requestBody?: infer B;
+} ? Json<NonNullable<B>> : undefined;
+type Params<O> = O extends {
+    parameters: infer P;
+} ? P : never;
+export interface ClientOptions {
+    /** A secret or restricted key (`af_sk_…`) or a personal access token (`afp_…`). */
+    token: string;
+    /** Defaults to https://app.airfone.app. */
+    baseUrl?: string;
+    /** Pins the API version (`AirFone-Version`). */
+    version?: string;
+    fetch?: typeof fetch;
+}
+/** An error the API answered with: `{ error: { code, message } }`. */
+export declare class AirFoneError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string | undefined);
+}
+/** What a request can carry besides its path. */
+export interface RequestInit<P extends keyof paths, M extends Method> {
+    path?: Record<string, string>;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: Body<Op<P, M>>;
+    idempotencyKey?: string;
+}
+type Verb<M extends Method> = <P extends keyof paths & string>(path: P, init?: RequestInit<P, M>) => Promise<Ok<Op<P, M>>>;
+export interface Client {
+    get: Verb<'get'>;
+    post: Verb<'post'>;
+    put: Verb<'put'>;
+    patch: Verb<'patch'>;
+    delete: Verb<'delete'>;
+}
+export declare function createClient(options: ClientOptions): Client;
+export type { Params };

package/dist/index.js

@@ -0,0 +1,48 @@
+/** An error the API answered with: `{ error: { code, message } }`. */
+export class AirFoneError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(status, code, message, requestId) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.name = 'AirFoneError';
+    }
+}
+export function createClient(options) {
+    const base = (options.baseUrl ?? 'https://app.airfone.app').replace(/\/$/, '');
+    const doFetch = options.fetch ?? fetch;
+    async function call(method, path, init = {}) {
+        let url = path.replace(/\{(\w+)\}/g, (_, k) => encodeURIComponent(init.path?.[k] ?? ''));
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(init.query ?? {}))
+            if (v !== undefined)
+                q.set(k, String(v));
+        if ([...q].length)
+            url += `?${q}`;
+        const headers = { Authorization: `Bearer ${options.token}`, Accept: 'application/json' };
+        if (options.version)
+            headers['AirFone-Version'] = options.version;
+        if (init.idempotencyKey)
+            headers['Idempotency-Key'] = init.idempotencyKey;
+        if (init.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const res = await doFetch(base + url, { method: method.toUpperCase(), headers, body: init.body === undefined ? undefined : JSON.stringify(init.body) });
+        const text = await res.text();
+        const data = text ? JSON.parse(text) : undefined;
+        if (!res.ok) {
+            const e = data?.error ?? {};
+            throw new AirFoneError(res.status, e.code ?? 'error', e.message ?? res.statusText, res.headers.get('Request-Id') ?? undefined);
+        }
+        return data;
+    }
+    return {
+        get: (path, init) => call('get', path, init),
+        post: (path, init) => call('post', path, init),
+        put: (path, init) => call('put', path, init),
+        patch: (path, init) => call('patch', path, init),
+        delete: (path, init) => call('delete', path, init),
+    };
+}