postio-integrations

Name: Postio
Author: postio-uk

The JS-family npm packages, the AI / agent surface, and the cdn.postio.co.uk Worker that powers Postio's browser drop-in.

The Postio API + OpenAPI spec live in postio-uk/postio-api. The spec is also published as @postio/openapi.

Packages

Package	What it is
`@postio/api-types`	TypeScript types generated from the OpenAPI spec.
`@postio/core`	Runtime-agnostic typed client (browser / Node / Workers / Bun / Deno).
`@postio/node`	Node SDK on top of `core` — retries with exponential backoff, structured logger hook.
`@postio/postman-collection`	Postman v2.1 collection for every endpoint.
`@postio/address-finder`	Browser address autocomplete — ARIA combobox, themable, framework-agnostic source.
`@postio/address-finder-bundled`	The same component prebuilt for `<script>` tag use.
`@postio/react`	React hooks + `<AddressFinder />` component, TanStack Query under the hood.
`@postio/mcp`	Model Context Protocol server — `npx -y @postio/mcp` for Claude Desktop / Cursor / Windsurf / Zed.

Layout

packages/         pnpm workspace; one publishable npm package per subdir
ai/               AI / agent surface (Claude Skill, GPT Action, recommendation prompts)
cdn-worker/       Cloudflare Worker that serves the address-finder bundles
.github/workflows/  CI for publishing + deploying

Building

cd packages
pnpm install
pnpm -r run build

Each package builds independently (pnpm -F @postio/<name> run build). The address-finder bundle has a topological-build quirk — use the ... suffix so its workspace dep builds first:

pnpm -F "@postio/address-finder-bundled..." run build

Contributing

PRs welcome. Conventions:

Node 22+, pnpm 10+, ESM only, MIT-licensed.
stage is the working branch; master deploys / publishes via CI.
One package change per PR where possible.
Versions on each package are independent SemVer; bump the version in package.json when you intend a release.

The full integration index — including the server SDKs in their own repos and the WordPress plugin — lives at postio.co.uk/integrations.