@open-mercato/core 0.6.6-develop.6381.1.042df302c3 → 0.6.6-develop.6383.1.27fcc83455

package/src/modules/catalog/agentic/standalone-guide.md

@@ -1,79 +0,0 @@
-# Catalog Module — Standalone App Guide
-
-Use the catalog module for products, categories, pricing, variants, and offers.
-
-## Pricing System
-
-Never reimplement pricing logic. Use the catalog pricing service via DI:
-
-```typescript
-const pricingService = container.resolve('catalogPricingService')
-```
-
-- `selectBestPrice` — finds the best price for a given context (customer, channel, quantity)
-- `resolvePriceVariantId` — resolves variant-level prices
-- Register custom pricing resolvers with priority (higher = checked first):
-
-```typescript
-import { registerCatalogPricingResolver } from '@open-mercato/core/modules/catalog/lib/pricing'
-registerCatalogPricingResolver(myResolver, { priority: 10 })
-```
-
-Price layers compose in order: base price → channel override → customer-specific → promotional.
-
-The pipeline emits `catalog.pricing.resolve.before` and `catalog.pricing.resolve.after` events that your module can subscribe to.
-
-## Data Model
-
-| Entity | Purpose | Key Constraints |
-|--------|---------|----------------|
-| **Products** | Core items with media and descriptions | MUST have at least a name |
-| **Categories** | Hierarchical product grouping | No circular parent-child references |
-| **Variants** | Product variations (size, color) | MUST reference valid option schemas |
-| **Prices** | Multi-tier with channel scoping | Use `selectBestPrice` for resolution |
-| **Offers** | Time-limited promotions | MUST have valid date ranges |
-| **Option Schemas** | Variant option type definitions | Cannot delete while variants reference them |
-
-## Subscribing to Catalog Events
-
-React to product lifecycle events in your module:
-
-```typescript
-// src/modules/<your_module>/subscribers/product-updated.ts
-export const metadata = {
-  event: 'catalog.product.updated',
-  persistent: true,
-  id: 'your-module-product-updated',
-}
-
-export default async function handler(payload, ctx) {
-  // payload.resourceId = product ID
-}
-```
-
-Key events:
-- `catalog.product.created` / `updated` / `deleted`
-- `catalog.pricing.resolve.before` / `after` (excluded from workflow triggers)
-
-## Extending Catalog UI
-
-Use widget injection to add your module's UI into catalog pages:
-
-```typescript
-// src/modules/<your_module>/widgets/injection-table.ts
-export const widgetInjections = {
-  'crud-form:catalog.catalog_product:fields': {
-    widgetId: 'your-module-product-fields',
-    priority: 100,
-  },
-}
-```
-
-Common injection spots:
-- `crud-form:catalog.catalog_product:fields` — product edit form
-- `data-table:catalog.products:columns` — product list columns
-- `data-table:catalog.products:row-actions` — product row actions
-
-## Using Catalog in Sales
-
-When building sales-related features, use the catalog pricing service to resolve prices rather than reading price entities directly. This ensures channel scoping, customer-specific pricing, and promotional offers are applied correctly.

package/src/modules/currencies/agentic/standalone-guide.md

