@amos.com/node

Amos

A typed Node.js client for the Amos Pay API, generated from the OpenAPI spec with openapi-typescript and powered by openapi-fetch.

Docs: the full Amos API reference lives at docs.amos.com. This package is the typed Node.js binding for that API.

Installation

npm install @amos.com/node

Quick start

import {
  createPayApiClient,
  PAY_API_BASE_URL_PRODUCTION,
  PAY_API_VERSION,
} from "@amos.com/node";

const pay = createPayApiClient({
  baseUrl: PAY_API_BASE_URL_PRODUCTION,
  headers: {
    "X-Api-Key": process.env.AMOS_API_KEY!,
    "X-Api-Version": PAY_API_VERSION,
  },
});

const { data, error } = await pay.POST("/customers", {
  body: { customer: { email: "alex@example.com" } },
});

if (error) {
  console.error(error);
} else {
  console.log(data);
}

Sandbox mode

Swap the base URL constant:

import {
  createPayApiClient,
  PAY_API_BASE_URL_SANDBOX,
  PAY_API_VERSION,
} from "@amos.com/node";

const pay = createPayApiClient({
  baseUrl: PAY_API_BASE_URL_SANDBOX,
  headers: {
    "X-Api-Key": process.env.AMOS_API_KEY!,
    "X-Api-Version": PAY_API_VERSION,
  },
});

Custom base URL or fetch

createPayApiClient accepts any of openapi-fetch's ClientOptions, so you can point at a proxy or supply your own fetch:

const pay = createPayApiClient({
  baseUrl: "https://my-proxy.example.com",
  fetch: customFetchImpl,
  headers: {
    "X-Api-Key": process.env.AMOS_API_KEY!,
    "X-Api-Version": PAY_API_VERSION,
    "X-Trace-Id": "abc123",
  },
});

Middleware (e.g. fresh idempotency keys)

import type { Middleware } from "@amos.com/node";

const idempotencyKey: Middleware = {
  async onRequest({ request }) {
    if (request.method === "POST") {
      request.headers.set("Idempotency-Key", crypto.randomUUID());
    }
    return request;
  },
};

pay.use(idempotencyKey);

API surface

import {
  createPayApiClient,
  PAY_API_BASE_URL_PRODUCTION,
  PAY_API_BASE_URL_SANDBOX,
  PAY_API_VERSION,
} from "@amos.com/node";
import type { PayApiClient, ClientOptions, Middleware } from "@amos.com/node";

• createPayApiClient(options) — returns a typed openapi-fetch client. Exposes the full openapi-fetch interface: GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH, TRACE, use, eject.
• PAY_API_BASE_URL_PRODUCTION / PAY_API_BASE_URL_SANDBOX — base URLs for the two environments.
• PAY_API_VERSION — the wire-level X-Api-Version this build targets. Pass it as the X-Api-Version header on every request (most easily as a default in headers, as shown above).
• PayApiClient — the type returned by createPayApiClient.
• ClientOptions, Middleware — re-exported from openapi-fetch for convenience.

Types

All schema types are re-exported from the main entry. For example:

import type { components, paths, operations } from "@amos.com/node";

type Customer = components["schemas"]["Customer"];

Versioning

We follow SemVer for the npm package, with one extra rule: the major version tracks the wire-level X-Api-Version header.

npm range	X-Api-Version it targets
@amos.com/node@1.x	1
@amos.com/node@2.x	2 (hypothetical)

So bumping PAY_API_VERSION is always a major release, and consumers who pin to @amos.com/node@^1 know they will never be transparently upgraded onto a new wire contract.

The mental rule for bumps: "would a program that typechecked against the previous dist/index.d.ts still typecheck against the new one?" If no, it's a major.

Pre-1.0 caveat. While we're on 0.x, breaking changes can land in any 0.x release. Strict SemVer (and the API-version-tracks-major rule above) starts the day we cut 1.0.0. Pin to an exact 0.x.y if you need stability today.