@open-mercato/core 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7001.1.03608ab252

package/src/modules/customers/components/detail/assignableStaff.ts

@@ -1,177 +1,14 @@
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
-import type { FilterOption } from '@open-mercato/shared/lib/query/advanced-filter'
-
-export type AssignableStaffMember = {
-  teamMemberId: string
-  userId: string
-  displayName: string
-  email: string | null
-  teamName: string | null
-}
-
-type AssignableStaffResponse = {
-  items?: Array<Record<string, unknown>>
-  total?: number
-  page?: number
-  pageSize?: number
-}
-
-export type AssignableStaffMembersPage = {
-  items: AssignableStaffMember[]
-  /**
-   * How many rows the server served for this page, before the dedupe below.
-   * "Load more" guards must measure this rather than `items.length`: a deduped
-   * length shorter than the served page reads as a short page and terminates
-   * the sequence early, stranding the rest of the roster.
-   */
-  servedCount: number
-  total: number
-  page: number
-  pageSize: number
-}
-
-// The assignable-staff roster is owned by the optional, ejectable `staff` module.
-// When that module is disabled, its `/api/staff/team-members/assignable` endpoint is
-// absent and the request resolves to 404. Customers UI (deals / people / companies
-// owner filters, role-assignment dialogs) is core and always enabled, so it must not
-// break in that case — a missing staff module simply means there is no roster to
-// offer. Treat the 404 as an empty page and let any other failure propagate.
-function isAssignableEndpointMissing(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    (error as { status?: unknown }).status === 404
-  )
-}
-
-export async function fetchAssignableStaffMembersPage(
-  query: string,
-  options?: { page?: number; pageSize?: number; signal?: AbortSignal },
-): Promise<AssignableStaffMembersPage> {
-  const page = options?.page ?? 1
-  const pageSize = options?.pageSize ?? 24
-  const params = new URLSearchParams()
-  params.set('page', String(page))
-  params.set('pageSize', String(pageSize))
-  const normalizedQuery = query.trim()
-  if (normalizedQuery.length > 0) {
-    params.set('search', normalizedQuery)
-  }
-
-  let data: AssignableStaffResponse
-  try {
-    data = await readApiResultOrThrow<AssignableStaffResponse>(
-      `/api/staff/team-members/assignable?${params.toString()}`,
-      options?.signal ? { signal: options.signal } : undefined,
-    )
-  } catch (error) {
-    if (isAssignableEndpointMissing(error)) {
-      return { items: [], servedCount: 0, total: 0, page, pageSize }
-    }
-    throw error
-  }
-
-  const rawItems = Array.isArray(data?.items) ? data.items : []
-  const deduped = new Map<string, AssignableStaffMember>()
-
-  for (const item of rawItems) {
-    const userId =
-      typeof item?.userId === 'string'
-        ? item.userId
-        : typeof item?.user_id === 'string'
-          ? item.user_id
-          : null
-    if (!userId || deduped.has(userId)) continue
-
-    const user =
-      item?.user && typeof item.user === 'object'
-        ? (item.user as Record<string, unknown>)
-        : null
-    const team =
-      item?.team && typeof item.team === 'object'
-        ? (item.team as Record<string, unknown>)
-        : null
-
-    const displayName =
-      typeof item?.displayName === 'string' && item.displayName.trim().length > 0
-        ? item.displayName.trim()
-        : typeof item?.display_name === 'string' && item.display_name.trim().length > 0
-          ? item.display_name.trim()
-          : null
-    const email =
-      user && typeof user.email === 'string' && user.email.trim().length > 0
-        ? user.email.trim()
-        : typeof item?.email === 'string' && item.email.trim().length > 0
-          ? item.email.trim()
-          : null
-    const teamName =
-      typeof item?.teamName === 'string' && item.teamName.trim().length > 0
-        ? item.teamName.trim()
-        : typeof item?.team_name === 'string' && item.team_name.trim().length > 0
-          ? item.team_name.trim()
-          : team && typeof team.name === 'string' && team.name.trim().length > 0
-            ? team.name.trim()
-            : null
-    const teamMemberId =
-      typeof item?.teamMemberId === 'string'
-        ? item.teamMemberId
-        : typeof item?.team_member_id === 'string'
-          ? item.team_member_id
-          : typeof item?.id === 'string'
-            ? item.id
-            : userId
-
-    deduped.set(userId, {
-      teamMemberId,
-      userId,
-      displayName: displayName ?? email ?? userId,
-      email,
-      teamName,
-    })
-  }
-
-  return {
-    items: Array.from(deduped.values()),
-    servedCount: rawItems.length,
-    total:
-      typeof data?.total === 'number' && Number.isFinite(data.total)
-        ? data.total
-        : deduped.size,
-    page:
-      typeof data?.page === 'number' && Number.isFinite(data.page)
-        ? data.page
-        : page,
-    pageSize:
-      typeof data?.pageSize === 'number' && Number.isFinite(data.pageSize)
-        ? data.pageSize
-        : pageSize,
-  }
-}
-
-export async function fetchAssignableStaffMembers(
-  query: string,
-  options?: { pageSize?: number; signal?: AbortSignal },
-): Promise<AssignableStaffMember[]> {
-  const result = await fetchAssignableStaffMembersPage(query, options)
-  return result.items
-}
-
-export function mapAssignableStaffToFilterOptions(items: AssignableStaffMember[]): FilterOption[] {
-  return items.map((item) => ({
-    value: item.userId,
-    label: item.email && item.email !== item.displayName
-      ? `${item.displayName} (${item.email})`
-      : item.displayName,
-    tone: 'neutral',
-  }))
-}
-
-export function ensureCurrentUserFilterOption(
-  options: FilterOption[],
-  currentUserId: string,
-  fallbackLabel: string,
-): FilterOption[] {
-  const trimmed = currentUserId.trim()
-  if (!trimmed || options.some((option) => option.value === trimmed)) return options
-  return [{ value: trimmed, label: fallbackLabel, tone: 'neutral' }, ...options]
-}
+/**
+ * @deprecated Import from `@open-mercato/core/modules/customers/lib/assignableStaff` instead.
+ * This path is a compatibility bridge kept for one minor version after 0.6.7; it will be
+ * removed in 0.7.0. The implementation moved to `../../lib/assignableStaff` so non-component
+ * callers (API routes, commands) can use it without importing from a `components/` path.
+ */
+export {
+  fetchAssignableStaffMembersPage,
+  fetchAssignableStaffMembers,
+  mapAssignableStaffToFilterOptions,
+  ensureCurrentUserFilterOption,
+  type AssignableStaffMember,
+  type AssignableStaffMembersPage,
+} from '../../lib/assignableStaff'

