@contractspec/example.crm-pipeline 1.57.0 → 1.59.0

package/dist/node/deal/index.js

@@ -0,0 +1,408 @@
+// src/deal/deal.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var DealStatusEnum = defineEnum("DealStatus", [
+  "OPEN",
+  "WON",
+  "LOST",
+  "STALE"
+]);
+var DealStatusFilterEnum = defineEnum("DealStatusFilter", [
+  "OPEN",
+  "WON",
+  "LOST",
+  "all"
+]);
+
+// src/deal/deal.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var DealWonPayloadModel = defineSchemaModel({
+  name: "DealWonPayload",
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    value: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false }
+  }
+});
+var 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 }
+  }
+});
+var DealLostPayloadModel = defineSchemaModel({
+  name: "DealLostPayload",
+  fields: {
+    dealId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var 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
+    }
+  }
+});
+var 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 }
+  }
+});
+
+// src/deal/deal.operation.ts
+import {
+  defineCommand,
+  defineQuery
+} from "@contractspec/lib.contracts/operations";
+var OWNERS = ["@example.crm-pipeline"];
+var 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"
+        }
+      }
+    ]
+  }
+});
+var 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"
+        }
+      }
+    ]
+  }
+});
+var 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"
+        }
+      }
+    ]
+  }
+});
+var 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"
+        }
+      }
+    ]
+  }
+});
+var 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 }
+      }
+    ]
+  }
+});
+export {
+  WinDealInputModel,
+  WinDealContract,
+  MoveDealInputModel,
+  MoveDealContract,
+  LoseDealInputModel,
+  LoseDealContract,
+  ListDealsOutputModel,
+  ListDealsInputModel,
+  ListDealsContract,
+  DealWonPayloadModel,
+  DealStatusFilterEnum,
+  DealStatusEnum,
+  DealMovedPayloadModel,
+  DealModel,
+  DealLostPayloadModel,
+  CreateDealInputModel,
+  CreateDealContract
+};

package/dist/node/docs/crm-pipeline.docblock.js

@@ -0,0 +1,113 @@
+// src/docs/crm-pipeline.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var crmPipelineDocBlocks = [
+  {
+    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.
+
+## Adoption narrative
+
+### Before
+- A CRM app with hand-written data models and handler logic.
+- Pipeline stage rules live in code and drift across UI/API/events.
+- Regeneration is risky because specs and implementations are not aligned.
+
+### After
+- Contracts define deals, stages, and tasks as the source of truth.
+- Regeneration keeps UI/API/events in sync when stages change.
+- Compliance surfaces (audits, notifications) stay consistent with specs.
+
+### Minimal adoption steps
+1) Add ContractSpec CLI and core libraries.
+2) Define one operation (for example, deal/create).
+3) Run contractspec build to generate handlers and types.
+4) Wire the generated handler into your existing router.
+5) Expand to events and presentations as you add surface areas.
+`
+  },
+  {
+    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/dist/node/docs/index.js

@@ -0,0 +1,113 @@
+// src/docs/crm-pipeline.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var crmPipelineDocBlocks = [
+  {
+    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.
+
+## Adoption narrative
+
+### Before
+- A CRM app with hand-written data models and handler logic.
+- Pipeline stage rules live in code and drift across UI/API/events.
+- Regeneration is risky because specs and implementations are not aligned.
+
+### After
+- Contracts define deals, stages, and tasks as the source of truth.
+- Regeneration keeps UI/API/events in sync when stages change.
+- Compliance surfaces (audits, notifications) stay consistent with specs.
+
+### Minimal adoption steps
+1) Add ContractSpec CLI and core libraries.
+2) Define one operation (for example, deal/create).
+3) Run contractspec build to generate handlers and types.
+4) Wire the generated handler into your existing router.
+5) Expand to events and presentations as you add surface areas.
+`
+  },
+  {
+    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/dist/node/entities/company.entity.js

@@ -0,0 +1,52 @@
+// src/entities/company.entity.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var CompanySizeEnum = defineEntityEnum({
+  name: "CompanySize",
+  values: ["STARTUP", "SMALL", "MEDIUM", "LARGE", "ENTERPRISE"],
+  schema: "crm",
+  description: "Size category of a company."
+});
+var CompanyEntity = defineEntity({
+  name: "Company",
+  description: "A company/organization in the CRM.",
+  schema: "crm",
+  map: "company",
+  fields: {
+    id: field.id({ description: "Unique company ID" }),
+    name: field.string({ description: "Company name" }),
+    domain: field.string({ isOptional: true, description: "Website domain" }),
+    website: field.url({ isOptional: true }),
+    industry: field.string({ isOptional: true }),
+    size: field.enum("CompanySize", { isOptional: true }),
+    employeeCount: field.int({ isOptional: true }),
+    annualRevenue: field.decimal({ isOptional: true }),
+    organizationId: field.foreignKey(),
+    ownerId: field.foreignKey({ description: "Account owner" }),
+    phone: field.string({ isOptional: true }),
+    email: field.email({ isOptional: true }),
+    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 }),
+    linkedInUrl: field.url({ isOptional: true }),
+    description: field.string({ isOptional: true }),
+    tags: field.string({ isArray: true }),
+    customFields: field.json({ isOptional: true }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    contacts: field.hasMany("Contact"),
+    deals: field.hasMany("Deal")
+  },
+  indexes: [index.on(["organizationId", "ownerId"]), index.on(["domain"])],
+  enums: [CompanySizeEnum]
+});
+export {
+  CompanySizeEnum,
+  CompanyEntity
+};