@open-mercato/cli 0.6.6-develop.6377.1.d26fed7324 → 0.6.6-develop.6382.1.4b9b9091ab

package/dist/agentic/guides/core.integrations.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

package/dist/agentic/guides/core.sales.md

@@ -1,104 +0,0 @@
-# Sales Module — Standalone App Guide
-
-Use the sales module for orders, quotes, invoices, shipments, and payments. This module has the most complex business logic in the system.
-
-## Document Flow
-
-```
-Quote → Order → Invoice
-         ↓
-    Shipments + Payments
-```
-
-- Quotes convert to orders — do not create orders without a source quote (unless configured)
-- Orders track shipments and payments independently
-- Each entity has its own status workflow — do not skip states
-- Returns create line-level adjustments and update `returned_quantity`
-
-## Pricing Calculations
-
-Always use the sales calculation service — never inline price math:
-
-```typescript
-const calcService = container.resolve('salesCalculationService')
-```
-
-- Dispatches `sales.line.calculate.*` and `sales.document.calculate.*` events
-- For catalog pricing: use `selectBestPrice` from the catalog module
-- Register custom line/totals calculators or override via DI
-
-## Channel Scoping
-
-All sales documents are scoped to channels. Channel selection affects:
-- Available pricing tiers
-- Document numbering sequences
-- Visibility in admin UI
-
-## Data Model
-
-### Core Entities
-| Entity | Purpose | Key Constraint |
-|--------|---------|---------------|
-| **Sales Orders** | Confirmed customer orders | MUST have a channel and at least one line |
-| **Sales Quotes** | Proposed orders | MUST track conversion status |
-| **Order/Quote Lines** | Individual items | MUST reference valid products |
-| **Adjustments** | Discounts/surcharges | MUST use registered `AdjustmentKind` |
-
-### Fulfillment
-| Entity | Purpose |
-|--------|---------|
-| **Shipments** | Delivery tracking with status workflow |
-| **Payments** | Payment recording with status workflow |
-| **Returns** | Order returns with line selection and automatic adjustments |
-
-### Configuration (do not modify directly)
-Channels, statuses, payment/shipping methods, price kinds, adjustment kinds, and document numbers — configure via admin UI or `setup.ts` hooks.
-
-## Subscribing to Sales Events
-
-```typescript
-// src/modules/<your_module>/subscribers/order-created.ts
-export const metadata = {
-  event: 'sales.order.created',
-  persistent: true,
-  id: 'your-module-order-created',
-}
-
-export default async function handler(payload, ctx) {
-  // React to new orders
-}
-```
-
-Key events: `sales.order.created` / `updated` / `deleted`, `sales.quote.created` / `updated`, `sales.payment.created`, `sales.shipment.created`
-
-## Extending Sales UI
-
-Widget injection spots:
-
-**Order & Quote detail page:**
-- `sales.document.detail.order:details` — order detail page sections
-- `sales.document.detail.quote:details` — quote detail page sections
-- `sales.document.detail.order:tabs` — order detail page tabs
-- `sales.document.detail.quote:tabs` — quote detail page tabs
-- `detail:sales.order:stage-bar` — order stage bar (empty, ready for extension)
-- `detail:sales.quote:stage-bar` — quote stage bar (empty, ready for extension)
-- `detail:sales.order:closure` — order closure section (empty, ready for extension)
-- `detail:sales.quote:closure` — quote closure section (empty, ready for extension)
-
-**Order list:**
-- `data-table:sales.orders:columns` — order list columns
-- `data-table:sales.orders:row-actions` — order row actions
-
-**Order form:**
-- `crud-form:sales.sales_order:fields` — order detail form
-
-**Payments:**
-- `data-table:sales.payments:columns` — payment list columns
-
-**Payment methods:**
-- `crud-form:sales.payment_method:fields` — payment method form fields
-- `crud-form:sales.sales_payment_method:fields` — sales payment method form fields
-
-## Frontend Pages
-
-- `frontend/quote/` — public-facing quote view for customer acceptance

package/dist/agentic/guides/core.workflows.md