@@ -1,43 +0,0 @@
-# Currencies Module — Standalone App Guide
-
-Use the currencies module for multi-currency support, exchange rates, and currency conversion.
-
-## Key Rules
-
-1. **Store amounts with 4 decimal precision** — never truncate to 2 decimals internally
-2. **Use date-based exchange rates** — always resolve rates for the transaction date, not the "current" rate
-3. **Record both currencies** — dual recording (transaction currency + base currency) is mandatory for reporting
-4. **Calculate realized gains/losses** on payment: `(payment rate - invoice rate) × foreign amount`
-5. **Never hard-delete exchange rates** — they are historical reference data
-
-## Multi-Currency Transaction Pattern
-
-When processing multi-currency transactions (e.g., sales invoice in EUR with USD base):
-
-1. Retrieve the exchange rate for the transaction date
-2. Generate the document in the transaction currency
-3. Calculate the base currency equivalent: `foreign amount × rate`
-4. Store both amounts on the document
-5. On payment: calculate realized gain/loss from rate difference
-6. Report in both transaction and base currencies
-
-## Data Model
-
-| Entity | Table | Purpose |
-|--------|-------|---------|
-| **Currency** | `currency` | Currency master data (code, name, symbol) |
-| **Exchange Rate** | `exchange_rate` | Daily exchange rates per currency pair |
-
-## Adding a New Currency
-
-1. Add the currency record via the admin UI or `seedDefaults` hook in your `setup.ts`
-2. Ensure exchange rates exist for the currency pair at required dates
-3. Verify all sales/pricing logic resolves the new currency correctly
-
-## Using Currencies in Your Module
-
-When your module deals with monetary amounts:
-- Store the currency code alongside the amount
-- Reference the currencies module for exchange rate lookups
-- Use the transaction date for rate resolution, not the current date
-- Store both foreign and base amounts for reporting

package/src/modules/customer_accounts/agentic/standalone-guide.md

@@ -1,129 +0,0 @@
-# Customer Accounts Module — Standalone App Guide
-
-Customer-facing identity and portal authentication. This module manages customer user accounts, sessions, roles, and the authentication flow for the customer portal. It is separate from the staff `auth` module.
-
-## Portal Authentication
-
-### Login Flow
-1. Customer submits credentials via `POST /api/login`
-2. Password verified with bcryptjs, lockout checked (5 attempts → 15 min lock)
-3. JWT issued with customer claims (`type: 'customer'`, features, CRM links)
-4. Two cookies set: `customer_auth_token` (JWT, 8h) + `customer_session_token` (raw, 30d)
-
-### Other Auth Methods
-- **Signup**: `POST /api/signup` — self-registration with email verification
-- **Magic Link**: `POST /api/magic-link/request` + `/verify` — passwordless login (15 min TTL)
-- **Password Reset**: `POST /api/password/reset-request` + `/reset-confirm` (60 min TTL)
-- **Invitation**: Admin invites user → `POST /api/invitations/accept` (72h TTL)
-
-## Customer RBAC
-
-### Two-Layer Model (mirrors staff RBAC)
-1. **Role ACLs** — features assigned to roles
-2. **User ACLs** — per-user overrides (takes precedence if present)
-
-### Default Roles (seeded on tenant creation)
-| Role | Features | Portal Admin |
-|------|----------|-------------|
-| Portal Admin | `portal.*` | Yes |
-| Buyer | Orders, quotes, catalog, account | No |
-| Viewer | Read-only orders, invoices, catalog | No |
-
-### Feature Convention
-Portal features use `portal.<area>.<action>` naming (e.g., `portal.orders.view`, `portal.catalog.view`).
-
-### Cross-Module Feature Merging
-Your module can declare `defaultCustomerRoleFeatures` in `setup.ts`. During tenant setup, these are merged into the corresponding customer role ACLs:
-
-```typescript
-// src/modules/<your_module>/setup.ts
-export const setup: ModuleSetupConfig = {
-  defaultCustomerRoleFeatures: {
-    portal_admin: ['portal.your_feature.*'],
-    buyer: ['portal.your_feature.view'],
-  },
-}
-```
-
-## Using Customer Auth in Your Module
-
-### Server Components (pages)
-```typescript
-import { getCustomerAuthFromCookies } from '@open-mercato/core/modules/customer_accounts/lib/customerAuthServer'
-
-const auth = await getCustomerAuthFromCookies()
-if (!auth) redirect('/login')
-```
-
-### API Routes
-```typescript
-import { requireCustomerAuth, requireCustomerFeature } from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
-import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
-import type { CustomerRbacService } from '@open-mercato/core/modules/customer_accounts/services/customerRbacService'
-
-// In your API handler:
-const auth = await requireCustomerAuth(request)  // throws 401 if not authenticated
-const container = await createRequestContainer()
-const customerRbacService = container.resolve('customerRbacService') as CustomerRbacService
-// Re-resolves ACL on every request so role/feature revocation is immediate
-await requireCustomerFeature(auth, ['portal.orders.view'], customerRbacService)  // throws 403 if missing
-```
-
-### RBAC Service
-```typescript
-const rbacService = container.resolve('customerRbacService')
-const hasAccess = await rbacService.userHasAllFeatures(
-  userId, ['portal.orders.view'], { tenantId, organizationId }
-)
-```
-
-## Portal Page Guards
-
-Use declarative metadata for portal pages:
-
-```typescript
-export const metadata = {
-  requireCustomerAuth: true,
-  requireCustomerFeatures: ['portal.orders.view'],
-}
-```
-
-## Subscribing to Customer Events
-
-| Event | When |
-|-------|------|
-| `customer_accounts.user.created` | New customer signup |
-| `customer_accounts.user.updated` | Profile updated |
-| `customer_accounts.user.locked` | Account locked after failed logins |
-| `customer_accounts.login.success` | Successful login |
-| `customer_accounts.invitation.accepted` | Invitation accepted |
-
-```typescript
-export const metadata = {
-  event: 'customer_accounts.user.created',
-  persistent: true,
-  id: 'your-module-customer-signup',
-}
-
-export default async function handler(payload, ctx) {
-  // React to customer signup — e.g., create default preferences
-}
-```
-
-## CRM Auto-Linking
-
-When a customer signs up, the module automatically searches for a matching CRM person by email and links them (`personEntityId`). The reverse also works — creating a CRM person auto-links to an existing customer user.
-
-## Widget Injection Spots
-
-| Spot | Widget | Purpose |
-|------|--------|---------|
-| `crud-form:customers:customer_person_profile:fields` | Account status | Shows portal account status on CRM person detail |
-| `crud-form:customers:customer_company_profile:fields` | Company users | Shows portal users linked to a CRM company |
-
-## Security Notes
-
-- All public endpoints are rate-limited (per-email + per-IP)
-- Tokens stored as SHA-256 hashes — raw tokens never persisted
-- Emails use deterministic hash for lookups (`hashForLookup`)
-- Error messages never confirm whether an email is registered

