@apollo-deploy/signal-schemas

Wire contracts for the Apollo Signal transactional email service.

This package is the single source of truth for types that cross the Signal service boundary — request/response shapes, public domain models, and enums consumed by both the backend and at least one external surface (SDK, web client, OpenAPI export).

TL;DR

1. This package is for Signal-specific shared wire contracts only.
2. Backend-private schemas live in the owning module: apps/signal/src/modules/<module>/contracts/internal/.
3. Only contracts/global/* inside a Signal module may import from this package.
4. After changing schema sources, run in order: registry:check → generate → build.

Decision Tree

Is this schema crossing a process boundary?
├── No  → Keep it in the owning module (contracts/internal).
└── Yes → Will any non-backend surface consume it?
         ├── No  → Keep it in contracts/internal.
         └── Yes → Add it here.

When in doubt, keep it local. Promotion is cheap; rollback is not.

Available Subpaths

| Domain | Subpath | |---|---| | Common primitives (dates, pagination, error envelope) | @apollo-deploy/signal-schemas | | All definitions (aggregate barrel) | @apollo-deploy/signal-schemas/definitions | | Generators (tooling) | @apollo-deploy/signal-schemas/generators | | Email API | @apollo-deploy/signal-schemas/emails | | Projects (/signal/projects*) | @apollo-deploy/signal-schemas/projects | | Domains, webhooks, suppressions, emails, etc. | @apollo-deploy/signal-schemas/<module> |

Domain Folder Layout

Every domain under src/definitions/<domain>/ follows:

<domain>/
├── domain.schema.ts   # Entities, enums, value objects
├── request.schema.ts  # Query params, path params, request bodies
├── response.schema.ts # Response shapes, list envelopes
└── index.ts           # Barrel — re-exports only, no definitions

How apps/signal Modules Consume This Package

Only contracts/global/* inside a feature module may import from @apollo-deploy/signal-schemas. All other layers import from the module's contracts/global barrel.

// apps/signal/src/modules/webhooks/contracts/global/index.ts
export {
  CreateWebhookBodySchema,
  WebhookResponseSchema,
  type CreateWebhookBody,
  type WebhookResponse,
} from '@apollo-deploy/signal-schemas/webhooks';

// apps/signal/src/modules/webhooks/api/route-schema.ts
import { SignalWebhookCreateBodySchema } from '../contracts/global/index.js';

Development Workflow

# From packages/signal-schemas/
bun run registry:check   # 1. Confirm all schemas are registered
bun run registry:fix     # 1b. Auto-add missing registrations
bun run generate         # 2. Regenerate JSON Schema output under generated/
bun run build            # 3. Rebuild dist/ so workspace consumers see new types

Adding a New Domain

1. Create the domain folder: mkdir -p src/definitions/my-domain
2. Create: domain.schema.ts, request.schema.ts, response.schema.ts, index.ts
3. Add the domain to src/definitions/index.ts
4. Add a subpath to package.json exports
5. Run registry:fix → generate → build
6. In consuming modules, expose types through contracts/global/ only

Schema Registry

Every exported *Schema constant must be registered with z.globalRegistry:

bun run registry:check   # CI enforcement
bun run registry:fix     # Auto-insert missing registrations

Key Differences from packages/schemas

• Scope: Signal-only contracts. Cross-service contracts also consumed by apps/api or the main SDK stay in packages/schemas.
• Private: "private": true — not published to npm, workspace-only.
• Common primitives: common.ts provides Signal-specific shared types (IsoDateStringSchema, CursorPaginationSchema, SignalErrorEnvelopeSchema, UrlSchema).