@texakey/api-contracts

This repository is the single source of truth for shared API contracts across the NEEM Healthcare Platform. It is structured as a reusable TypeScript npm package and can be consumed through local file dependencies, monorepo workspaces, or npm as @texakey/api-contracts.

Architecture

• openapi/ stores versioned OpenAPI specifications for shared clinical, auth, identity/admin, patients, templates, audit logs, clinical notes, EHR, AI, portal, and admin APIs.
• src/generated/types/ contains OpenAPI-derived TypeScript contract types and stable type aliases.
• src/generated/orval/ contains raw Orval client output. Treat this directory as replaceable generator output.
• src/generated/clients/ contains stable wrapper clients for application imports.
• src/schemas/ contains hand-written Zod schemas for request validation, form validation, and shared domain validation.
• src/errors/ contains standardized error contracts shared by services and frontends.
• docs/versioning.md documents versioning, compatibility, breaking changes, and deprecation rules.

Generated code is separated from hand-written code so applications can depend on stable exports while contract generation evolves behind the scenes.

For a deeper onboarding guide, read docs/developer-handbook.md. For a contributor-focused map of how files connect, read docs/contributor-file-map.md. For a full curl-to-package worked example, read docs/contract-change-worked-example.md. For a junior-friendly folder-by-folder flow, read docs/repo-flow-for-juniors.md. For the general process when backend sends API contract updates, read docs/backend-contract-intake-flow.md. For how the NEEM AI product repo should consume these contracts, read docs/neem-ai-client-integration.md. For local and server environment setup, read docs/neem-ai-environments.md. For future Postman collection updates, follow docs/postman-update-runbook.md.

Install for Local Use

From another repository:

npm install ../path/to/neem-api-contracts

In a workspace:

{
  "workspaces": ["packages/*", "../neem-api-contracts"]
}

Usage

import { PatientSchema, createApiError } from "@texakey/api-contracts";
import type { Patient } from "@texakey/api-contracts";

const patient = PatientSchema.parse(input);
const error = createApiError(
  "permission.denied",
  "User cannot approve this draft",
);

Subpath exports are available for focused imports:

import { AppointmentRequestSchema } from "@texakey/api-contracts/schemas";
import {
  authClient,
  ehr1Client,
  identityAdminClient,
  patientClient,
} from "@texakey/api-contracts/generated/clients";
import type { Encounter } from "@texakey/api-contracts/generated/types";

Individual module subpaths are also exported when a consumer needs a narrower import:

import { authClient } from "@texakey/api-contracts/generated/clients/authClient";
import { LoginRequestSchema } from "@texakey/api-contracts/schemas/requests";

Code Generation Workflow

The repository includes example generation scripts:

npm run generate:types
npm run generate:clients
npm run generate
npm run check:generated

generate:types uses openapi-typescript against openapi/shared-clinical.yaml and writes src/generated/types/openapi.ts.

generate:clients uses orval.config.ts to generate raw fetch-based Orval clients under src/generated/orval/ for:

• ehr1
• ehr2
• ai
• portal
• admin
• auth
• identityAdmin
• patients
• templates
• auditLogs
• clinicalNotes
• sessions
• transcription

Stable package consumers should import from src/generated/clients/ through the package subpath exports. check:generated regenerates output and fails if generated files drift from the committed source.

Development

npm install
npm run typecheck
npm run lint
npm run test
npm run build

The package uses ESM, strict TypeScript, ESLint, Prettier, Vitest, barrel exports, and path aliases.

The TypeScript config intentionally avoids the deprecated baseUrl option. Path aliases use explicit relative targets instead.

npm Publishing

The package is scoped as @texakey/api-contracts and includes publishConfig.access = "public".

Use this exact flow before publishing a new version. Run it from a clean working tree so generated-code drift, version changes, and build output changes are easy to notice.

First, check the local version and the versions already published on npm:

npm pkg get version
npm view @texakey/api-contracts version
npm view @texakey/api-contracts versions --json

The local package.json version must not appear in the published npm versions list. npm versions are immutable, so a failed publish like You cannot publish over the previously published versions: 0.2.0 means the package needs a new version before retrying.

If the local version was already published, bump it before testing and publishing:

npm version patch --no-git-tag-version
npm version minor --no-git-tag-version
npm version major --no-git-tag-version

Use patch for docs, generated-code drift, or non-breaking fixes; minor for backward-compatible contract additions; and major for breaking contract changes. The --no-git-tag-version flag updates package.json and package-lock.json without creating a git commit or tag, so the release commit can include the version bump, generated files, and docs together.

Then run the full verification suite:

npm ci
npm run format:check
npm run lint
npm run typecheck
npm run test
npm run build
npm run check:generated
npm pack --dry-run

What each command proves:

• npm ci installs exactly the dependency versions from package-lock.json.
• npm run format:check confirms committed files match the Prettier rules.
• npm run lint catches JavaScript and TypeScript style or correctness issues.
• npm run typecheck verifies the TypeScript contract surface without writing build output.
• npm run test runs the Vitest test suite.
• npm run build compiles the package into dist/, which is what npm consumers receive.
• npm run check:generated regenerates OpenAPI and Orval output, then fails if src/generated is out of sync with committed files.
• npm pack --dry-run previews the files that would be included in the npm package without publishing anything.

Publish with:

npm login
npm whoami
npm publish --access public

After publishing, install it in the product repo:

cd /home/samuel/neem-ai-web
npm install @texakey/api-contracts @texakey/frontend-sdk

For the exact NEEM AI login handoff, follow docs/neem-ai-client-integration.md.