package/src/modules/customers/lib/assignableStaff.ts

@@ -0,0 +1,177 @@
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import type { FilterOption } from '@open-mercato/shared/lib/query/advanced-filter'
+
+export type AssignableStaffMember = {
+  teamMemberId: string
+  userId: string
+  displayName: string
+  email: string | null
+  teamName: string | null
+}
+
+type AssignableStaffResponse = {
+  items?: Array<Record<string, unknown>>
+  total?: number
+  page?: number
+  pageSize?: number
+}
+
+export type AssignableStaffMembersPage = {
+  items: AssignableStaffMember[]
+  /**
+   * How many rows the server served for this page, before the dedupe below.
+   * "Load more" guards must measure this rather than `items.length`: a deduped
+   * length shorter than the served page reads as a short page and terminates
+   * the sequence early, stranding the rest of the roster.
+   */
+  servedCount: number
+  total: number
+  page: number
+  pageSize: number
+}
+
+// The assignable-staff roster is owned by the optional, ejectable `staff` module.
+// When that module is disabled, its `/api/staff/team-members/assignable` endpoint is
+// absent and the request resolves to 404. Customers UI (deals / people / companies
+// owner filters, role-assignment dialogs) is core and always enabled, so it must not
+// break in that case — a missing staff module simply means there is no roster to
+// offer. Treat the 404 as an empty page and let any other failure propagate.
+function isAssignableEndpointMissing(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { status?: unknown }).status === 404
+  )
+}
+
+export async function fetchAssignableStaffMembersPage(
+  query: string,
+  options?: { page?: number; pageSize?: number; signal?: AbortSignal },
+): Promise<AssignableStaffMembersPage> {
+  const page = options?.page ?? 1
+  const pageSize = options?.pageSize ?? 24
+  const params = new URLSearchParams()
+  params.set('page', String(page))
+  params.set('pageSize', String(pageSize))
+  const normalizedQuery = query.trim()
+  if (normalizedQuery.length > 0) {
+    params.set('search', normalizedQuery)
+  }
+
+  let data: AssignableStaffResponse
+  try {
+    data = await readApiResultOrThrow<AssignableStaffResponse>(
+      `/api/staff/team-members/assignable?${params.toString()}`,
+      options?.signal ? { signal: options.signal } : undefined,
+    )
+  } catch (error) {
+    if (isAssignableEndpointMissing(error)) {
+      return { items: [], servedCount: 0, total: 0, page, pageSize }
+    }
+    throw error
+  }
+
+  const rawItems = Array.isArray(data?.items) ? data.items : []
+  const deduped = new Map<string, AssignableStaffMember>()
+
+  for (const item of rawItems) {
+    const userId =
+      typeof item?.userId === 'string'
+        ? item.userId
+        : typeof item?.user_id === 'string'
+          ? item.user_id
+          : null
+    if (!userId || deduped.has(userId)) continue
+
+    const user =
+      item?.user && typeof item.user === 'object'
+        ? (item.user as Record<string, unknown>)
+        : null
+    const team =
+      item?.team && typeof item.team === 'object'
+        ? (item.team as Record<string, unknown>)
+        : null
+
+    const displayName =
+      typeof item?.displayName === 'string' && item.displayName.trim().length > 0
+        ? item.displayName.trim()
+        : typeof item?.display_name === 'string' && item.display_name.trim().length > 0
+          ? item.display_name.trim()
+          : null
+    const email =
+      user && typeof user.email === 'string' && user.email.trim().length > 0
+        ? user.email.trim()
+        : typeof item?.email === 'string' && item.email.trim().length > 0
+          ? item.email.trim()
+          : null
+    const teamName =
+      typeof item?.teamName === 'string' && item.teamName.trim().length > 0
+        ? item.teamName.trim()
+        : typeof item?.team_name === 'string' && item.team_name.trim().length > 0
+          ? item.team_name.trim()
+          : team && typeof team.name === 'string' && team.name.trim().length > 0
+            ? team.name.trim()
+            : null
+    const teamMemberId =
+      typeof item?.teamMemberId === 'string'
+        ? item.teamMemberId
+        : typeof item?.team_member_id === 'string'
+          ? item.team_member_id
+          : typeof item?.id === 'string'
+            ? item.id
+            : userId
+
+    deduped.set(userId, {
+      teamMemberId,
+      userId,
+      displayName: displayName ?? email ?? userId,
+      email,
+      teamName,
+    })
+  }
+
+  return {
+    items: Array.from(deduped.values()),
+    servedCount: rawItems.length,
+    total:
+      typeof data?.total === 'number' && Number.isFinite(data.total)
+        ? data.total
+        : deduped.size,
+    page:
+      typeof data?.page === 'number' && Number.isFinite(data.page)
+        ? data.page
+        : page,
+    pageSize:
+      typeof data?.pageSize === 'number' && Number.isFinite(data.pageSize)
+        ? data.pageSize
+        : pageSize,
+  }
+}
+
+export async function fetchAssignableStaffMembers(
+  query: string,
+  options?: { pageSize?: number; signal?: AbortSignal },
+): Promise<AssignableStaffMember[]> {
+  const result = await fetchAssignableStaffMembersPage(query, options)
+  return result.items
+}
+
+export function mapAssignableStaffToFilterOptions(items: AssignableStaffMember[]): FilterOption[] {
+  return items.map((item) => ({
+    value: item.userId,
+    label: item.email && item.email !== item.displayName
+      ? `${item.displayName} (${item.email})`
+      : item.displayName,
+    tone: 'neutral',
+  }))
+}
+
+export function ensureCurrentUserFilterOption(
+  options: FilterOption[],
+  currentUserId: string,
+  fallbackLabel: string,
+): FilterOption[] {
+  const trimmed = currentUserId.trim()
+  if (!trimmed || options.some((option) => option.value === trimmed)) return options
+  return [{ value: trimmed, label: fallbackLabel, tone: 'neutral' }, ...options]
+}

