@rkt-tools/contracts 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @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`                                   |
+| types: `BridgeEnvelope` (union), `CoreEnvelope` (**iMessage member only**, not the union), `CallEnvelope`, `SafeMetadata` | inferred                                                       |
+
+## Build & test
+
+```bash
+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
+```
+
+Consumers build it deps-first on every build/deploy path via the trailing-`...` filter, e.g. `pnpm --filter "rkt-crm..." build`.
+
+## 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.
+
+## Consumption
+
+| Consumer                            | How                                                                                |
+| ----------------------------------- | ---------------------------------------------------------------------------------- |
+| **rkt-comms** (`crm`, `imap-mcp`)   | `"@rkt-tools/contracts": "workspace:*"` — no npm auth needed for local/Railway builds    |
+| **rkt-ship** (and other cross-repo) | `"@rkt-tools/contracts": "^0.1.0"` from public npm (`publishConfig.access: public`) |
+
+Release and registry runbook: [`docs/contracts-registry.md`](../../docs/contracts-registry.md). ADR: [`0033`](../../packages/crm/docs/adr/0033-rkt-contracts-npm-registry-consumption.md).

package/dist/envelope.d.ts

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+export declare const participantSchema: z.ZodObject<{
+    externalIdentityRef: z.ZodString;
+    role: z.ZodEnum<{
+        sender: "sender";
+        recipient: "recipient";
+        participant: "participant";
+        owner: "owner";
+    }>;
+}, z.core.$strict>;
+export declare const SAFE_METADATA_KEYS: readonly ["message_count", "inbound_count", "outbound_count", "participant_count", "service", "chat_kind", "has_attachments", "attachment_count", "reaction_only_count", "session_candidate_id", "source_schema_version"];
+export declare const imessageSafeMetadataSchema: z.ZodObject<{
+    message_count: z.ZodOptional<z.ZodNumber>;
+    inbound_count: z.ZodOptional<z.ZodNumber>;
+    outbound_count: z.ZodOptional<z.ZodNumber>;
+    participant_count: z.ZodOptional<z.ZodNumber>;
+    service: z.ZodOptional<z.ZodEnum<{
+        imessage: "imessage";
+        sms: "sms";
+    }>>;
+    chat_kind: z.ZodOptional<z.ZodEnum<{
+        dm: "dm";
+        group: "group";
+    }>>;
+    has_attachments: z.ZodOptional<z.ZodBoolean>;
+    attachment_count: z.ZodOptional<z.ZodNumber>;
+    reaction_only_count: z.ZodOptional<z.ZodNumber>;
+    session_candidate_id: z.ZodOptional<z.ZodString>;
+    source_schema_version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const callSafeMetadataSchema: z.ZodObject<{
+    call_seconds: z.ZodNumber;
+    call_service: z.ZodEnum<{
+        cellular: "cellular";
+        facetime_audio: "facetime_audio";
+        facetime_video: "facetime_video";
+    }>;
+    answered: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const imessageEnvelopeSchema: z.ZodObject<{
+    bridgeId: z.ZodString;
+    sourceEventId: z.ZodString;
+    occurredAt: z.ZodISODateTime;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+        mixed: "mixed";
+        unknown: "unknown";
+    }>;
+    isGroup: z.ZodBoolean;
+    payloadHash: z.ZodString;
+    backfillBatchId: z.ZodOptional<z.ZodUUID>;
+    watermarkRef: z.ZodOptional<z.ZodString>;
+    eventKind: z.ZodLiteral<"imessage.message">;
+    source: z.ZodLiteral<"imessage">;
+    conversationRef: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        externalIdentityRef: z.ZodString;
+        role: z.ZodEnum<{
+            sender: "sender";
+            recipient: "recipient";
+            participant: "participant";
+            owner: "owner";
+        }>;
+    }, z.core.$strict>>;
+    safeMetadata: z.ZodDefault<z.ZodObject<{
+        message_count: z.ZodOptional<z.ZodNumber>;
+        inbound_count: z.ZodOptional<z.ZodNumber>;
+        outbound_count: z.ZodOptional<z.ZodNumber>;
+        participant_count: z.ZodOptional<z.ZodNumber>;
+        service: z.ZodOptional<z.ZodEnum<{
+            imessage: "imessage";
+            sms: "sms";
+        }>>;
+        chat_kind: z.ZodOptional<z.ZodEnum<{
+            dm: "dm";
+            group: "group";
+        }>>;
+        has_attachments: z.ZodOptional<z.ZodBoolean>;
+        attachment_count: z.ZodOptional<z.ZodNumber>;
+        reaction_only_count: z.ZodOptional<z.ZodNumber>;
+        session_candidate_id: z.ZodOptional<z.ZodString>;
+        source_schema_version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const callEnvelopeSchema: z.ZodObject<{
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    bridgeId: z.ZodString;
+    sourceEventId: z.ZodString;
+    occurredAt: z.ZodISODateTime;
+    isGroup: z.ZodBoolean;
+    payloadHash: z.ZodString;
+    backfillBatchId: z.ZodOptional<z.ZodUUID>;
+    watermarkRef: z.ZodOptional<z.ZodString>;
+    eventKind: z.ZodLiteral<"call.event">;
+    source: z.ZodLiteral<"call_history">;
+    conversationRef: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        externalIdentityRef: z.ZodString;
+        role: z.ZodEnum<{
+            sender: "sender";
+            recipient: "recipient";
+            participant: "participant";
+            owner: "owner";
+        }>;
+    }, z.core.$strict>>;
+    safeMetadata: z.ZodObject<{
+        call_seconds: z.ZodNumber;
+        call_service: z.ZodEnum<{
+            cellular: "cellular";
+            facetime_audio: "facetime_audio";
+            facetime_video: "facetime_video";
+        }>;
+        answered: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const bridgeEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    bridgeId: z.ZodString;
+    sourceEventId: z.ZodString;
+    occurredAt: z.ZodISODateTime;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+        mixed: "mixed";
+        unknown: "unknown";
+    }>;
+    isGroup: z.ZodBoolean;
+    payloadHash: z.ZodString;
+    backfillBatchId: z.ZodOptional<z.ZodUUID>;
+    watermarkRef: z.ZodOptional<z.ZodString>;
+    eventKind: z.ZodLiteral<"imessage.message">;
+    source: z.ZodLiteral<"imessage">;
+    conversationRef: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        externalIdentityRef: z.ZodString;
+        role: z.ZodEnum<{
+            sender: "sender";
+            recipient: "recipient";
+            participant: "participant";
+            owner: "owner";
+        }>;
+    }, z.core.$strict>>;
+    safeMetadata: z.ZodDefault<z.ZodObject<{
+        message_count: z.ZodOptional<z.ZodNumber>;
+        inbound_count: z.ZodOptional<z.ZodNumber>;
+        outbound_count: z.ZodOptional<z.ZodNumber>;
+        participant_count: z.ZodOptional<z.ZodNumber>;
+        service: z.ZodOptional<z.ZodEnum<{
+            imessage: "imessage";
+            sms: "sms";
+        }>>;
+        chat_kind: z.ZodOptional<z.ZodEnum<{
+            dm: "dm";
+            group: "group";
+        }>>;
+        has_attachments: z.ZodOptional<z.ZodBoolean>;
+        attachment_count: z.ZodOptional<z.ZodNumber>;
+        reaction_only_count: z.ZodOptional<z.ZodNumber>;
+        session_candidate_id: z.ZodOptional<z.ZodString>;
+        source_schema_version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    bridgeId: z.ZodString;
+    sourceEventId: z.ZodString;
+    occurredAt: z.ZodISODateTime;
+    isGroup: z.ZodBoolean;
+    payloadHash: z.ZodString;
+    backfillBatchId: z.ZodOptional<z.ZodUUID>;
+    watermarkRef: z.ZodOptional<z.ZodString>;
+    eventKind: z.ZodLiteral<"call.event">;
+    source: z.ZodLiteral<"call_history">;
+    conversationRef: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        externalIdentityRef: z.ZodString;
+        role: z.ZodEnum<{
+            sender: "sender";
+            recipient: "recipient";
+            participant: "participant";
+            owner: "owner";
+        }>;
+    }, z.core.$strict>>;
+    safeMetadata: z.ZodObject<{
+        call_seconds: z.ZodNumber;
+        call_service: z.ZodEnum<{
+            cellular: "cellular";
+            facetime_audio: "facetime_audio";
+            facetime_video: "facetime_video";
+        }>;
+        answered: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>], "eventKind">;
+export type BridgeEnvelope = z.infer<typeof bridgeEnvelopeSchema>;
+export type CoreEnvelope = z.infer<typeof imessageEnvelopeSchema>;
+export type CallEnvelope = z.infer<typeof callEnvelopeSchema>;
+export type SafeMetadata = z.infer<typeof imessageSafeMetadataSchema>;
+export declare function parseBridgeEnvelope(value: unknown): BridgeEnvelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,iBAAiB;;;;;;;;kBAG5B,CAAC;AAKH,eAAO,MAAM,kBAAkB,2NAYrB,CAAC;AAEX,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;kBAYrC,CAAC;AAKH,eAAO,MAAM,sBAAsB;;;;;;;;kBAIjC,CAAC;AAsBH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQjC,CAAC;AAOH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkB7B,CAAC;AAKH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAG/B,CAAC;AAOH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAEtE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAElE"}

package/dist/envelope.js

@@ -0,0 +1,106 @@
+// Canonical ingestion-envelope contract shared by the Core (crm) and the Mac bridge
+// (imap-mcp). Single source of truth — was hand-mirrored across the two packages.
+// Pure types/schemas, no I/O. Authored in Zod v4 idiom.
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Participant — shared by both envelope variants.
+// ---------------------------------------------------------------------------
+export const participantSchema = z.strictObject({
+    externalIdentityRef: z.string().min(1),
+    role: z.enum(['sender', 'recipient', 'participant', 'owner']),
+});
+// ---------------------------------------------------------------------------
+// iMessage safe-metadata allowlist (key list kept for consumers that enumerate it).
+// ---------------------------------------------------------------------------
+export const SAFE_METADATA_KEYS = [
+    'message_count',
+    'inbound_count',
+    'outbound_count',
+    'participant_count',
+    'service',
+    'chat_kind',
+    'has_attachments',
+    'attachment_count',
+    'reaction_only_count',
+    'session_candidate_id',
+    'source_schema_version',
+];
+export const imessageSafeMetadataSchema = z.strictObject({
+    message_count: z.number().int().nonnegative().optional(),
+    inbound_count: z.number().int().nonnegative().optional(),
+    outbound_count: z.number().int().nonnegative().optional(),
+    participant_count: z.number().int().positive().optional(),
+    service: z.enum(['imessage', 'sms']).optional(),
+    chat_kind: z.enum(['dm', 'group']).optional(),
+    has_attachments: z.boolean().optional(),
+    attachment_count: z.number().int().nonnegative().optional(),
+    reaction_only_count: z.number().int().nonnegative().optional(),
+    session_candidate_id: z.string().min(1).optional(),
+    source_schema_version: z.string().min(1).optional(),
+});
+// Call safe metadata — all three REQUIRED and load-bearing at promotion (a missing
+// `answered` would silently drop a connected inbound call; a missing `call_service`
+// would mislabel a cellular call as FaceTime), so the Core fails closed.
+export const callSafeMetadataSchema = z.strictObject({
+    call_seconds: z.number().int().nonnegative(),
+    call_service: z.enum(['cellular', 'facetime_audio', 'facetime_video']),
+    answered: z.boolean(),
+});
+// ---------------------------------------------------------------------------
+// Common fields shared by every envelope variant. Defined as a plain object (not
+// z.object) so it can be spread into each strictObject variant.
+// `occurredAt` accepts ISO 8601 with Z or ±HH:MM offset; `backfillBatchId` is an
+// RFC-9562 UUID. (Zod v4 enforces both more strictly than v3 did — RFC-conformant.)
+// ---------------------------------------------------------------------------
+const commonFields = {
+    bridgeId: z.string().min(1),
+    sourceEventId: z.string().min(1),
+    occurredAt: z.iso.datetime({ offset: true }),
+    direction: z.enum(['inbound', 'outbound', 'mixed', 'unknown']),
+    isGroup: z.boolean(),
+    payloadHash: z.string().regex(/^[a-f0-9]{64}$/),
+    backfillBatchId: z.uuid().optional(),
+    watermarkRef: z.string().min(1).optional(),
+};
+// ---------------------------------------------------------------------------
+// iMessage envelope member.
+// ---------------------------------------------------------------------------
+export const imessageEnvelopeSchema = z.strictObject({
+    eventKind: z.literal('imessage.message'),
+    source: z.literal('imessage'),
+    conversationRef: z.string().min(1),
+    participants: z.array(participantSchema).min(1),
+    // Optional at parse time (the builder always emits it); defaults to {}.
+    safeMetadata: imessageSafeMetadataSchema.default({}),
+    ...commonFields,
+});
+// ---------------------------------------------------------------------------
+// Call envelope member. The "exactly one owner + one participant" constraint is a
+// .refine() on the `participants` FIELD (not the object), so the member stays a
+// ZodObject and is valid inside z.discriminatedUnion.
+// ---------------------------------------------------------------------------
+export const callEnvelopeSchema = z.strictObject({
+    eventKind: z.literal('call.event'),
+    source: z.literal('call_history'),
+    conversationRef: z.string().regex(/^call:/),
+    participants: z
+        .array(participantSchema)
+        .refine((arr) => arr.length === 2 &&
+        arr.filter((p) => p.role === 'owner').length === 1 &&
+        arr.filter((p) => p.role === 'participant').length === 1, { message: 'call envelope must be 1:1 — exactly one owner and one participant' }),
+    safeMetadata: callSafeMetadataSchema,
+    ...commonFields,
+    // A call is one-directional; narrow the shared 4-value direction to the two values a
+    // call can carry. Placed after the spread so it overrides commonFields.direction.
+    direction: z.enum(['inbound', 'outbound']),
+});
+// ---------------------------------------------------------------------------
+// Discriminated union — the single schema the Core parses for all variants.
+// ---------------------------------------------------------------------------
+export const bridgeEnvelopeSchema = z.discriminatedUnion('eventKind', [
+    imessageEnvelopeSchema,
+    callEnvelopeSchema,
+]);
+export function parseBridgeEnvelope(value) {
+    return bridgeEnvelopeSchema.parse(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './envelope.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from './envelope.js';

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rkt-tools/contracts",
+  "version": "0.1.0",
+  "description": "Shared ingestion-envelope Zod schemas for the rkt stack",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "prepublishOnly": "pnpm run build && pnpm run test"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^22.10.2",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^9.1.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^4.1.6"
+  }
+}