package/src/modules/customers/agentic/standalone-guide.md

@@ -1,138 +0,0 @@
-# Customers Module — Reference CRUD Patterns
-
-This is the **reference CRUD module**. When building new modules in your standalone app, follow these patterns.
-
-## CRUD API Pattern
-
-Use `makeCrudRoute` with `indexer: { entityType }` for query index coverage:
-
-```typescript
-// src/modules/<your_module>/api/get/<entities>.ts
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
-import { YourEntity } from '../../entities/YourEntity'
-
-const handler = makeCrudRoute({
-  entity: YourEntity,
-  entityId: 'your_module.your_entity',
-  operations: ['list', 'detail'],
-  indexer: { entityType: 'your_module.your_entity' },
-})
-
-export default handler
-export const openApi = { summary: 'List and retrieve entities', tags: ['Your Module'] }
-```
-
-Key points:
-- Always set `indexer: { entityType }` — keeps custom entities indexed
-- Wire custom field helpers for create/update if your module supports custom fields
-- Export `openApi` on every API route file
-
-## Undoable Commands Pattern
-
-All write operations should use the Command pattern with undo support:
-
-```typescript
-import { registerCommand } from '@open-mercato/shared/lib/commands'
-import { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
-
-registerCommand('your_module.entity.create', {
-  async execute(payload, ctx) {
-    // 1. Create entity
-    // 2. Capture snapshot for undo: extractUndoPayload(entity)
-    // 3. Side effects: emitCrudSideEffects({ indexer: { entityType, cacheAliases } })
-  },
-  async undo(payload, ctx) {
-    // 1. Restore from snapshot
-    // 2. Side effects: emitCrudUndoSideEffects({ indexer: { entityType, cacheAliases } })
-  },
-})
-```
-
-Key points:
-- Include `indexer: { entityType, cacheAliases }` in both `emitCrudSideEffects` and `emitCrudUndoSideEffects`
-- Capture custom field snapshots in `before`/`after` payloads (`snapshot.custom`)
-- Restore custom fields via `buildCustomFieldResetMap(before.custom, after.custom)` in undo
-
-## Custom Field Integration
-
-```typescript
-import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
-```
-
-- Pass `{ transform }` to normalize values (e.g., `normalizeCustomFieldSubmitValue`)
-- Works for both `cf_` and `cf:` prefixed keys
-- Pass `entityIds` to form helpers so correct custom-field sets are loaded
-- If your module ships default custom fields, declare them in `ce.ts` via `entities[].fields`
-
-## Search Configuration
-
-Declare in `search.ts` with all three strategies:
-
-```typescript
-import type { SearchModuleConfig } from '@open-mercato/shared/modules/search'
-
-export const searchConfig: SearchModuleConfig = {
-  entities: {
-    'your_module.your_entity': {
-      fields: ['name', 'description'],  // Fulltext indexing
-      // fieldPolicy for sensitive field handling
-      // buildSource for vector embeddings
-      // formatResult for search result display
-    },
-  },
-}
-```
-
-Key points:
-- Use `fieldPolicy.excluded` for sensitive fields (passwords, tokens)
-- Use `fieldPolicy.hashOnly` for PII needing exact-match only (email, phone)
-- Always define `formatResult` for human-friendly search results
-
-## Backend Page Structure
-
-Follow this pattern for each page type:
-
-| Page | Pattern | Key Features |
-|------|---------|-------------|
-| **List** | `DataTable` | Filters, search, export, row actions, pagination |
-| **Create** | `CrudForm` mode=create | Fields, groups, custom fields, back link |
-| **Detail/Edit** | `CrudForm` mode=edit or tabbed layout | Entity data, related entities, activities |
-
-## Module Files Checklist
-
-When scaffolding a new CRUD module, ensure all these files are present:
-
-| File | Purpose |
-|------|---------|
-| `index.ts` | Module metadata |
-| `acl.ts` | Feature-based permissions |
-| `setup.ts` | Tenant init, default role features |
-| `di.ts` | Awilix DI registrations |
-| `events.ts` | Typed event declarations |
-| `data/entities.ts` | MikroORM entity classes |
-| `data/validators.ts` | Zod validation schemas |
-| `search.ts` | Search indexing configuration |
-| `ce.ts` | Custom entities / custom field sets |
-
-Optional:
-- `translations.ts` — translatable fields per entity
-- `notifications.ts` — notification type definitions
-- `cli.ts` — module CLI commands
-
-## Entity Update Safety
-
-When mutating entities across multiple phases that include queries:
-
-```typescript
-import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
-
-await withAtomicFlush(em, [
-  () => { record.name = 'New'; record.status = 'active' },
-  () => syncEntityTags(em, record, tags),
-], { transaction: true })
-
-// Side effects AFTER the atomic flush
-await emitCrudSideEffects({ ... })
-```
-
-Never run `em.find`/`em.findOne` between scalar mutations and `em.flush()` without `withAtomicFlush` — changes will be silently lost. Cache invalidation must also stay outside `withAtomicFlush` and fire after commit, so the opt-in `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` mode (default OFF) never serves stale or partially-committed reads.