package/src/modules/data_sync/AGENTS.md

@@ -54,6 +54,7 @@ packages/core/src/modules/data_sync/
 │   ├── adapter-registry.ts      # Register/get adapters by providerKey
 │   ├── id-mapping.ts            # External ID ↔ local ID lookup and storage
 │   ├── queue.ts                 # Queue helper for enqueuing sync jobs
+│   ├── batch-stream.ts          # Drives adapter streams; one root span per batch
 │   ├── run-parameters.ts        # Validate/coerce operator run parameters vs. adapter declaration
 │   ├── sync-engine.ts           # Orchestrates streaming import/export with progress
 │   └── sync-run-service.ts      # CRUD for SyncRun + cursor management
@@ -206,6 +207,8 @@ If the sync provider needs bootstrap credentials, mappings, locales, channels, o
 - **Resume**: Retry reads the last successful cursor, resumes from there
 - **Progress**: Linked to `ProgressJob` via `progressJobId` for `ProgressTopBar` display
 - **Cancellation**: Via `progressService.isCancellationRequested()`
+- **Tracing**: The engine emits one **root** span per batch (`data_sync.import.batch` / `data_sync.export.batch`) linked back to the run, covering the adapter's read *and* the engine's bookkeeping. Adapters MUST NOT hand-roll their own batch span — they cannot root it, so a multi-day run would ride on the single sampling decision taken for the request that triggered it. Inner spans an adapter creates nest under the batch span normally. The final read — the one that finds the stream drained — is traced as `data_sync.import.drain` / `data_sync.export.drain`, so N batches emit exactly N `*.batch` spans plus one `*.drain`.
+- **Stream shape**: The engine drives the adapter's async iterator explicitly (`batch-stream.ts`) so the span wraps `next()`, where a generator does its real work before yielding. Closing follows the language's own `IteratorClose` rules, so `finally` blocks in an adapter generator behave exactly as under `for await`: no `return()` when the stream exhausts or `next()` throws (already closed), `return()` with its failure surfaced on an early stop, and `return()` with its failure swallowed when the engine's own handler threw (that error wins). Keep cleanup in `finally`.
 
 ## Queue Names
 

