@ityph/api-client

A typed HTTP client for the superapp's external API (apps/superapp/src/app/api/external/**), generated from the committed public OpenAPI spec (apps/superapp/openapi/external.public.json) and built on openapi-fetch.

import { createApiClient } from "@ityph/api-client";

const client = createApiClient({
  baseUrl: "https://serendra.ity.ph",
  apiKey: process.env.SUPERAPP_API_KEY!,
});

const { data, error } = await client.POST("/api/external/notifications/send", {
  body: {
    unitId: "unit-101",
    title: "Package arrived",
    subtitle: "Your package is ready for pickup.",
  },
});

if (error) {
  // `error` is typed as the ADR 0025 external-API error body:
  // { success: false; error: string; code: string; details?: unknown[] }
  throw new Error(`${error.code}: ${error.error}`);
}

createApiClient wraps openapi-fetch's createClient<paths>() and sets the x-api-key header (the spec's ApiKeyAuth security scheme) on every request. Pass fetch to inject a custom implementation, mainly for tests.

The package also re-exports the generated paths/components types and the derived ExternalApiError type, and ships the spec itself at the @ityph/api-client/openapi.json subpath so non-TypeScript backends can generate their own client from it.

The package is an ES module. Its published exports carry a default condition beside import, so CommonJS require() and tsx resolve it; require() of an ES module needs Node 20.19 / 22.12 or newer.

Generated code — never hand-edit

Everything under src/generated/ and the committed openapi.json are generated from apps/superapp/openapi/external.public.json (the internal spec, apps/superapp/openapi/external.internal.json, is never used here). Do not hand-edit either file — regenerate them instead:

pnpm --filter @ityph/api-client run generate
# or, from the repo root:
pnpm run api-client:generate

pnpm --filter @ityph/api-client run check (or pnpm run api-client:check from the repo root) regenerates in memory and fails if the committed openapi.json or src/generated/external.ts have drifted from the current spec — the CI gate, mirroring the superapp's own pnpm openapi:check.

Releasing @ityph/api-client

Same Changesets pipeline as @ityph/bridge (.changeset/config.json) — see libs/bridge/README.md's "Releasing" section for the mechanics. The package version tracks the spec's own version (major for major); it can also release its own minor and patch fixes independently of a spec change.