package/src/modules/data_sync/agentic/standalone-guide.md

@@ -1,107 +0,0 @@
-# Data Sync Module — Standalone App Guide
-
-The data sync module provides a streaming synchronization hub for import/export operations with external systems. Provider modules register `DataSyncAdapter` implementations.
-
-## Creating a Sync Adapter
-
-Implement the `DataSyncAdapter` interface in your provider module:
-
-```typescript
-import type { DataSyncAdapter } from '@open-mercato/core/modules/data_sync/lib/adapter'
-
-const myAdapter: DataSyncAdapter = {
-  providerKey: 'my_provider',
-  direction: 'import',  // 'import' | 'export' | 'bidirectional'
-  supportedEntities: ['catalog.product', 'customers.person'],
-
-  async *streamImport(entityType, cursor, config) {
-    // Yield ImportBatch objects with records
-    yield { records: [...], cursor: 'next-page-token' }
-  },
-
-  async validateConnection(credentials) {
-    // Verify external system is reachable
-    return { valid: true }
-  },
-
-  async getInitialCursor(entityType) {
-    return null  // Start from beginning
-  },
-}
-```
-
-Register in your module's `di.ts`:
-```typescript
-import { registerDataSyncAdapter } from '@open-mercato/core/modules/data_sync/lib/adapter-registry'
-registerDataSyncAdapter(myAdapter)
-```
-
-## Run Lifecycle
-
-```
-pending → running → completed | failed | cancelled
-```
-
-- **Cursor persistence**: After each batch, cursor is saved — enables resume on failure
-- **Progress**: Linked to `ProgressJob` for live progress display via `ProgressTopBar`
-- **Cancellation**: Via `progressService.isCancellationRequested()`
-- **Overlap protection**: Only one sync per integration + entityType + direction at a time
-
-## Key Services (DI)
-
-| Service | Purpose |
-|---------|---------|
-| `dataSyncRunService` | CRUD for sync runs, cursor management, overlap detection |
-| `dataSyncEngine` | Orchestrates streaming import/export with batch processing and progress |
-| `externalIdMappingService` | Maps local entity IDs to/from external system IDs |
-
-## Starting a Sync
-
-Via API:
-```
-POST /api/data_sync/run
-{ "integrationId": "my_provider", "entityType": "catalog.product", "direction": "import" }
-```
-
-Syncs run asynchronously via the queue system — never run inline in API handlers.
-
-## Queue Workers
-
-| Queue | Worker | Concurrency |
-|-------|--------|-------------|
-| `data-sync-import` | Import handler | 5 |
-| `data-sync-export` | Export handler | 5 |
-| `data-sync-scheduled` | Scheduled sync dispatch | 3 |
-
-## Events
-
-| Event | When |
-|-------|------|
-| `data_sync.run.started` | Sync begins processing |
-| `data_sync.run.completed` | Sync finishes successfully |
-| `data_sync.run.failed` | Sync fails |
-| `data_sync.run.cancelled` | Sync is cancelled |
-
-Subscribe to these events to trigger post-sync side effects in your module.
-
-## UMES Extension Points
-
-Sync providers can extend the platform UI:
-
-| Extension | Use Case |
-|-----------|----------|
-| **Widget Injection** | Sync status badges, mapping previews on entity pages |
-| **Event Subscribers** | React to sync lifecycle events |
-| **Entity Extensions** | Link sync metadata to core entities |
-| **Response Enrichers** | Attach external ID data to API responses |
-| **Notifications** | Alerts on sync completion/failure |
-| **DOM Event Bridge** | Real-time sync progress via SSE |
-| **Menu Injection** | Provider-specific sync dashboards in sidebar |
-
-## Key Rules
-
-- Always scope queries by `organizationId` + `tenantId`
-- Use the queue system — never run syncs inline
-- Persist cursor after each batch — enables resume on failure
-- Log item-level errors — don't stop the sync for individual failures
-- Check for overlap before starting a new run

