@open-mercato/shared 0.6.7-develop.6860.1.f796b22e80 → 0.6.7

package/src/lib/webhooks/inbound-types.ts

@@ -1,125 +0,0 @@
-/**
- * Inbound webhook handler types (SPEC: 2026-03-23-inbound-webhook-handlers).
- *
- * These mirror the event-subscriber DX: a module exports `webhook-sources.ts`
- * (one or more `WebhookSourceConfig`) and `webhook-handlers/*.ts` files that each
- * export `metadata: WebhookHandlerMeta` plus a default handler function.
- */
-
-/** Raw inbound request passed to a source verifier. */
-export interface InboundWebhookRequest {
-  /** Raw request body, required for signature verification. */
-  body: string
-  /** Lower-cased request headers. */
-  headers: Record<string, string>
-  /** Parsed request body (best-effort JSON). */
-  parsedBody: Record<string, unknown>
-}
-
-/** Optional descriptor of the credential fields a source needs (drives the admin UI). */
-export interface WebhookSourceCredentialField {
-  key: string
-  label: string
-  secret?: boolean
-  required?: boolean
-}
-
-/**
- * Configuration for an external webhook source (e.g. `stripe`, `resend`).
- * Declared in a module's `webhook-sources.ts` via the `webhookSources` export.
- */
-export interface WebhookSourceConfig {
-  /** Unique source identifier, e.g. `stripe`. Also the inbound path segment. */
-  key: string
-  /** Human-readable label. */
-  label: string
-  /**
-   * Verify the authenticity of an inbound webhook.
-   * Return true if valid, false to reject with 401. Throwing rejects with 400/500.
-   */
-  verifier: (
-    request: InboundWebhookRequest,
-    credentials: Record<string, string>,
-  ) => Promise<boolean>
-  /** Extract the event type from the parsed body/headers. */
-  eventTypeExtractor: (
-    body: Record<string, unknown>,
-    headers: Record<string, string>,
-  ) => string
-  /** Extract a unique message id for deduplication. Return undefined if unavailable. */
-  messageIdExtractor?: (
-    body: Record<string, unknown>,
-    headers: Record<string, string>,
-  ) => string | undefined
-  /** Optionally derive tenant scope from the payload/headers. */
-  scopeExtractor?: (
-    body: Record<string, unknown>,
-    headers: Record<string, string>,
-  ) => { tenantId?: string; organizationId?: string }
-  /** Credential fields this source needs; used by the source-credential admin UI. */
-  credentialFields?: WebhookSourceCredentialField[]
-}
-
-/** Metadata exported by every `webhook-handlers/*.ts` file. */
-export interface WebhookHandlerMeta {
-  /** Source key this handler listens to, e.g. `stripe`. */
-  source: string
-  /** Event-type pattern (supports wildcards: `*`, `payment_intent.*`). */
-  event: string
-  /** Unique handler id, e.g. `payments:stripe-payment-succeeded`. */
-  id: string
-  /** If true (default), handler runs via the queue-backed dispatcher. */
-  persistent?: boolean
-}
-
-/** Payload handed to a webhook handler. */
-export interface WebhookHandlerPayload {
-  /** Parsed webhook body. */
-  data: Record<string, unknown>
-  /** Extracted event type. */
-  eventType: string
-  /** Source key. */
-  sourceKey: string
-  /** Selected request headers. */
-  headers: Record<string, string>
-  /** WebhookIngestion record id. */
-  ingestionId: string
-  /** Tenant scope. */
-  tenantId: string
-  organizationId: string
-}
-
-/** DI accessor handed to a webhook handler. */
-export interface WebhookHandlerContext {
-  resolve: <T>(name: string) => T
-}
-
-/** A webhook handler function (default export of a `webhook-handlers/*.ts` file). */
-export type WebhookHandler = (
-  payload: WebhookHandlerPayload,
-  ctx: WebhookHandlerContext,
-) => Promise<void>
-
-/** A generated registry entry binding handler metadata to a lazy module loader. */
-export interface WebhookHandlerRegistryEntry {
-  meta: WebhookHandlerMeta
-  handler: () => Promise<{ default: WebhookHandler }>
-}
-
-/** Per-handler execution detail recorded on a WebhookIngestion. */
-export interface WebhookHandlerResult {
-  handlerId: string
-  module: string
-  status: 'success' | 'failed'
-  errorMessage?: string
-  durationMs: number
-  startedAt: string
-}
-
-/** Lifecycle status of an inbound webhook ingestion. */
-export type WebhookIngestionStatus =
-  | 'received'
-  | 'processing'
-  | 'processed'
-  | 'failed'
-  | 'duplicate'

