@rkt-tools/contracts

The pure, shared ingestion-envelope contract for the rkt-comms monorepo: the Zod schemas and inferred types that describe the POST /ingest/event payloads. Both the Core (packages/crm) and the Mac bridge (packages/imap-mcp) import it, so the wire contract is authored once instead of hand-mirrored across the two packages.

• Pure. Types/schemas only — no I/O, no Node API, the sole runtime dependency is zod. It is a leaf in the dependency graph (it must import neither consumer; pnpm depcheck enforces this).
• Zod v4. Authored in v4 idiom (z.strictObject, z.iso.datetime, z.uuid).

Exports

| Export | What | | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | bridgeEnvelopeSchema | discriminated union over eventKind — what the Core parses | | imessageEnvelopeSchema / callEnvelopeSchema | the two standalone members — what the bridge validates against | | participantSchema, imessageSafeMetadataSchema, callSafeMetadataSchema, SAFE_METADATA_KEYS | building blocks | | parseBridgeEnvelope(value) | bridgeEnvelopeSchema.parse | | mailWebhookPayloadSchema, webhookMessageSchema, webhookRefSchema, webhookEventSchema | mail triage webhook wire + internal event shapes | | parseMailWebhookPayload(value) / parseWebhookEvent(value) | strict parsers for the mail webhook contract | | types: BridgeEnvelope (union), CoreEnvelope (iMessage member only, not the union), CallEnvelope, SafeMetadata | inferred | | types: MailWebhookPayload, WebhookMessage, WebhookRef, WebhookEvent, WebhookAttachment, WebhookThread | mail webhook inferred types |

Install

pnpm add @rkt-tools/contracts

Build & test

pnpm --filter @rkt-tools/contracts build      # tsc -p tsconfig.build.json → dist/ (emits .d.ts)
pnpm --filter @rkt-tools/contracts test       # golden-fixture contract guard
pnpm --filter @rkt-tools/contracts typecheck

Changing the wire contract

Edit src/envelope.ts and extend the golden fixtures in test/envelope.test.ts in the same commit. The fixtures (known-good must-parse, known-bad must-reject) are the regression guard that the contract can't silently loosen or tighten. The build must keep declaration: true (in tsconfig.build.json) or NodeNext consumers fail type resolution.