package/src/modules/integrations/agentic/standalone-guide.md

@@ -1,113 +0,0 @@
-# Integrations Module — Standalone App Guide
-
-The integrations module provides the foundation for all external connectors (payment gateways, shipping carriers, data sync providers, etc.). It offers three shared mechanisms: **Integration Registry**, **Credentials API**, and **Operation Logs**.
-
-## Creating an Integration Provider
-
-Create a new module in your app for each provider:
-
-1. Create `src/modules/<provider_id>/` with standard module files
-2. Add `integration.ts` at the module root exporting an `IntegrationDefinition`:
-
-```typescript
-import type { IntegrationDefinition } from '@open-mercato/shared/modules/integrations/types'
-
-export const integration: IntegrationDefinition = {
-  id: 'my_provider',
-  name: 'My Provider',
-  description: 'Integration with My Provider',
-  category: 'payment',
-  credentials: {
-    fields: [
-      { key: 'apiKey', label: 'API Key', type: 'password', required: true },
-      { key: 'environment', label: 'Environment', type: 'select', options: ['sandbox', 'production'] },
-    ],
-  },
-  healthCheck: { service: 'myProviderHealthCheck' },  // optional
-  apiVersions: ['v1', 'v2'],                          // optional
-}
-```
-
-3. Register the health check service in `di.ts` (if declared)
-4. Run `yarn generate` to auto-discover the integration
-
-## Key Services (DI)
-
-| Service | Purpose |
-|---------|---------|
-| `integrationCredentialsService` | Encrypted credential CRUD with bundle fallthrough |
-| `integrationStateService` | Enable/disable, API version, reauth, health state |
-| `integrationLogService` | Structured logging with scoped loggers |
-| `integrationHealthService` | Resolves and runs provider health checks |
-
-## Credential Resolution
-
-1. Direct credentials for the integration ID
-2. If `bundleId` is set, fallback to bundle's credentials
-3. Returns `null` if neither exists
-
-## Bundle Integrations
-
-For platform connectors with multiple integrations (e.g., an ERP with products + orders sync):
-
-```typescript
-export const bundle: IntegrationBundle = {
-  id: 'my_erp',
-  name: 'My ERP',
-  integrations: ['my_erp_products', 'my_erp_orders'],
-}
-```
-
-- Set `bundleId` on each child integration
-- Bundle credentials are shared via fallthrough
-
-## Events
-
-| Event | When |
-|-------|------|
-| `integrations.credentials.updated` | Credentials saved |
-| `integrations.state.updated` | Integration enabled/disabled |
-| `integrations.version.changed` | API version changed |
-| `integrations.log.created` | Log entry written |
-
-## Extending the Integration Detail Page
-
-Provider modules can add tabs, cards, or sections to the integration detail page:
-
-```typescript
-// integration.ts
-import { buildIntegrationDetailWidgetSpotId } from '@open-mercato/shared/modules/integrations/types'
-
-export const integration = {
-  id: 'my_provider',
-  detailPage: {
-    widgetSpotId: buildIntegrationDetailWidgetSpotId('my_provider'),
-  },
-} satisfies IntegrationDefinition
-```
-
-Register widgets for that spot in `widgets/injection-table.ts`. Use `placement.kind: 'tab'` for additional tabs, `'group'` for card panels, `'stack'` for inline sections.
-
-## UMES Extension Points
-
-Integration providers can leverage the full extension system:
-
-| Extension | Use Case |
-|-----------|----------|
-| **Widget Injection** | Inject status badges, config panels into other modules |
-| **Event Subscribers** | React to integration events for side-effects |
-| **Entity Extensions** | Link provider data to core entities (e.g., external IDs) |
-| **Response Enrichers** | Attach provider data to API responses |
-| **API Interceptors** | Intercept routes with before/after hooks |
-| **Notifications** | In-app alerts on integration events |
-| **DOM Event Bridge** | Real-time updates via SSE (`clientBroadcast: true`) |
-
-## Provider-Owned Env Preconfiguration
-
-If your provider needs credentials or settings after a fresh install:
-
-- Read env vars in a provider-local helper (e.g., `lib/preset.ts`)
-- Apply from your module's `setup.ts` for automatic tenant bootstrap
-- Expose a CLI command for rerunning the bootstrap
-- Use provider-prefixed env names (e.g., `OM_INTEGRATION_MYPROVIDER_*`)
-- Persist through normal integration services — never special-case in core