Pam Ordo contracts

The versioned OpenAPI contract, generated TypeScript types, and shared fixtures for Pam Ordo APIs.

Install

Pin consumers to an exact npm version:

{
  "dependencies": {
    "@pam-ai/pam-ordo-contracts": "3.20.0"
  }
}

import type {
  ConversationDetailResponse,
  InboxListResponse,
  NotificationDisplayContext,
  NotificationListResponse,
  DismissNotificationsCommand,
  DismissNotificationsResult,
  CommandResult,
  ErrorEnvelope,
  paths,
} from '@pam-ai/pam-ordo-contracts';

Notification reads may include the optional InboxNotification.displayContext. When present, NotificationDisplayContext always contains customerName, actorName, repairOrderNumber, commentExcerpt, and context; the latter four values are either an authorized HydratedText or null when that context is not applicable. A relevant but unavailable or withheld source is represented by HydratedText.availability, not by null. Consumers should render availability and use the existing title/body fallback when the context object is absent.

POST /v1/inbox/commands/dismiss-notifications implements Clear all for the authenticated recipient. The initial DismissNotificationsCommand omits cursor; the server fixes the action boundary and returns a stable informational cutoff. Each nextCursor continuation uses a new operation ID, and repeating the same request replays its DismissNotificationsResult. Cursors are opaque, recipient/rooftop-bound, and nextCursor: null means the fixed snapshot is complete. The response counts are for that page only; notifications created after the cutoff remain eligible for a later read.

FIFO producers also import ProducerCommandV1 plus the deterministic producerMessageGroupId, producerMessageDeduplicationId, and producerMessageAttributes helpers. The helpers keep every producer aligned with the ordered-consumer contract without introducing an AWS SDK dependency.

Policy and authority consumers import InboxPolicyV1, InboxTargetResolutionRequestV1, and InboxTargetResolutionResponseV1. Use inboxPolicyVersion to derive the immutable sha256: policy snapshot ID from canonical normalized policy content. InboxPolicyV1 intentionally rejects legacy timed-escalation fields.

Conversation AI consumers import ConversationAiSnapshotV1. It is a replace-in-place snapshot keyed by rooftop and canonical Customer identity; it is not a source-of-truth Interaction record or a version-history API.

Reach out consumers use CreateInboxCustomerCommand for an explicit create-only Customer request and SendInboxMessageCommand for the Conversation-aware Telnyx SMS operation. Directory reads, Customer creation, calls, and messages remain separate capabilities; a consumer must never infer one grant from another.

The public npm artifact contains compiled TypeScript declarations, bundled OpenAPI, and shared fixtures. Consumers do not need GitHub repository credentials.

New DASH-273 verification runners must use the canonical v2 manifest exported at @pam-ai/pam-ordo-contracts/fixtures/dash-273/manifest.v2.json with manifest.v2.schema.json. Resolve each shared command fixture relative to the manifest file. The v2 manifest records exact command and FIFO identities, the truthful starting boundary, and whether coverage is projection-only, producer-only, or consumer-only. Conflict references are typed as { "kind": "command" | "step", "id": "..." }; command IDs resolve against the global command catalog and step IDs resolve within their scenario.

The original manifest.json and manifest.schema.json exports remain byte-for-byte compatible with published 3.10.1 for legacy readers. They retain ambiguous string conflict references and must not be used by new runners that validate conflict semantics.

Contract development

openapi/openapi.yaml is the source of truth. Bundled JSON and generated TypeScript are committed for review.

npm install
npm run contract:generate
npm run check
npm pack --dry-run

Quality commands

The repository follows the dashboard conventions for linting, formatting, and dependency auditing:

npm run lint
npm run lint:fix
npm run format
npm run format:check
npm run npm-audit

Generated TypeScript and bundled OpenAPI are excluded from ESLint and Prettier; their generators enforce deterministic output. CI uses Pam's shared lint and audit actions.

Breaking changes require a major version bump:

npm run contract:breaking -- --base <full-base-commit-sha>

Follow docs/PUBLISHING.md to publish an immutable npm version and matching Git tag. Consumers should pin the exact npm version.