package/src/modules/data_sync/lib/batch-stream.ts

@@ -0,0 +1,117 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  withTelemetrySpan,
+  type TelemetrySpan,
+  type TelemetrySpanAttributes,
+  type TelemetryTraceCarrier,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+
+const logger = createLogger('data_sync').child({ component: 'batch-stream' })
+
+/** What the handler wants the stream to do next. */
+export type BatchOutcome = 'continue' | 'stop'
+
+/** Why the stream ended: the adapter ran out of batches, or a handler stopped it. */
+export type BatchStreamResult = 'completed' | 'stopped'
+
+export type BatchStreamOptions = {
+  spanName: string
+  /**
+   * Name for the read that turns out to have drained the stream. That read is
+   * real adapter work — it can be a full remote page fetch that comes back
+   * empty — so it stays traced, but it is not a batch: leaving it under
+   * `spanName` would report one batch more than the run actually processed and
+   * feed an unlabelled, counter-less sample into every batch latency panel.
+   */
+  drainSpanName: string
+  /** Run-level attributes repeated on every batch span (run id, entity type, scope). */
+  attributes?: TelemetrySpanAttributes
+  /** The run's trace, so a rooted batch still points back at what triggered it. */
+  linkTo?: TelemetryTraceCarrier
+}
+
+/**
+ * Close the stream while an error is already in flight. That error is the one
+ * worth propagating, so a secondary cleanup failure is logged rather than
+ * allowed to mask it — which is what `for await` does on a body throw.
+ */
+async function closeQuietly(iterator: AsyncIterator<unknown>): Promise<void> {
+  if (!iterator.return) return
+  try {
+    await iterator.return()
+  } catch (error) {
+    logger.warn('Data sync adapter stream did not close cleanly', { err: error })
+  }
+}
+
+/**
+ * Drive `stream` one batch at a time, running the adapter's read AND `handle`'s
+ * bookkeeping for that batch inside a single ROOT span linked back to the run.
+ *
+ * Rooting per batch is the whole point. A sync run can last days, so leaving its
+ * spans nested under the request that triggered it puts the entire run behind
+ * one sampling decision — below ratio 1.0 a run can emit nothing at all, and at
+ * 1.0 it becomes a single unrenderable trace. A batch is the unit the slowness
+ * analysis actually reasons about, so it gets its own trace and its own
+ * decision.
+ *
+ * The iterator is driven explicitly instead of with `for await` so the span can
+ * wrap `next()`, which is where an adapter generator does its real work — it
+ * reads, transforms and upserts before it ever yields. A stream is only known to
+ * be drained once that read returns `done`, so the last span per run starts
+ * under `spanName` and is renamed to `drainSpanName`: a run over N batches emits
+ * N spans named `spanName` and exactly one named `drainSpanName`.
+ *
+ * Closing follows the language's own `IteratorClose` rules exactly, so adapter
+ * cleanup behaves as it did under `for await`:
+ *
+ * - **exhausted** — the iterator already completed itself; no `return()` call.
+ * - **stopped early** — `return()` is called and a failure to close *is* the
+ *   result, the same as breaking out of `for await`.
+ * - **`handle` threw** — `return()` is called, but its failure is swallowed so
+ *   the handler's error still wins.
+ * - **`next()` threw** — the iterator is already closed; no `return()` call.
+ */
+export async function forEachBatch<TBatch>(
+  stream: AsyncIterable<TBatch>,
+  options: BatchStreamOptions,
+  handle: (batch: TBatch, span: TelemetrySpan) => Promise<BatchOutcome>,
+): Promise<BatchStreamResult> {
+  const iterator = stream[Symbol.asyncIterator]()
+  for (;;) {
+    let readThrew = false
+    let outcome: BatchOutcome | 'exhausted'
+    try {
+      outcome = await withTelemetrySpan(
+        options.spanName,
+        async (span): Promise<BatchOutcome | 'exhausted'> => {
+          let next: IteratorResult<TBatch>
+          try {
+            next = await iterator.next()
+          } catch (error) {
+            readThrew = true
+            throw error
+          }
+          if (next.done) {
+            span.updateName?.(options.drainSpanName)
+            return 'exhausted'
+          }
+          return handle(next.value, span)
+        },
+        {
+          root: true,
+          attributes: options.attributes,
+          links: options.linkTo ? [options.linkTo] : undefined,
+        },
+      )
+    } catch (error) {
+      if (!readThrew) await closeQuietly(iterator)
+      throw error
+    }
+    if (outcome === 'exhausted') return 'completed'
+    if (outcome === 'stop') {
+      await iterator.return?.()
+      return 'stopped'
+    }
+  }
+}