@elevasis/core 0.20.0 → 0.22.0

package/src/auth/multi-tenancy/permissions.ts

@@ -6,13 +6,18 @@
  *   - API middleware (via requireOrganizationPermission(key))
  *   - UI hooks (via useOrganizationPermissions().hasPermission(key))
  *
- * The DB table `org_rol_permissions` mirrors this constant. Reconciliation
- * runs at API boot (insert-or-update only — never auto-delete; see the
- * deletion runbook in the auth-role-system doc -- review/auth-role-system/).
+ * The DB table `org_rol_permissions` mirrors this constant. There is no
+ * runtime reconciler; parity is enforced two ways:
+ *   1. Each migration that adds/removes/modifies a permission must INSERT
+ *      (or UPDATE / DELETE) the corresponding `org_rol_permissions` row in
+ *      the same transaction.
+ *   2. `apps/api/src/auth/multi-tenancy/__tests__/permissions-catalog-sync.integration.test.ts`
+ *      asserts the TS catalog and the DB rows agree; CI fails on drift.
  *
  * Adding a permission:
  *   1. Add an entry below.
- *   2. Add a row to the migration / via reconcilePermissionCatalog at boot.
+ *   2. Add a row to the migration (INSERT INTO org_rol_permissions ...) in
+ *      the same transaction as any policies/grants that reference the key.
  *   3. Reference it in RLS / middleware as needed.
  *   4. Optionally grant it to one or more system roles in org_rol_grants.
  *
@@ -30,15 +35,17 @@ export const PERMISSIONS = {
   OPERATIONS_READ: 'operations.read',
   OPERATIONS_MANAGE: 'operations.manage',
   ACQUISITION_MANAGE: 'acquisition.manage',
-  PROJECTS_MANAGE: 'projects.manage'
+  PROJECTS_MANAGE: 'projects.manage',
+  CLIENTS_MANAGE: 'clients.manage'
 } as const
 
 export type PermissionKey = (typeof PERMISSIONS)[keyof typeof PERMISSIONS]
 
 /**
- * Static metadata for each permission. Mirrored into org_rol_permissions on
- * boot reconciliation. is_org_grantable=false means the permission is reserved
- * to system roles only — custom roles cannot include it (privilege-escalation guard).
+ * Static metadata for each permission. Mirrored into org_rol_permissions by
+ * a migration `INSERT` in the same transaction as any change to this catalog.
+ * is_org_grantable=false means the permission is reserved to system roles
+ * only — custom roles cannot include it (privilege-escalation guard).
  */
 export interface PermissionDescriptor {
   key: PermissionKey
@@ -97,6 +104,11 @@ export const PERMISSION_CATALOG: readonly PermissionDescriptor[] = [
     key: 'projects.manage',
     description: 'Create, update, and delete project records (prj_projects, prj_milestones, prj_tasks, prj_notes)',
     isOrgGrantable: false
+  },
+  {
+    key: 'clients.manage',
+    description: 'Create, update, and delete client hub records (clients, clt_* satellites)',
+    isOrgGrantable: false
   }
 ] as const
 

package/src/business/README.md

@@ -2,7 +2,7 @@
 
 Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
 
-External projects extend these in `foundations/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
+External projects extend these in `core/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
 
 ## Published Exports
 
