@open-mercato/shared 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/modules/overrides.ts

@@ -116,6 +116,21 @@ export interface EncryptionOverridesShape {
   maps?: EncryptionMapOverridesMap | LooseOverrideMap
 }
 
+/**
+ * Backend navigation ordering.
+ *
+ * `groupOrder` **prepends** sidebar nav group ids: the ids listed here rank ahead of every other
+ * group, in the order given, and any group not named keeps the ordering it has today. Prepending
+ * rather than replacing means an app that only cares about its own group lists that one id, instead of
+ * having to enumerate every shipped group and accidentally demoting the ones it forgot.
+ *
+ * This is a *default*, applied beneath both role and user sidebar preferences — an operator's own
+ * arrangement still wins.
+ */
+export interface NavOverridesShape {
+  groupOrder?: string[]
+}
+
 /**
  * Umbrella shape for `entry.overrides`. Every key is optional; a
  * downstream app sets only the domains it cares about.
@@ -136,6 +151,7 @@ export interface ModuleOverrides {
   acl?: AclOverridesShape
   di?: DiOverridesMap | LooseOverrideMap
   encryption?: EncryptionOverridesShape
+  nav?: NavOverridesShape
 }
 
 /**
@@ -175,6 +191,7 @@ export type ModuleOverrideDomain =
   | 'acl'
   | 'di'
   | 'encryption'
+  | 'nav'
 
 export interface ModuleOverrideEntry<TShape> {
   moduleId: string
@@ -227,6 +244,7 @@ const DOMAIN_KEYS: ModuleOverrideDomain[] = [
   'acl',
   'di',
   'encryption',
+  'nav',
 ]
 
 const TRACKING_ISSUE_HINT =
@@ -441,6 +459,71 @@ const encryptionMapOverrideStore: OverrideStore<ModuleEncryptionMap> = { modules
 const diOverrideStore: OverrideStore<Exclude<DiBindingOverride, null>> = { modules: {}, programmatic: {} }
 const setupOverridesByModule: Record<string, SetupOverridesShape> = {}
 
+/**
+ * Sidebar nav ordering state.
+ *
+ * Persisted on `globalThis` rather than in a module-local variable. This is the one override domain
+ * whose consumer lives in a *different package* (`@open-mercato/core`'s backend chrome reads what the
+ * app's bootstrap wrote), and standalone builds can evaluate `@open-mercato/shared` through more than
+ * one server chunk — bootstrap would store the value in one instance while the reader saw `null` from
+ * another. See `.ai/lessons.md`, "Global registries in publishable packages must use `globalThis`".
+ *
+ * Two tiers, matching every other override domain and the documented resolution order: programmatic
+ * calls win over `modules.ts` inline declarations.
+ */
+const GLOBAL_NAV_OVERRIDE_STATE_KEY = '__openMercatoNavOverrideState__'
+
+type NavOverrideState = {
+  /** From `modules.ts` inline `overrides.nav`, with the module entry that supplied it. */
+  modules: { moduleId: string; groupOrder: string[] } | null
+  /** From `applyNavGroupOrderOverrides`. Takes precedence over `modules`. */
+  programmatic: string[] | null
+}
+
+function getNavOverrideState(): NavOverrideState {
+  const existing = (globalThis as Record<string, unknown>)[GLOBAL_NAV_OVERRIDE_STATE_KEY]
+  if (existing && typeof existing === 'object') {
+    const typed = existing as NavOverrideState
+    if ('modules' in typed && 'programmatic' in typed) return typed
+  }
+  const initial: NavOverrideState = { modules: null, programmatic: null }
+  ;(globalThis as Record<string, unknown>)[GLOBAL_NAV_OVERRIDE_STATE_KEY] = initial
+  return initial
+}
+
+/** Drops blank/duplicate ids and returns `null` when nothing usable remains. */
+function normalizeNavGroupOrder(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null
+  const ids = Array.from(
+    new Set(
+      value
+        .filter((id): id is string => typeof id === 'string' && id.trim().length > 0)
+        .map((id) => id.trim()),
+    ),
+  )
+  return ids.length > 0 ? ids : null
+}
+
+/**
+ * Programmatic nav ordering, for env-driven boot decisions and tests. Takes precedence over
+ * `modules.ts` inline `overrides.nav`, consistent with the other domains' programmatic tier. Pass
+ * `null` to clear it and fall back to the inline declaration.
+ */
+export function applyNavGroupOrderOverrides(groupOrder: string[] | null): void {
+  getNavOverrideState().programmatic = groupOrder === null ? null : normalizeNavGroupOrder(groupOrder)
+}
+
+/**
+ * Nav group ids an app wants ranked ahead of the built-in order, or `null` when none is configured.
+ *
+ * Consumers MUST treat `null` as "use the shipped ordering unchanged" — this is a default, applied
+ * beneath role and user sidebar preferences.
+ */
+export function getNavGroupOrderOverride(): readonly string[] | null {
+  const state = getNavOverrideState()
+  return state.programmatic ?? state.modules?.groupOrder ?? null
+}
+
 function normalizeIdOverrideKey(key: string, label: string): string | null {
   if (typeof key !== 'string') return null
   const trimmed = key.trim()
@@ -721,6 +804,9 @@ export function resetModuleContractOverridesForTests(): void {
   clearStore(encryptionMapOverrideStore)
   clearStore(diOverrideStore)
   for (const key of Object.keys(setupOverridesByModule)) delete setupOverridesByModule[key]
+  const navState = getNavOverrideState()
+  navState.modules = null
+  navState.programmatic = null
 }
 
 /**
@@ -1500,7 +1586,24 @@ function encryptionOverridesApplier(entries: ReadonlyArray<ModuleOverrideEntry<E
   }
 }
 
+function navOverridesApplier(entries: ReadonlyArray<ModuleOverrideEntry<NavOverridesShape>>): void {
+  const state = getNavOverrideState()
+  for (const entry of entries) {
+    const groupOrder = normalizeNavGroupOrder(entry.overrides?.groupOrder)
+    if (!groupOrder) continue
+    if (state.modules && state.modules.moduleId !== entry.moduleId) {
+      logger.warn('nav.groupOrder declared by more than one module — the later one wins', {
+        previousModuleId: state.modules.moduleId,
+        moduleId: entry.moduleId,
+        hint: 'Sidebar group ordering is a single app-wide decision; declare it on one module entry.',
+      })
+    }
+    state.modules = { moduleId: entry.moduleId, groupOrder }
+  }
+}
+
 function registerBuiltInModuleOverrideAppliers(): void {
+  registerModuleOverrideApplier<NavOverridesShape>('nav', navOverridesApplier)
   registerModuleOverrideApplier<RoutesOverridesShape>('routes', routesOverridesApplier)
   registerModuleOverrideApplier<EventsOverridesShape>('events', eventsOverridesApplier)
   registerModuleOverrideApplier<WorkerOverridesMap>('workers', workersOverridesApplier)

package/src/modules/payment_gateways/__tests__/types.test.ts

@@ -0,0 +1,37 @@
+import {
+  clearWebhookHandlers,
+  getWebhookHandler,
+  registerWebhookHandler,
+  type VerifyWebhookInput,
+  type WebhookEvent,
+} from '../types'
+
+const handler = async (_input: VerifyWebhookInput): Promise<WebhookEvent> => ({
+  eventType: 'payment.updated',
+  eventId: 'evt-1',
+  data: {},
+  idempotencyKey: 'evt-1',
+  timestamp: new Date(0),
+})
+
+describe('payment gateway webhook registration', () => {
+  beforeEach(() => {
+    clearWebhookHandlers()
+  })
+
+  it('preserves an optional valid body limit on the registration', () => {
+    registerWebhookHandler('limited', handler, { maxBodyBytes: 64 * 1024 })
+
+    expect(getWebhookHandler('limited')?.maxBodyBytes).toBe(64 * 1024)
+  })
+
+  it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER])(
+    'rejects an invalid body limit: %s',
+    (maxBodyBytes) => {
+      expect(() => registerWebhookHandler('invalid', handler, { maxBodyBytes })).toThrow(
+        '[internal] Payment gateway webhook maxBodyBytes must be a positive safe integer',
+      )
+      expect(getWebhookHandler('invalid')).toBeUndefined()
+    },
+  )
+})

package/src/modules/payment_gateways/types.ts

@@ -1,3 +1,5 @@
+import { DEFAULT_WEBHOOK_BODY_LIMIT_BYTES } from '../../lib/webhooks/body'
+
 // ── Unified Payment Status ──────────────────────────────────────────────────
 
 export type UnifiedPaymentStatus =
@@ -112,6 +114,32 @@ export type PaymentGatewayClientSession =
   | EmbeddedPaymentGatewayClientSession
   | RedirectPaymentGatewayClientSession
 
+// ── Order Amount Reconciliation ─────────────────────────────────────────────
+
+export interface PaymentGatewayScope {
+  organizationId: string
+  tenantId: string
+}
+
+export interface PaymentOrderTotal {
+  orderId: string
+  currencyCode: string
+  amountDue: number
+}
+
+/**
+ * Contract a module that owns orders implements so `payment_gateways` can
+ * reconcile a caller-supplied session amount against the authoritative amount
+ * due, without depending on that module. Implementations MUST scope the lookup
+ * by tenant and organization and MUST return `null` for anything outside the
+ * caller's scope, so an out-of-scope order is indistinguishable from a missing
+ * one. The `sales` module registers the default implementation under the
+ * `paymentOrderTotalResolver` DI name.
+ */
+export interface PaymentOrderTotalResolver {
+  resolveOrderTotal(orderId: string, scope: PaymentGatewayScope): Promise<PaymentOrderTotal | null>
+}
+
 // ── Input / Output Types ────────────────────────────────────────────────────
 
 export interface CreateSessionInput {
@@ -225,6 +253,7 @@ export interface WebhookHandlerRegistration {
   handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>
   queue?: string
   readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
+  maxBodyBytes?: number
 }
 
 // ── Adapter Registry Options ────────────────────────────────────────────────
@@ -319,13 +348,25 @@ export function registerWebhookHandler(
   options?: {
     queue?: string
     readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
+    maxBodyBytes?: number
   },
 ): () => void {
+  if (
+    options?.maxBodyBytes !== undefined
+    && (!Number.isSafeInteger(options.maxBodyBytes)
+      || options.maxBodyBytes <= 0
+      || options.maxBodyBytes > DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+  ) {
+    throw new Error(
+      `[internal] Payment gateway webhook maxBodyBytes must be a positive safe integer no greater than ${DEFAULT_WEBHOOK_BODY_LIMIT_BYTES}`,
+    )
+  }
   const webhookHandlerRegistry = getWebhookHandlerRegistry()
   webhookHandlerRegistry.set(providerKey, {
     handler,
     queue: options?.queue,
     readSessionIdHint: options?.readSessionIdHint,
+    maxBodyBytes: options?.maxBodyBytes,
   })
   return () => {
     webhookHandlerRegistry.delete(providerKey)

package/src/modules/registry.ts

@@ -194,6 +194,8 @@ export type ModuleWorker = {
   moduleId?: string
   queue: string
   concurrency: number
+  lockDuration?: number
+  maxStalledCount?: number
   handler: ModuleWorkerHandler
 }
 
@@ -513,6 +515,7 @@ export function getDefaultEncryptionMaps(modules: Module[]): import('./encryptio
         moduleId: mod.id,
         map: {
           entityId: entry.entityId,
+          ...(entry.keyScope ? { keyScope: entry.keyScope } : {}),
           fields: entry.fields.map((field) => ({
             field: field.field,
             hashField: field.hashField ?? null,

package/src/modules/widgets/__tests__/extension-points.test.ts

@@ -0,0 +1,101 @@
+import {
+  CRUD_FORM_EXTENSION_SURFACES,
+  CRUD_FORM_LIFECYCLE_PHASES,
+  CRUD_FORM_OPERATIONS,
+  DATA_TABLE_EXTENSION_SURFACES,
+  crudFormExtensionHost,
+  crudFormExtensionSpotId,
+  dataTableExtensionHost,
+  dataTableExtensionSpotId,
+  defineModuleExtensionPoints,
+  extensionSpotChildId,
+  injectionExtensionHost,
+  resolveExtensionPointPattern,
+} from '@open-mercato/shared/modules/widgets/extension-points'
+
+describe('module extension point declarations', () => {
+  it('preserves exact ids and immutable declarations', () => {
+    const extensionPoints = defineModuleExtensionPoints({
+      moduleId: 'catalog',
+      hosts: {
+        products: dataTableExtensionHost({
+          baseSpotId: 'data-table:catalog.products',
+          tableId: 'catalog.products.list',
+          source: 'components/products/ProductsDataTable.tsx',
+        }),
+        productForm: crudFormExtensionHost({
+          entityId: 'catalog.product',
+          spotId: 'crud-form:catalog.product',
+          source: 'backend/catalog/products/[id]/page.tsx',
+        }),
+      },
+    })
+
+    expect(extensionPoints.moduleId).toBe('catalog')
+    expect(extensionPoints.hosts.products.tableId).toBe('catalog.products.list')
+    expect(Object.isFrozen(extensionPoints)).toBe(true)
+    expect(Object.isFrozen(extensionPoints.hosts)).toBe(true)
+  })
+
+  it('requires named parameters for dynamic patterns', () => {
+    // @ts-expect-error patterned declarations require named parameters
+    expect(() => injectionExtensionHost({
+      family: 'integration',
+      pattern: 'integrations.detail:{integrationId}',
+      supported: ['render-widget'],
+      source: 'backend/integrations/[id]/page.tsx',
+    })).toThrow('patterned injection extension hosts require named parameters')
+  })
+
+  it('describes only the surfaces bound by DataTable and CrudForm', () => {
+    expect(DATA_TABLE_EXTENSION_SURFACES.filter((surface) => surface.bound).map((surface) => surface.key)).toEqual([
+      'header',
+      'footer',
+      'toolbar',
+      'searchTrailing',
+      'columns',
+      'rowActions',
+      'bulkActions',
+      'filters',
+      'replacement',
+    ])
+    expect(DATA_TABLE_EXTENSION_SURFACES.find((surface) => surface.key === 'emptyState')?.bound).toBe(false)
+    expect(CRUD_FORM_EXTENSION_SURFACES.filter((surface) => !surface.bound).map((surface) => surface.key)).toEqual([
+      'beforeFields',
+      'afterFields',
+      'footer',
+      'sidebar',
+      'group',
+      'fieldBefore',
+      'fieldAfter',
+    ])
+    expect(CRUD_FORM_LIFECYCLE_PHASES).toEqual([
+      'transformValidation',
+      'transformDisplayData',
+      'onBeforeNavigate',
+      'onAppEvent',
+      'onVisibilityChange',
+      'onBeforeDelete',
+      'onDelete',
+      'onAfterDelete',
+      'onDeleteError',
+      'onFieldChange',
+      'transformFormData',
+      'onBeforeSave',
+      'onSave',
+      'onAfterSave',
+    ])
+    expect(CRUD_FORM_OPERATIONS).toEqual(['create', 'update', 'delete'])
+  })
+
+  it('builds standard family ids without changing punctuation', () => {
+    expect(dataTableExtensionSpotId('catalog.products.list', 'columns')).toBe(
+      'data-table:catalog.products.list:columns',
+    )
+    expect(crudFormExtensionSpotId('catalog.product', 'fields')).toBe('crud-form:catalog.product:fields')
+    expect(extensionSpotChildId('legacy:custom-host', 'header')).toBe('legacy:custom-host:header')
+    expect(resolveExtensionPointPattern('integrations.detail:{integrationId}', {
+      integrationId: 'stripe',
+    })).toBe('integrations.detail:stripe')
+  })
+})