@synap-core/workspace-templates 0.6.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/workspace-templates",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "description": "Canonical workspace definitions — YAML source + typed exports for browser, backend, CLI, and marketplace",

package/src/business-developer.template.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Contract tests for the Business Developer CRM overlay.
+ *
+ * The catalog intentionally reads `templates.ts`, the generated source
+ * consumed by every template installer.
+ */
+
+import { describe, expect, it } from "vitest";
+import { toWorkspaceDefinition } from "./define.js";
+import { getWorkspaceTemplate } from "./templates.js";
+
+const template = (() => {
+  const resolved = getWorkspaceTemplate("business-developer");
+  if (!resolved) throw new Error("Business Developer template is not registered");
+  return resolved;
+})();
+
+const crmTemplate = (() => {
+  const resolved = getWorkspaceTemplate("crm");
+  if (!resolved) throw new Error("CRM template is not registered");
+  return resolved;
+})();
+
+function profile(slug: string) {
+  const found = template?.profiles.find((candidate) => candidate.slug === slug);
+  expect(found, `expected ${slug} profile`).toBeDefined();
+  if (!found) throw new Error(`expected ${slug} profile`);
+  return found;
+}
+
+function propertySlugs(slug: string) {
+  return new Set(profile(slug).properties.map((property) => property.slug));
+}
+
+describe("Business Developer workspace overlay", () => {
+  it("composes onto CRM without replacing its workspace identity", () => {
+    expect(template).toBeDefined();
+    expect(template.dependencies).toEqual([
+    {
+      slug: "crm",
+      kind: "workspace",
+      relation: "compose",
+      reason: "Adds a lead-first business-development workflow to your CRM workspace.",
+    },
+    ]);
+    expect(template.workspace.subtype).toBe("crm");
+    expect(template.workspace.visibility).toBeUndefined();
+  });
+
+  it("keeps CRM lifecycle facets workspace-local", () => {
+    for (const slug of ["crm-lead", "crm-client"]) {
+      const facet = profile(slug);
+      expect(facet.scope).toBe("WORKSPACE");
+      expect(facet.profileKind).toBe("role");
+      expect(facet.applicableKinds).toEqual(["person", "company"]);
+    }
+
+    expect(template.profiles.some((candidate) => ["lead", "client"].includes(candidate.slug))).toBe(false);
+
+    expect([...propertySlugs("crm-lead")].sort()).toEqual([
+    "assignedUserId",
+    "convertedAt",
+    "disqualificationReason",
+    "icpScore",
+    "lastContactedAt",
+    "lifecycleStage",
+    "nextAction",
+    "nextActionAt",
+    "outreachChannels",
+    "qualificationNotes",
+    "source",
+    ].sort());
+  });
+
+  it("models proposals and auditable commission separately from leads", () => {
+    const commercialStages = profile("deal")
+      .properties.find((property) => property.slug === "commercialStage")?.enumValues;
+    expect(commercialStages).toEqual(["draft", "proposed", "negotiating", "won", "lost"]);
+
+    expect([...propertySlugs("crm-commission-entitlement")].sort()).toEqual([
+    "earnedAt",
+    "estimatedAmount",
+    "feeBasisAmount",
+    "paidAt",
+    "rateBps",
+    "sequence",
+    "sourceDealId",
+    "sourcedByUserId",
+    "status",
+    "voidReason",
+    ].sort());
+
+    expect([...propertySlugs("deal")].sort()).toEqual([
+      "commercialStage",
+      "commissionEntitlementId",
+      "commissionStatus",
+      "expectedClientGain",
+      "lostReason",
+      "sourcedByUserId",
+      "synapFeeAmount",
+      "synapFeeModel",
+      "synapFixedFee",
+      "synapSuccessFeeRate",
+      "wonAt",
+    ].sort());
+
+    const entitlementId = profile("deal").properties.find(
+      (property) => property.slug === "commissionEntitlementId",
+    );
+    expect(entitlementId).toMatchObject({
+      valueType: "entity_id",
+      inputType: "entity_select",
+      targetProfileSlug: "crm-commission-entitlement",
+    });
+    expect(
+      profile("crm-commission-entitlement").properties.find(
+        (property) => property.slug === "sourceDealId",
+      ),
+    ).toMatchObject({
+      valueType: "entity_id",
+      inputType: "entity_select",
+      targetProfileSlug: "deal",
+    });
+
+    expect(
+      template.entityLinks?.map(({ sourceProfileSlug, targetProfileSlug, type }) => ({
+        sourceProfileSlug,
+        targetProfileSlug,
+        type,
+      })),
+    ).toEqual([
+      { sourceProfileSlug: "deal", targetProfileSlug: "crm-commission-entitlement", type: "crm_commission_for_deal" },
+    ]);
+  });
+
+  it("relies on CRM's single generic counterparty relationship", () => {
+    expect(
+      crmTemplate.entityLinks?.map(({ sourceProfileSlug, targetProfileSlug, type }) => ({
+        sourceProfileSlug,
+        targetProfileSlug,
+        type,
+      })),
+    ).toEqual([
+      { sourceProfileSlug: "person", targetProfileSlug: "deal", type: "linked_to_deal" },
+      { sourceProfileSlug: "company", targetProfileSlug: "deal", type: "linked_to_deal" },
+    ]);
+  });
+
+  it("keeps playbooks lead-first and proposal-gated", () => {
+    expect(
+      template.playbooks?.map(({ name, subjectProfile }) => ({ name, profileSlug: subjectProfile?.profileSlug })),
+    ).toEqual([
+      { name: "Qualify a CRM lead", profileSlug: "crm-lead" },
+      { name: "Advance a commercial proposal", profileSlug: "deal" },
+    ]);
+    expect(template.playbooks?.[0]?.goalTemplate ?? "").toMatch(/Do not create a deal/);
+    expect(template.playbooks?.[1]?.goalTemplate ?? "").toMatch(/Never mark the counterparty as a CRM client/);
+  });
+
+  it("declares the complete, human-confirmed handoff as a reusable flow", () => {
+    const handoff = template.automations?.find(
+      (automation) => automation.name === "Win and hand off",
+    );
+    expect(handoff).toMatchObject({
+      key: "crm-win-and-handoff",
+      triggerType: "manual",
+      status: "active",
+    });
+    expect(handoff?.flow.nodes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: "read-deal", type: "entity_read" }),
+        expect.objectContaining({ id: "find-party", type: "related_entities" }),
+        expect.objectContaining({ id: "guard-lead", type: "guard" }),
+        expect.objectContaining({ id: "commission-sequence", type: "select" }),
+        expect.objectContaining({ id: "claim-first-client-deal", type: "claim" }),
+        expect.objectContaining({ id: "claim-commission-entitlement", type: "claim" }),
+        expect.objectContaining({ id: "prior-won-deals", type: "related_entities" }),
+        expect.objectContaining({
+          id: "is-first-client-deal",
+          type: "compute",
+          data: expect.objectContaining({
+            left: "{{steps.claim-first-client-deal.output.claimed}}",
+            right: "{{steps.has-no-prior-won-deals.output.result}}",
+          }),
+        }),
+        expect.objectContaining({ id: "create-commission", type: "output" }),
+        expect.objectContaining({ id: "convert-lead", type: "output" }),
+      ]),
+    );
+    expect(handoff?.flow.nodes).toContainEqual(
+      expect.objectContaining({
+        id: "create-commission",
+        data: expect.objectContaining({
+          outputType: "entity_create",
+          config: expect.objectContaining({ dedupeBy: "sourceDealId" }),
+        }),
+      }),
+    );
+    expect(handoff?.flow.nodes).toContainEqual(
+      expect.objectContaining({
+        id: "guard-deal",
+        data: expect.objectContaining({
+          checks: expect.arrayContaining([
+            expect.objectContaining({
+              path: "steps.read-deal.output.entity.properties.commercialStage",
+              anyOf: expect.arrayContaining([
+                expect.objectContaining({ path: "steps.read-deal.output.entity.properties.commercialStage", equals: "won" }),
+                expect.objectContaining({ path: "steps.read-deal.output.entity.properties.dealStage", equals: "won" }),
+              ]),
+            }),
+          ]),
+        }),
+      }),
+    );
+
+    expect(template.actionPlacements).toEqual([
+      expect.objectContaining({
+        profileSlug: "person",
+        kind: "playbook",
+        ref: "Qualify a CRM lead",
+        when: { requiredFacetSlugs: ["crm-lead"] },
+      }),
+      expect.objectContaining({
+        profileSlug: "company",
+        kind: "playbook",
+        ref: "Qualify a CRM lead",
+        when: { requiredFacetSlugs: ["crm-lead"] },
+      }),
+      expect.objectContaining({
+        profileSlug: "deal",
+        kind: "playbook",
+        ref: "Advance a commercial proposal",
+      }),
+      expect.objectContaining({
+        profileSlug: "deal",
+        kind: "automation",
+        ref: "Win and hand off",
+        label: "Hand off won proposal",
+        when: {
+          propertyAnyEquals: { commercialStage: ["won"], dealStage: ["won"] },
+          propertyNotEquals: { handoffStatus: "handed_off" },
+        },
+        confirmation: expect.objectContaining({
+          confirmLabel: "Hand off proposal",
+        }),
+      }),
+    ]);
+  });
+
+  it("carries playbooks through the workspace-create converter", () => {
+    const { definition } = toWorkspaceDefinition("business-developer");
+    const playbooks = definition.playbooks ?? [];
+
+    expect(playbooks).toHaveLength(2);
+    expect(playbooks[0]).toMatchObject({
+      name: "Qualify a CRM lead",
+      subjectProfile: { profileSlug: "crm-lead" },
+      params: [{ name: "lead", type: "string", description: "CRM lead" }],
+    });
+    expect(playbooks[1]).toMatchObject({
+      name: "Advance a commercial proposal",
+      subjectProfile: { profileSlug: "deal" },
+      params: [{ name: "deal", type: "string", description: "Commercial proposal" }],
+    });
+
+    expect(definition.flowAutomations).toHaveLength(1);
+    expect(definition.flowAutomations?.[0]).toMatchObject({
+      key: "crm-win-and-handoff",
+      name: "Win and hand off",
+      triggerType: "manual",
+      flowDefinition: expect.objectContaining({
+        nodes: expect.arrayContaining([
+          expect.objectContaining({ id: "read-deal", type: "entity_read" }),
+          expect.objectContaining({ id: "commission-sequence", type: "select" }),
+          expect.objectContaining({ id: "claim-first-client-deal", type: "claim" }),
+        ]),
+      }),
+    });
+  });
+});