package/src/modules/__tests__/nav-group-order-override.test.ts

@@ -1,183 +0,0 @@
-/** @jest-environment node */
-
-// `defaultGroupOrder` in `auth/lib/backendChrome.tsx` ranks any group it lists ahead of any group it
-// does not, regardless of an app's own page `priority`/`order` — so a downstream app could not place its
-// own primary module above the shipped groups by any documented means. `overrides.nav.groupOrder` wires
-// that as a real override domain, which `BACKWARD_COMPATIBILITY.md` §2 explicitly reserves for additive
-// wiring.
-
-const mockLoggerWarn = jest.fn()
-
-jest.mock('../../lib/logger', () => ({
-  createLogger: () => {
-    const child = { warn: (...args: unknown[]) => mockLoggerWarn(...args), error: jest.fn(), info: jest.fn(), debug: jest.fn() }
-    return { child: () => child, warn: child.warn, error: child.error, info: child.info, debug: child.debug }
-  },
-}))
-
-import {
-  applyModuleOverridesFromEnabledModules,
-  applyNavGroupOrderOverrides,
-  getNavGroupOrderOverride,
-  resetModuleContractOverridesForTests,
-  resetModuleOverrideAppliersForTests,
-} from '../overrides'
-
-function reset() {
-  resetModuleOverrideAppliersForTests()
-  resetModuleContractOverridesForTests()
-  mockLoggerWarn.mockClear()
-}
-
-beforeEach(reset)
-afterEach(reset)
-
-const collisionWarnings = () =>
-  mockLoggerWarn.mock.calls.filter((call) => String(call[0]).includes('nav.groupOrder declared by more than one'))
-
-describe('nav.groupOrder override domain', () => {
-  it('is unset when no module declares it', () => {
-    applyModuleOverridesFromEnabledModules([{ id: 'catalog' }, { id: 'sales', overrides: {} }])
-
-    expect(getNavGroupOrderOverride()).toBeNull()
-  })
-
-  it('captures the ids a module declares, in order — proving the domain is wired', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'app', overrides: { nav: { groupOrder: ['app.nav.group', 'catalog.nav.group'] } } },
-    ])
-
-    expect(getNavGroupOrderOverride()).toEqual(['app.nav.group', 'catalog.nav.group'])
-    // An unwired domain would be dropped with a "not yet wired" warning instead of being captured.
-    expect(mockLoggerWarn.mock.calls.filter((call) => String(call[0]).includes('not yet wired'))).toEqual([])
-  })
-
-  it('ignores an empty list, leaving the shipped ordering in charge', () => {
-    applyModuleOverridesFromEnabledModules([{ id: 'app', overrides: { nav: { groupOrder: [] } } }])
-
-    expect(getNavGroupOrderOverride()).toBeNull()
-  })
-
-  it('drops blank entries and de-duplicates while preserving first position', () => {
-    applyModuleOverridesFromEnabledModules([
-      {
-        id: 'app',
-        overrides: { nav: { groupOrder: ['  app.nav.group  ', '', '   ', 'app.nav.group', 'catalog.nav.group'] } },
-      },
-    ])
-
-    expect(getNavGroupOrderOverride()).toEqual(['app.nav.group', 'catalog.nav.group'])
-  })
-
-  it('ignores a non-array value rather than throwing', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'app', overrides: { nav: { groupOrder: 'app.nav.group' as never } } },
-    ])
-
-    expect(getNavGroupOrderOverride()).toBeNull()
-  })
-
-  it('lets the later module win when two declare an order, and says so', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'first', overrides: { nav: { groupOrder: ['first.nav.group'] } } },
-      { id: 'second', overrides: { nav: { groupOrder: ['second.nav.group'] } } },
-    ])
-
-    expect(getNavGroupOrderOverride()).toEqual(['second.nav.group'])
-    expect(collisionWarnings()).toHaveLength(1)
-  })
-
-  it('does not warn when the same module declares it twice', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'app', overrides: { nav: { groupOrder: ['a.nav.group'] } } },
-      { id: 'app', overrides: { nav: { groupOrder: ['b.nav.group'] } } },
-    ])
-
-    expect(getNavGroupOrderOverride()).toEqual(['b.nav.group'])
-    expect(collisionWarnings()).toEqual([])
-  })
-
-  it('is cleared by the store reset hook so suites cannot leak into each other', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'app', overrides: { nav: { groupOrder: ['app.nav.group'] } } },
-    ])
-    expect(getNavGroupOrderOverride()).not.toBeNull()
-
-    resetModuleContractOverridesForTests()
-
-    expect(getNavGroupOrderOverride()).toBeNull()
-  })
-})
-
-describe('nav.groupOrder programmatic tier', () => {
-  it('takes precedence over the modules.ts declaration', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'app', overrides: { nav: { groupOrder: ['from-modules.nav.group'] } } },
-    ])
-    applyNavGroupOrderOverrides(['from-code.nav.group'])
-
-    expect(getNavGroupOrderOverride()).toEqual(['from-code.nav.group'])
-  })
-
-  it('falls back to the modules.ts declaration when cleared with null', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'app', overrides: { nav: { groupOrder: ['from-modules.nav.group'] } } },
-    ])
-    applyNavGroupOrderOverrides(['from-code.nav.group'])
-    applyNavGroupOrderOverrides(null)
-
-    expect(getNavGroupOrderOverride()).toEqual(['from-modules.nav.group'])
-  })
-
-  it('applies the same normalisation as the modules.ts tier', () => {
-    applyNavGroupOrderOverrides(['  a.nav.group  ', '', 'a.nav.group', 'b.nav.group'])
-
-    expect(getNavGroupOrderOverride()).toEqual(['a.nav.group', 'b.nav.group'])
-  })
-
-  it('treats an all-blank list as no override', () => {
-    applyNavGroupOrderOverrides(['   ', ''])
-
-    expect(getNavGroupOrderOverride()).toBeNull()
-  })
-
-  it('works before any module override has been dispatched', () => {
-    applyNavGroupOrderOverrides(['standalone.nav.group'])
-
-    expect(getNavGroupOrderOverride()).toEqual(['standalone.nav.group'])
-  })
-})
-
-describe('nav.groupOrder survives module duplication', () => {
-  // Regression for `.ai/lessons.md`, "Global registries in publishable packages must use
-  // `globalThis`". This domain's writer (app bootstrap) and reader (`@open-mercato/core`'s backend
-  // chrome) sit in different packages, and standalone builds can evaluate `@open-mercato/shared`
-  // through more than one module instance. `jest.isolateModules` reproduces that: a second, freshly
-  // loaded copy of the module must still observe what the first copy stored.
-  it('a separately loaded module instance sees the value written by bootstrap', () => {
-    applyModuleOverridesFromEnabledModules([
-      { id: 'app', overrides: { nav: { groupOrder: ['bootstrap.nav.group'] } } },
-    ])
-
-    let observedFromSecondInstance: readonly string[] | null | undefined
-    jest.isolateModules(() => {
-      const freshModule = require('../overrides') as typeof import('../overrides')
-      observedFromSecondInstance = freshModule.getNavGroupOrderOverride()
-    })
-
-    // A module-local variable would leave this second instance blind to the bootstrap value.
-    expect(observedFromSecondInstance).toEqual(['bootstrap.nav.group'])
-  })
-
-  it('a programmatic override is visible to a separately loaded instance too', () => {
-    applyNavGroupOrderOverrides(['programmatic.nav.group'])
-
-    let observed: readonly string[] | null | undefined
-    jest.isolateModules(() => {
-      const freshModule = require('../overrides') as typeof import('../overrides')
-      observed = freshModule.getNavGroupOrderOverride()
-    })
-
-    expect(observed).toEqual(['programmatic.nav.group'])
-  })
-})

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

@@ -1,37 +0,0 @@
-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/widgets/__tests__/extension-points.test.ts

@@ -1,101 +0,0 @@
-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')
-  })
-})