@contractspec/example.crm-pipeline 0.0.0-canary-20260113170453

package/src/deal/deal.operation.ts

@@ -0,0 +1,291 @@
+import {
+  defineCommand,
+  defineQuery,
+} from '@contractspec/lib.contracts/operations';
+import {
+  DealModel,
+  CreateDealInputModel,
+  MoveDealInputModel,
+  DealMovedPayloadModel,
+  WinDealInputModel,
+  DealWonPayloadModel,
+  LoseDealInputModel,
+  DealLostPayloadModel,
+  ListDealsInputModel,
+  ListDealsOutputModel,
+} from './deal.schema';
+
+const OWNERS = ['@example.crm-pipeline'] as const;
+
+/**
+ * Create a new deal.
+ */
+export const CreateDealContract = defineCommand({
+  meta: {
+    key: 'crm.deal.create',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['crm', 'deal', 'create'],
+    description: 'Create a new deal in the pipeline.',
+    goal: 'Allow sales reps to create new opportunities.',
+    context: 'Deal creation UI, quick add.',
+  },
+  io: {
+    input: CreateDealInputModel,
+    output: DealModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'deal.created',
+        version: '1.0.0',
+        when: 'Deal is created',
+        payload: DealModel,
+      },
+    ],
+    audit: ['deal.created'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'create-deal-happy-path',
+        given: ['User is authenticated'],
+        when: ['User creates a deal with valid data'],
+        then: ['Deal is created', 'DealCreated event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'create-basic-deal',
+        input: {
+          title: 'Big Corp Q3 License',
+          stageId: 'stage-lead',
+          value: 50000,
+          companyId: 'comp-123',
+        },
+        output: {
+          id: 'deal-789',
+          title: 'Big Corp Q3 License',
+          status: 'open',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * Move deal to a different stage.
+ */
+export const MoveDealContract = defineCommand({
+  meta: {
+    key: 'crm.deal.move',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['crm', 'deal', 'move', 'kanban'],
+    description: 'Move a deal to a different stage.',
+    goal: 'Allow drag-and-drop stage movement in Kanban.',
+    context: 'Pipeline Kanban view.',
+  },
+  io: {
+    input: MoveDealInputModel,
+    output: DealModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'deal.moved',
+        version: '1.0.0',
+        when: 'Deal stage changed',
+        payload: DealMovedPayloadModel,
+      },
+    ],
+    audit: ['deal.moved'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'move-deal-happy-path',
+        given: ['Deal exists in stage A'],
+        when: ['User moves deal to stage B'],
+        then: ['Deal stage is updated', 'DealMoved event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'move-to-negotiation',
+        input: { dealId: 'deal-789', targetStageId: 'stage-negotiation' },
+        output: {
+          id: 'deal-789',
+          stageId: 'stage-negotiation',
+          movedAt: '2025-01-15T10:00:00Z',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * Mark deal as won.
+ */
+export const WinDealContract = defineCommand({
+  meta: {
+    key: 'crm.deal.win',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['crm', 'deal', 'won'],
+    description: 'Mark a deal as won.',
+    goal: 'Close a deal as successful.',
+    context: 'Deal closing flow.',
+  },
+  io: {
+    input: WinDealInputModel,
+    output: DealModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'deal.won',
+        version: '1.0.0',
+        when: 'Deal is won',
+        payload: DealWonPayloadModel,
+      },
+    ],
+    audit: ['deal.won'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'win-deal-happy-path',
+        given: ['Deal is open'],
+        when: ['User marks deal as won'],
+        then: ['Deal status becomes WON', 'DealWon event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'mark-won',
+        input: {
+          dealId: 'deal-789',
+          actualValue: 52000,
+          note: 'Signed contract attached',
+        },
+        output: {
+          id: 'deal-789',
+          status: 'won',
+          closedAt: '2025-01-20T14:30:00Z',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * Mark deal as lost.
+ */
+export const LoseDealContract = defineCommand({
+  meta: {
+    key: 'crm.deal.lose',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['crm', 'deal', 'lost'],
+    description: 'Mark a deal as lost.',
+    goal: 'Close a deal as unsuccessful.',
+    context: 'Deal closing flow.',
+  },
+  io: {
+    input: LoseDealInputModel,
+    output: DealModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'deal.lost',
+        version: '1.0.0',
+        when: 'Deal is lost',
+        payload: DealLostPayloadModel,
+      },
+    ],
+    audit: ['deal.lost'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'lose-deal-happy-path',
+        given: ['Deal is open'],
+        when: ['User marks deal as lost'],
+        then: ['Deal status becomes LOST', 'DealLost event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'mark-lost',
+        input: {
+          dealId: 'deal-789',
+          reason: 'competitor',
+          note: 'Went with cheaper option',
+        },
+        output: {
+          id: 'deal-789',
+          status: 'lost',
+          closedAt: '2025-01-21T09:00:00Z',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * List deals in pipeline.
+ */
+export const ListDealsContract = defineQuery({
+  meta: {
+    key: 'crm.deal.list',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['crm', 'deal', 'list'],
+    description: 'List deals with filters.',
+    goal: 'Show pipeline, deal lists, dashboards.',
+    context: 'Pipeline view, deal list.',
+  },
+  io: {
+    input: ListDealsInputModel,
+    output: ListDealsOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'list-deals-happy-path',
+        given: ['User has access to deals'],
+        when: ['User lists deals'],
+        then: ['List of deals is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'list-filter-stage',
+        input: { stageId: 'stage-lead', limit: 20 },
+        output: { items: [], total: 5, hasMore: false },
+      },
+    ],
+  },
+});

package/src/deal/deal.schema.ts

@@ -0,0 +1,154 @@
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import { DealStatusEnum, DealStatusFilterEnum } from './deal.enum';
+
+/**
+ * A deal in the CRM pipeline.
+ */
+export const DealModel = defineSchemaModel({
+  name: 'Deal',
+  description: 'A deal in the CRM pipeline',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    value: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    currency: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    pipelineId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    stageId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: DealStatusEnum, isOptional: false },
+    contactId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    companyId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    expectedCloseDate: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Input for creating a deal.
+ */
+export const CreateDealInputModel = defineSchemaModel({
+  name: 'CreateDealInput',
+  description: 'Input for creating a deal',
+  fields: {
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    value: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    currency: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    pipelineId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    stageId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    contactId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    companyId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    expectedCloseDate: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+  },
+});
+
+/**
+ * Input for moving a deal to another stage.
+ */
+export const MoveDealInputModel = defineSchemaModel({
+  name: 'MoveDealInput',
+  description: 'Input for moving a deal to another stage',
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    stageId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    position: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+  },
+});
+
+/**
+ * Payload for deal moved event.
+ */
+export const DealMovedPayloadModel = defineSchemaModel({
+  name: 'DealMovedPayload',
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    fromStage: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toStage: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Input for marking a deal as won.
+ */
+export const WinDealInputModel = defineSchemaModel({
+  name: 'WinDealInput',
+  description: 'Input for marking a deal as won',
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    wonSource: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    notes: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+/**
+ * Payload for deal won event.
+ */
+export const DealWonPayloadModel = defineSchemaModel({
+  name: 'DealWonPayload',
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    value: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Input for marking a deal as lost.
+ */
+export const LoseDealInputModel = defineSchemaModel({
+  name: 'LoseDealInput',
+  description: 'Input for marking a deal as lost',
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    lostReason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    notes: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+/**
+ * Payload for deal lost event.
+ */
+export const DealLostPayloadModel = defineSchemaModel({
+  name: 'DealLostPayload',
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Input for listing deals.
+ */
+export const ListDealsInputModel = defineSchemaModel({
+  name: 'ListDealsInput',
+  description: 'Input for listing deals',
+  fields: {
+    pipelineId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    stageId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: DealStatusFilterEnum, isOptional: true },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    search: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    limit: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 20,
+    },
+    offset: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 0,
+    },
+  },
+});
+
+/**
+ * Output for listing deals.
+ */
+export const ListDealsOutputModel = defineSchemaModel({
+  name: 'ListDealsOutput',
+  description: 'Output for listing deals',
+  fields: {
+    deals: { type: DealModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    totalValue: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+  },
+});

package/src/deal/deal.test-spec.ts

@@ -0,0 +1,55 @@
+import { defineTestSpec } from '@contractspec/lib.contracts';
+
+export const dealListTest = defineTestSpec({
+  meta: {
+    key: 'test.crm.deal.list',
+    version: '1.0.0',
+    owners: ['@example.crm-pipeline'],
+    description: 'Test for listing deals',
+    stability: 'stable',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'crm.deal.list', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'crm.deal.list' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'crm.deal.list' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const dealMoveTest = defineTestSpec({
+  meta: {
+    key: 'test.crm.deal.move',
+    version: '1.0.0',
+    owners: ['@example.crm-pipeline'],
+    description: 'Test for moving deal',
+    stability: 'stable',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'crm.deal.move', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'crm.deal.move' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'crm.deal.move' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});

package/src/deal/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Deal domain - Deal management in CRM pipeline.
+ */
+
+export { DealStatusEnum, DealStatusFilterEnum } from './deal.enum';
+
+export {
+  DealModel,
+  CreateDealInputModel,
+  MoveDealInputModel,
+  DealMovedPayloadModel,
+  WinDealInputModel,
+  DealWonPayloadModel,
+  LoseDealInputModel,
+  DealLostPayloadModel,
+  ListDealsInputModel,
+  ListDealsOutputModel,
+} from './deal.schema';
+
+export {
+  CreateDealContract,
+  MoveDealContract,
+  WinDealContract,
+  LoseDealContract,
+  ListDealsContract,
+} from './deal.operation';

package/src/docs/crm-pipeline.docblock.ts

@@ -0,0 +1,98 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const crmPipelineDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.crm-pipeline.goal',
+    title: 'CRM Pipeline — Goal',
+    summary:
+      'Deals, stages, contacts, companies, and tasks with auditable stage movement.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/crm-pipeline/goal',
+    tags: ['crm', 'goal'],
+    body: `## Why it matters
+- Regenerable CRM flow for deals/stages without code drift.
+- Ensures stage movement, tasks, and contacts stay aligned across surfaces.
+
+## Business/Product goal
+- Give sales teams a governed pipeline with auditable moves and notifications.
+- Allow experimentation (feature flags) on stage definitions and task flows.
+
+## Success criteria
+- Stage/state changes emit events and remain declarative in spec.
+- PII (contacts) is scoped/redacted in presentations.`,
+  },
+  {
+    id: 'docs.examples.crm-pipeline.usage',
+    title: 'CRM Pipeline — Usage',
+    summary: 'How to seed, extend, and regenerate the CRM pipeline.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/crm-pipeline/usage',
+    tags: ['crm', 'usage'],
+    body: `## Setup
+1) Seed (if available) or create pipeline stages, deals, contacts, companies, tasks.
+2) Configure Notifications for stage changes/tasks; set policy.pii for contact data.
+
+## Extend & regenerate
+1) Adjust stage schema/order, deal fields, task fields in the spec.
+2) Regenerate to sync UI/API/events; ensure kanban/action buttons update.
+3) Use Feature Flags to trial new stages or SLA rules.
+
+## Guardrails
+- Emit events for stage moves and task completions; log to Audit Trail.
+- Keep required fields enforced in contracts; avoid freeform state.
+- Redact contact PII in markdown/JSON outputs.`,
+  },
+  {
+    id: 'docs.examples.crm-pipeline.reference',
+    title: 'CRM Pipeline — Reference',
+    summary:
+      'Entities, contracts, events, and presentations for the CRM template.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/crm-pipeline',
+    tags: ['crm', 'reference'],
+    body: `## Entities
+- Contact, Company, Deal, Pipeline, Stage, Task.
+
+## Contracts
+- deal/create, stage/move, contact/company CRUD, task create/complete.
+
+## Events
+- deal.created, stage.moved, task.completed, contact.updated.
+
+## Presentations
+- Pipelines/kanban, deal detail, contact/company profiles, task lists.
+
+## Notes
+- Stage definitions should be declarative; enforce via spec and regeneration.
+- Use Notifications for deal/task updates; Audit Trail for state changes.`,
+  },
+  {
+    id: 'docs.examples.crm-pipeline.constraints',
+    title: 'CRM Pipeline — Constraints & Safety',
+    summary:
+      'Internal guardrails for stages, PII, and regeneration semantics in the CRM template.',
+    kind: 'reference',
+    visibility: 'internal',
+    route: '/docs/examples/crm-pipeline/constraints',
+    tags: ['crm', 'constraints', 'internal'],
+    body: `## Constraints
+- Stage definitions/order must remain declarative; no imperative overrides in code.
+- Events to emit: deal.created, stage.moved, task.completed, contact.updated (minimum).
+- Regeneration should not alter stage semantics without explicit spec change.
+
+## PII
+- Mark contact/company PII (emails, phones) for redaction in presentations.
+- Ensure MCP/web outputs avoid raw PII when not needed.
+
+## Verification
+- Add fixtures for stage move rules and SLA/task changes.
+- Ensure Audit/Notifications remain wired for stage and task events.
+- Use Feature Flags for experimental stages/SLAs; default safe/off.`,
+  },
+];
+
+registerDocBlocks(crmPipelineDocBlocks);

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './crm-pipeline.docblock';

package/src/entities/company.entity.ts

@@ -0,0 +1,77 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@contractspec/lib.schema';
+
+/**
+ * Company size enum.
+ */
+export const CompanySizeEnum = defineEntityEnum({
+  name: 'CompanySize',
+  values: ['STARTUP', 'SMALL', 'MEDIUM', 'LARGE', 'ENTERPRISE'] as const,
+  schema: 'crm',
+  description: 'Size category of a company.',
+});
+
+/**
+ * Company entity - organization/account.
+ */
+export const CompanyEntity = defineEntity({
+  name: 'Company',
+  description: 'A company/organization in the CRM.',
+  schema: 'crm',
+  map: 'company',
+  fields: {
+    id: field.id({ description: 'Unique company ID' }),
+
+    // Basic info
+    name: field.string({ description: 'Company name' }),
+    domain: field.string({ isOptional: true, description: 'Website domain' }),
+    website: field.url({ isOptional: true }),
+
+    // Industry
+    industry: field.string({ isOptional: true }),
+
+    // Size
+    size: field.enum('CompanySize', { isOptional: true }),
+    employeeCount: field.int({ isOptional: true }),
+    annualRevenue: field.decimal({ isOptional: true }),
+
+    // Ownership
+    organizationId: field.foreignKey(),
+    ownerId: field.foreignKey({ description: 'Account owner' }),
+
+    // Contact info
+    phone: field.string({ isOptional: true }),
+    email: field.email({ isOptional: true }),
+
+    // Address
+    address: field.string({ isOptional: true }),
+    city: field.string({ isOptional: true }),
+    state: field.string({ isOptional: true }),
+    country: field.string({ isOptional: true }),
+    postalCode: field.string({ isOptional: true }),
+
+    // Social
+    linkedInUrl: field.url({ isOptional: true }),
+
+    // Notes
+    description: field.string({ isOptional: true }),
+    tags: field.string({ isArray: true }),
+
+    // Custom fields
+    customFields: field.json({ isOptional: true }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+
+    // Relations
+    contacts: field.hasMany('Contact'),
+    deals: field.hasMany('Deal'),
+  },
+  indexes: [index.on(['organizationId', 'ownerId']), index.on(['domain'])],
+  enums: [CompanySizeEnum],
+});