@@ -1,152 +0,0 @@
-# Workflows Module — Standalone App Guide
-
-Use the workflows module for business process automation: defining step-based workflows, executing instances, handling user tasks, and triggering workflows from domain events.
-
-## Using Workflows in Your App
-
-The workflow engine is provided by `@open-mercato/core`. Your standalone app can:
-
-1. **Create workflow definitions** via the visual editor at `/backend/workflows`
-2. **Trigger workflows** from domain events emitted by your modules
-3. **Subscribe to workflow events** for side effects in your modules
-4. **Inject UI widgets** into workflow pages or inject workflow widgets into your pages
-5. **Define user tasks** that require human approval or data entry
-
-## Starting Workflows Programmatically
-
-Resolve the workflow executor via DI — never import lib functions directly:
-
-```typescript
-// In your module's DI-aware context (API route, subscriber, worker)
-const executor = container.resolve('workflowExecutor')
-
-await executor.startWorkflow({
-  workflowId: 'order-approval',  // matches a WorkflowDefinition.workflowId
-  context: {
-    orderId: order.id,
-    orderTotal: order.totalGross,
-    customerName: order.customerName,
-  },
-  organizationId,
-  tenantId,
-})
-```
-
-## Event Triggers
-
-Configure automatic workflow starts from your module's domain events:
-
-1. Create a workflow definition with a `triggers[]` entry in the visual editor or via API
-2. The workflow engine's wildcard subscriber evaluates all non-internal events
-3. Use `filterConditions` to narrow which events match (e.g., only orders above a threshold)
-4. Use `contextMapping` to extract event payload fields into workflow context variables
-5. Use `debounceMs` and `maxConcurrentInstances` to prevent trigger storms
-
-Excluded event prefixes (never trigger workflows): `query_index`, `search`, `workflows`, `cache`, `queue`.
-
-## Subscribing to Workflow Events
-
-React to workflow lifecycle events in your module:
-
-```typescript
-// src/modules/<your_module>/subscribers/workflow-completed.ts
-export const metadata = {
-  event: 'workflows.instance.completed',
-  persistent: true,
-  id: 'your-module-workflow-completed',
-}
-
-export default async function handler(payload, ctx) {
-  // payload.resourceId = instance ID
-  // payload.workflowId = definition ID
-  // payload.context = workflow context variables
-}
-```
-
-Key workflow events your module can subscribe to:
-
-| Event | When it fires |
-|-------|--------------|
-| `workflows.instance.created` | New workflow instance started |
-| `workflows.instance.completed` | Workflow finished successfully |
-| `workflows.instance.failed` | Workflow failed |
-| `workflows.instance.cancelled` | Workflow was cancelled |
-| `workflows.task.created` | User task assigned |
-| `workflows.task.completed` | User task completed |
-| `workflows.step.completed` | Individual step finished |
-
-## Step Types
-
-| Step type | Use case |
-|-----------|----------|
-| `START` | Entry point — every definition has exactly one |
-| `END` | Terminal step — marks workflow as COMPLETED |
-| `USER_TASK` | Human approval or data entry — pauses until task completion |
-| `AUTOMATED` | Executes transition activities immediately and advances |
-| `SUB_WORKFLOW` | Invokes a nested workflow definition |
-| `WAIT_FOR_SIGNAL` | Pauses for an external signal (e.g., payment confirmed) |
-| `WAIT_FOR_TIMER` | Pauses for a configured duration |
-| `PARALLEL_FORK` / `PARALLEL_JOIN` | Splits/merges parallel execution paths |
-
-## Activity Types
-
-Activities execute on transitions between steps:
-
-| Activity type | Use case |
-|---------------|----------|
-| `SEND_EMAIL` | Send templated email |
-| `CALL_API` | Call an internal API endpoint |
-| `CALL_WEBHOOK` | Call an external HTTP endpoint |
-| `UPDATE_ENTITY` | Mutate an entity via the command bus |
-| `EMIT_EVENT` | Emit a domain event |
-| `EXECUTE_FUNCTION` | Run a registered custom function |
-| `WAIT` | Delay execution for a configured duration |
-
-Use `{{context.*}}`, `{{workflow.*}}`, `{{env.*}}`, `{{now}}` for variable interpolation in activity config — never hardcode values.
-
-## Sending Signals
-
-Resume a workflow waiting for an external signal:
-
-```typescript
-const executor = container.resolve('workflowExecutor')
-
-await executor.sendSignal({
-  instanceId: workflowInstanceId,
-  signalName: 'payment_confirmed',
-  payload: { transactionId: '...' },
-  organizationId,
-  tenantId,
-})
-```
-
-## Widget Injection
-
-Inject workflow-related UI into your module's pages, or inject your module's widgets into workflow pages:
-
-```typescript
-// src/modules/<your_module>/widgets/injection-table.ts
-export const widgetInjections = {
-  // Inject into workflow task detail page
-  'workflows.task.detail:after': {
-    widgetId: 'your-module-task-context',
-    priority: 50,
-  },
-}
-```
-
-## Compensation (Saga Pattern)
-
-When a workflow step fails, compensation activities execute in reverse order to undo previous steps. This follows the saga pattern:
-
-- **Sync activities** execute inline and advance immediately
-- **Async activities** enqueue to the `workflow-activities` queue; workflow pauses until completion
-- On failure, compensation runs in reverse — keep activity handlers **idempotent** (check state before mutating)
-
-## Key Rules
-
-- MUST resolve services via DI (`container.resolve('workflowExecutor')`) — never import lib functions directly
-- MUST use `workflowExecutor.startWorkflow()` to create instances — never insert rows directly
-- MUST keep activity handlers idempotent — they may be retried on failure
-- MUST scope all queries by `organization_id` — workflow data is tenant-scoped
-- MUST NOT couple your module to workflow internals — use event triggers and signals for integration