@@ -49,4 +49,4 @@ export type Deal = BaseDeal
 
 The full pattern is documented in the SDK scaffold bundle: `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
 
-The canonical template demo lives at `external/_template/foundations/types/entities.ts`.
+The canonical template demo lives at `external/_template/core/types/entities.ts`.

package/src/business/acquisition/api-schemas.test.ts

@@ -10,10 +10,12 @@ import {
   AddCompaniesToListRequestSchema,
   AddContactsToListRequestSchema,
   AcqArtifactOwnerKindSchema,
+  AcqListDetailResponseSchema,
   AcqContactResponseSchema,
   AcqContactStatusSchema,
   AcqEmailValidSchema,
   AcqListResponseSchema,
+  AcqListStatusResponseSchema,
   BuildPlanSnapshotSchema,
   CreateArtifactRequestSchema,
   CreateCompanyRequestSchema,
@@ -32,12 +34,15 @@ import {
   DealTaskResponseSchema,
   ExecuteActionRequestSchema,
   IcpRubricSchema,
+  GetListQuerySchema,
   ListArtifactsQuerySchema,
   ListCompaniesQuerySchema,
   ListContactsQuerySchema,
   ListDealsQuerySchema,
   ListDealTasksDueQuerySchema,
   ListMembersQuerySchema,
+  ListReadQuerySchema,
+  ListRecordsQuerySchema,
   ListStatusSchema,
   PipelineStageSchema,
   ScrapingConfigSchema,
@@ -856,6 +861,24 @@ describe('DealDetailResponseSchema (forward-compat)', () => {
     expect(DealDetailResponseSchema.safeParse(withContact).success).toBe(true)
   })
 
+  it('accepts thin client lineage refs on deal detail responses', () => {
+    expect(
+      DealDetailResponseSchema.safeParse({
+        ...baseDeal,
+        client_id: VALID_UUID,
+        lineage: {
+          list: null,
+          projects: [],
+          client: {
+            id: VALID_UUID,
+            name: 'Acme Client',
+            status: 'active'
+          }
+        }
+      }).success
+    ).toBe(true)
+  })
+
   it('accepts extra unknown fields at top level (not strict)', () => {
     expect(DealDetailResponseSchema.safeParse({ ...baseDeal, futureField: 'value' }).success).toBe(true)
   })
@@ -1601,6 +1624,91 @@ describe('ListMembersQuerySchema', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// ListReadQuerySchema
+// ---------------------------------------------------------------------------
+
+describe('ListReadQuerySchema', () => {
+  it('accepts SDK list filters and coerces pagination', () => {
+    const result = ListReadQuerySchema.safeParse({
+      status: 'launched',
+      batch: 'batch-2026-05',
+      vertical: 'veterinary',
+      limit: '25',
+      offset: '50'
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toMatchObject({ limit: 25, offset: 50 })
+    }
+  })
+
+  it('keeps pagination optional for backward-compatible list reads', () => {
+    expect(ListReadQuerySchema.safeParse({}).success).toBe(true)
+  })
+
+  it('rejects unknown fields (strict mode)', () => {
+    expect(ListReadQuerySchema.safeParse({ includeDeals: true }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// GetListQuerySchema
+// ---------------------------------------------------------------------------
+
+describe('GetListQuerySchema', () => {
+  it('defaults to thin deal refs and omits progress unless requested', () => {
+    const result = GetListQuerySchema.safeParse({})
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toEqual({ includeDeals: true, includeProgress: false, dealLimit: 25 })
+    }
+  })
+
+  it('coerces boolean include flags from query strings', () => {
+    const result = GetListQuerySchema.safeParse({
+      includeDeals: 'false',
+      includeProgress: 'true',
+      dealLimit: '10'
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toEqual({ includeDeals: false, includeProgress: true, dealLimit: 10 })
+    }
+  })
+
+  it('rejects unknown fields (strict mode)', () => {
+    expect(GetListQuerySchema.safeParse({ depth: 2 }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ListRecordsQuerySchema
+// ---------------------------------------------------------------------------
+
+describe('ListRecordsQuerySchema', () => {
+  it('accepts contact records for DTC decision-maker enrichment', () => {
+    const result = ListRecordsQuerySchema.safeParse({
+      entity: 'contact',
+      stage: 'decision-makers-enriched'
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('keeps company records valid for qualified and uploaded stages', () => {
+    expect(ListRecordsQuerySchema.safeParse({ entity: 'company', stage: 'qualified' }).success).toBe(true)
+    expect(ListRecordsQuerySchema.safeParse({ entity: 'company', stage: 'uploaded' }).success).toBe(true)
+  })
+
+  it('still rejects unrelated stage/entity combinations', () => {
+    expect(ListRecordsQuerySchema.safeParse({ entity: 'contact', stage: 'qualified' }).success).toBe(false)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // AcqListResponseSchema (forward-compat)
 // ---------------------------------------------------------------------------
@@ -1632,6 +1740,96 @@ describe('AcqListResponseSchema (forward-compat)', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// AcqListDetailResponseSchema
+// ---------------------------------------------------------------------------
+
+describe('AcqListDetailResponseSchema', () => {
+  const baseList = {
+    id: VALID_UUID,
+    organizationId: VALID_UUID,
+    name: 'Test List',
+    description: null,
+    batchIds: [],
+    instantlyCampaignId: null,
+    status: 'draft' as const,
+    metadata: {},
+    launchedAt: null,
+    completedAt: null,
+    createdAt: ISO_TS,
+    scrapingConfig: {},
+    icp: {},
+    pipelineConfig: {}
+  }
+
+  it('accepts thin lineage deal refs on list detail responses', () => {
+    expect(
+      AcqListDetailResponseSchema.safeParse({
+        ...baseList,
+        lineage: {
+          deals: {
+            total: 1,
+            refs: [
+              {
+                id: VALID_UUID,
+                contactEmail: 'lead@example.com',
+                stageKey: 'proposal',
+                stateKey: null,
+                sourceType: 'outreach',
+                lastActivityAt: ISO_TS
+              }
+            ],
+            truncated: false
+          }
+        }
+      }).success
+    ).toBe(true)
+  })
+
+  it('accepts optional progress on list detail responses', () => {
+    expect(
+      AcqListDetailResponseSchema.safeParse({
+        ...baseList,
+        progress: {
+          totalMembers: 0,
+          totalCompanies: 0,
+          byCompanyStage: {},
+          byContactStage: {}
+        }
+      }).success
+    ).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// AcqListStatusResponseSchema
+// ---------------------------------------------------------------------------
+
+describe('AcqListStatusResponseSchema', () => {
+  it('accepts a portfolio summary across acquisition lists', () => {
+    expect(
+      AcqListStatusResponseSchema.safeParse({
+        totalLists: 1,
+        totalCompanies: 10,
+        totalContacts: 5,
+        totalDeals: 2,
+        byStatus: { launched: 1 },
+        lists: [
+          {
+            listId: VALID_UUID,
+            name: 'Pipeline',
+            status: 'launched',
+            totalCompanies: 10,
+            totalContacts: 5,
+            totalDeals: 2,
+            createdAt: ISO_TS
+          }
+        ]
+      }).success
+    ).toBe(true)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // AcqContactResponseSchema (forward-compat)
 // ---------------------------------------------------------------------------