@vantageos/crm-core

Core schema definitions and pure lib helpers for VantageCRM.

Status: C1.1 pre-extraction scaffold

This package is at stage C1.1 of the Vantage Immo modularisation plan. It re-exports code from vantageos-crm without copying or modifying it. Full extraction into this package as a standalone module happens at C1.7 (refactor + consume phase).

Sources currently live in vantageos-crm:

• Schemas: convex/schemas/<table>.ts
• Lib helpers: convex/lib/workspace.ts, convex/lib/rbac.ts, convex/lib/auditLog.ts
• Custom field validation: convex/crm/customFields.ts

What this package exports

Schemas (Convex defineTable results)

| Export | Source table | |---|---| | workspacesSchema | workspaces | | workspaceMembersSchema | workspaceMembers | | customFieldDefinitionsSchema | custom_field_definitions | | customObjectDefinitionsSchema | custom_object_definitions | | customObjectRecordsSchema | custom_object_records | | auditLogSchema | audit_log |

Lib helpers (pure, context-free — no Convex runtime dependency)

| Export | Type | Description | |---|---|---| | Actor | type | Actor interface (actorId, actorType, auditActorType) | | ActorType | type | Union: user / agent / agent:composio / system | | WorkspaceAccessResult | type | Result of workspace access validation | | buildActor | function | Build actor from clerkId + optional override | | CrmScope | type | Scope tiers: read / write / admin / cloud-admin | | scopeSatisfies | function | Check if grantedScope satisfies requiredScope | | roleToScope | function | Map workspace role to CRM scope | | canViewField | function | D-003 field-level RBAC check | | requireScopeFromScopes | function | Validate OAuth scopes array | | AuditAction | type | All valid audit log action values | | AuditActorType | type | user / agent / system | | AuditContext | type | Audit log entry context object | | diffRecords | function | Diff two records to produce fieldChanges array | | FieldType | type | Custom field type union | | FieldDefinitionShape | type | Custom field definition shape | | validateCustomFieldValue | function | Validate a value against a field definition |

Not exported (Convex runtime)

Functions that depend on Convex ctx (MutationCtx / QueryCtx) and _generated/ types are not exported — they require the consuming project to have Convex configured. Import those directly from your Convex project:

// In your Convex functions:
import { loadWorkspaceOrThrow, validateWorkspaceAccess, assertWorkspaceAccess } from '../lib/workspace';
import { requireScope, assertAdminScope, checkSubscriptionScope } from '../lib/rbac';
import { withAuditLog, withAuditLogDiff } from '../lib/auditLog';

Modularisation plan

| Stage | Description | Status | |---|---|---| | C1.1 | Scaffold extract — re-exports, zero behavioral change | Current | | C1.2 | E1: relation field type | Upcoming | | C1.3 | E4: record-owner scope (assertRecordOwnership) | Upcoming | | C1.4 | E5: scope prefix paramétrable (VANTAGE_SCOPE_PREFIX) | Upcoming | | C1.5 | E2: typed TypeScript client | Upcoming | | C1.6 | E3: full payload JSON validation | Upcoming | | C1.7 | Refactor vantageos-crm to consume this package (tests 186/186) | Upcoming | | C1.8 | Test acceptance — Vantage Immo deploy | Upcoming |

License

FSL-1.1-ALv2 — see LICENSE file.