@contractspec/example.crm-pipeline 1.44.0

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/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],
+});

package/src/entities/contact.entity.ts

@@ -0,0 +1,93 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@contractspec/lib.schema';
+
+/**
+ * Contact status enum.
+ */
+export const ContactStatusEnum = defineEntityEnum({
+  name: 'ContactStatus',
+  values: ['LEAD', 'PROSPECT', 'CUSTOMER', 'CHURNED', 'ARCHIVED'] as const,
+  schema: 'crm',
+  description: 'Status of a contact in the sales funnel.',
+});
+
+/**
+ * Contact entity - individual person.
+ */
+export const ContactEntity = defineEntity({
+  name: 'Contact',
+  description: 'An individual person in the CRM.',
+  schema: 'crm',
+  map: 'contact',
+  fields: {
+    id: field.id({ description: 'Unique contact ID' }),
+
+    // Basic info
+    firstName: field.string({ description: 'First name' }),
+    lastName: field.string({ description: 'Last name' }),
+    email: field.email({ isOptional: true, isUnique: true }),
+    phone: field.string({ isOptional: true }),
+
+    // Company
+    companyId: field.string({
+      isOptional: true,
+      description: 'Associated company',
+    }),
+    jobTitle: field.string({ isOptional: true }),
+
+    // Status
+    status: field.enum('ContactStatus', { default: 'LEAD' }),
+
+    // Ownership
+    organizationId: field.foreignKey(),
+    ownerId: field.foreignKey({
+      description: 'Sales rep who owns this contact',
+    }),
+
+    // Source
+    source: field.string({ isOptional: true, description: 'Lead source' }),
+
+    // Social
+    linkedInUrl: field.url({ isOptional: true }),
+    twitterHandle: field.string({ 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 }),
+
+    // Notes
+    notes: field.string({ isOptional: true }),
+    tags: field.string({ isArray: true }),
+
+    // Custom fields
+    customFields: field.json({ isOptional: true }),
+
+    // Engagement
+    lastContactedAt: field.dateTime({ isOptional: true }),
+    nextFollowUpAt: field.dateTime({ isOptional: true }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+
+    // Relations
+    company: field.belongsTo('Company', ['companyId'], ['id']),
+    deals: field.hasMany('Deal'),
+    tasks: field.hasMany('Task'),
+    activities: field.hasMany('Activity'),
+  },
+  indexes: [
+    index.on(['organizationId', 'status']),
+    index.on(['organizationId', 'ownerId']),
+    index.on(['organizationId', 'companyId']),
+    index.on(['email']),
+  ],
+  enums: [ContactStatusEnum],
+});

package/src/entities/deal.entity.ts

@@ -0,0 +1,160 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@contractspec/lib.schema';
+
+/**
+ * Deal status enum.
+ */
+export const DealStatusEnum = defineEntityEnum({
+  name: 'DealStatus',
+  values: ['OPEN', 'WON', 'LOST', 'STALE'] as const,
+  schema: 'crm',
+  description: 'Status of a deal.',
+});
+
+/**
+ * Pipeline entity - sales pipeline definition.
+ */
+export const PipelineEntity = defineEntity({
+  name: 'Pipeline',
+  description: 'A sales pipeline with stages.',
+  schema: 'crm',
+  map: 'pipeline',
+  fields: {
+    id: field.id(),
+    name: field.string({ description: 'Pipeline name' }),
+    description: field.string({ isOptional: true }),
+
+    // Ownership
+    organizationId: field.foreignKey(),
+
+    // Settings
+    isDefault: field.boolean({ default: false }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+
+    // Relations
+    stages: field.hasMany('Stage'),
+    deals: field.hasMany('Deal'),
+  },
+});
+
+/**
+ * Stage entity - pipeline stage.
+ */
+export const StageEntity = defineEntity({
+  name: 'Stage',
+  description: 'A stage within a sales pipeline.',
+  schema: 'crm',
+  map: 'stage',
+  fields: {
+    id: field.id(),
+    name: field.string({ description: 'Stage name' }),
+    pipelineId: field.foreignKey(),
+
+    // Position
+    position: field.int({ description: 'Order in pipeline' }),
+
+    // Probability
+    probability: field.int({
+      default: 0,
+      description: 'Win probability (0-100)',
+    }),
+
+    // Type
+    isWonStage: field.boolean({ default: false }),
+    isLostStage: field.boolean({ default: false }),
+
+    // Settings
+    color: field.string({
+      isOptional: true,
+      description: 'Stage color for UI',
+    }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+
+    // Relations
+    pipeline: field.belongsTo('Pipeline', ['pipelineId'], ['id'], {
+      onDelete: 'Cascade',
+    }),
+    deals: field.hasMany('Deal'),
+  },
+  indexes: [index.on(['pipelineId', 'position'])],
+});
+
+/**
+ * Deal entity - sales opportunity.
+ */
+export const DealEntity = defineEntity({
+  name: 'Deal',
+  description: 'A sales opportunity/deal.',
+  schema: 'crm',
+  map: 'deal',
+  fields: {
+    id: field.id({ description: 'Unique deal ID' }),
+    name: field.string({ description: 'Deal name' }),
+
+    // Value
+    value: field.decimal({ description: 'Deal value' }),
+    currency: field.string({ default: '"USD"' }),
+
+    // Pipeline
+    pipelineId: field.foreignKey(),
+    stageId: field.foreignKey(),
+
+    // Status
+    status: field.enum('DealStatus', { default: 'OPEN' }),
+
+    // Associations
+    contactId: field.string({ isOptional: true }),
+    companyId: field.string({ isOptional: true }),
+
+    // Ownership
+    organizationId: field.foreignKey(),
+    ownerId: field.foreignKey({ description: 'Deal owner' }),
+
+    // Timeline
+    expectedCloseDate: field.dateTime({ isOptional: true }),
+    closedAt: field.dateTime({ isOptional: true }),
+
+    // Tracking
+    lostReason: field.string({ isOptional: true }),
+    wonSource: field.string({ isOptional: true }),
+
+    // Notes
+    notes: field.string({ isOptional: true }),
+    tags: field.string({ isArray: true }),
+
+    // Custom fields
+    customFields: field.json({ isOptional: true }),
+
+    // Position in stage (for Kanban)
+    stagePosition: field.int({ default: 0 }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+
+    // Relations
+    pipeline: field.belongsTo('Pipeline', ['pipelineId'], ['id']),
+    stage: field.belongsTo('Stage', ['stageId'], ['id']),
+    contact: field.belongsTo('Contact', ['contactId'], ['id']),
+    company: field.belongsTo('Company', ['companyId'], ['id']),
+    tasks: field.hasMany('Task'),
+    activities: field.hasMany('Activity'),
+  },
+  indexes: [
+    index.on(['organizationId', 'status']),
+    index.on(['pipelineId', 'stageId', 'stagePosition']),
+    index.on(['ownerId', 'status']),
+    index.on(['expectedCloseDate']),
+  ],
+  enums: [DealStatusEnum],
+});

package/src/entities/index.ts

@@ -0,0 +1,45 @@
+export * from './company.entity';
+export * from './contact.entity';
+export * from './deal.entity';
+export * from './task.entity';
+
+import type { ModuleSchemaContribution } from '@contractspec/lib.schema';
+import { CompanyEntity, CompanySizeEnum } from './company.entity';
+import { ContactEntity, ContactStatusEnum } from './contact.entity';
+import {
+  DealEntity,
+  PipelineEntity,
+  StageEntity,
+  DealStatusEnum,
+} from './deal.entity';
+import {
+  TaskEntity,
+  ActivityEntity,
+  TaskTypeEnum,
+  TaskPriorityEnum,
+  TaskStatusEnum,
+} from './task.entity';
+
+/**
+ * CRM Pipeline schema contribution.
+ */
+export const crmPipelineSchemaContribution: ModuleSchemaContribution = {
+  moduleId: '@contractspec/example.crm-pipeline',
+  entities: [
+    CompanyEntity,
+    ContactEntity,
+    DealEntity,
+    PipelineEntity,
+    StageEntity,
+    TaskEntity,
+    ActivityEntity,
+  ],
+  enums: [
+    CompanySizeEnum,
+    ContactStatusEnum,
+    DealStatusEnum,
+    TaskTypeEnum,
+    TaskPriorityEnum,
+    TaskStatusEnum,
+  ],
+};