@startsimpli/integrations 0.1.5 → 0.1.6

package/src/corpus/entities.ts

@@ -31,6 +31,42 @@ import type {
   SourceDocument,
 } from './types';
 
+/**
+ * The tenant data plane's typed EDGE, as `/api/v1/relationships/` returns it.
+ *
+ * People are stored as edges, not as an inline array. The corpus delivery
+ * (bd startsim-768w.38.18) writes `source_document --involves--> party` and
+ * `source_document --authored_by--> party`; the document's own `data` carries
+ * only a `participant_count`. A reader that only looks at `data` sees a corpus
+ * in which nobody was ever in the room (bd startsim-768w.38.22).
+ */
+export interface TenantRelationship {
+  id?: string | number;
+  rel_type?: string;
+  relType?: string;
+  /** The record the edge starts at — the document, or the money event. */
+  source: string | number;
+  /** The record the edge points at — the party. */
+  target: string | number;
+  created_at?: string | null;
+  createdAt?: string | null;
+}
+
+/**
+ * Edges that mean "this party is ON this record", in the order they should be
+ * listed. DATA, not a closed set: a tenant that models its own edge passes its
+ * own list rather than editing this file.
+ *
+ * `authored_by` first because the author is who a reader looks for first;
+ * `billed_to` is here because a money event's party is the same question asked
+ * of a payment.
+ */
+export const DEFAULT_PARTICIPANT_EDGES: readonly string[] = [
+  'authored_by',
+  'involves',
+  'billed_to',
+];
+
 /** The tenant data plane's generic record envelope, as the API returns it. */
 export interface TenantEntity {
   id: string | number;
@@ -178,7 +214,13 @@ export function toParty(entity: TenantEntity, fallbackScope: CorpusScope): Party
   const email = asText(pick(data, 'email', 'primary_email', 'primaryEmail')) || emails[0] || '';
   return {
     id: String(entity.id),
-    name: asText(pick(data, 'name', 'label', 'full_name', 'fullName')) || entity.name || String(entity.id),
+    // `display_name` is what the canonical party schema declares
+    // (startsimpli_connectors.canonical), so it is read FIRST among the
+    // spellings — a connector-written row has no `name` key inside `data`.
+    name:
+      asText(pick(data, 'display_name', 'displayName', 'name', 'label', 'full_name', 'fullName')) ||
+      entity.name ||
+      String(entity.id),
     kind: asText(pick(data, 'kind', 'subtype', 'party_type', 'partyType')) || undefined,
     ...(email ? { email } : {}),
     ...(emails.length ? { emails } : {}),
@@ -192,6 +234,95 @@ export function toParty(entity: TenantEntity, fallbackScope: CorpusScope): Party
   };
 }
 
+/**
+ * Stable identity for de-duplication. A party that arrives once as an edge and
+ * once inline is ONE person, and listing them twice is the kind of small wrong
+ * that makes the whole panel look untrustworthy.
+ */
+function partyKey(party: PartyRef): string {
+  return (party.id || party.email || party.name || '').toLowerCase();
+}
+
+/**
+ * Union two participant lists, keeping the first spelling of each person.
+ *
+ * INLINE WINS over the edge-derived copy, because a connector that wrote the
+ * participant onto the record itself knew something about the role it played
+ * there. Order is preserved so `authored_by` stays in front.
+ */
+export function mergeParticipants(...lists: Array<PartyRef[] | undefined>): PartyRef[] {
+  const out: PartyRef[] = [];
+  const seen = new Set<string>();
+  for (const list of lists) {
+    for (const party of list ?? []) {
+      const key = partyKey(party);
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      out.push(party);
+    }
+  }
+  return out;
+}
+
+/**
+ * The graph, read as "who is on which record".
+ *
+ * THIS IS THE JOIN THE PRODUCT ACTUALLY NEEDS, and the reason it lives here
+ * rather than in a composer: the tenant stores people as typed edges, and every
+ * surface — the Library's Parties block, the row subtitle, the retrieval field
+ * weights, the prompt — asks the same question of them. Doing the join once,
+ * next to the mapper that already knows the storage shape, keeps `entities.ts`
+ * the single file that knows how a corpus record is stored.
+ *
+ * Nothing here names a vendor and nothing here assumes an edge direction beyond
+ * the declared one (`source` is the record, `target` is the party), which is the
+ * contract `canonical_schema()` states for all four canonical edges.
+ */
+export function indexParticipants(
+  relationships: TenantRelationship[],
+  parties: Iterable<PartyRef>,
+  edgeTypes: readonly string[] = DEFAULT_PARTICIPANT_EDGES,
+): Map<string, PartyRef[]> {
+  const byId = new Map<string, PartyRef>();
+  for (const party of parties) {
+    if (!party?.id) continue;
+    // NARROWED to a reference. A `Party` carries its own source and scope, and a
+    // document's participant list is a list of references — copying the whole
+    // record onto every document that mentions it is a second copy of the row.
+    byId.set(String(party.id), {
+      id: String(party.id),
+      name: party.name || String(party.id),
+      ...(party.kind ? { kind: party.kind } : {}),
+      ...(party.email ? { email: party.email } : {}),
+    });
+  }
+
+  // Rank by the DECLARED order of `edgeTypes` rather than by arrival order, so
+  // the author is listed first however the API happened to page the edges.
+  const rank = new Map(edgeTypes.map((type, index) => [type, index]));
+  const buckets = new Map<string, Array<{ order: number; party: PartyRef }>>();
+
+  for (const edge of relationships ?? []) {
+    if (!edge) continue;
+    const relType = asText(edge.rel_type ?? edge.relType);
+    const order = rank.get(relType);
+    if (order === undefined) continue; // `derived_from` and anything else: not a person
+    const recordId = asText(edge.source);
+    const party = byId.get(asText(edge.target));
+    if (!recordId || !party) continue; // an edge whose far end we cannot name adds nothing
+    const bucket = buckets.get(recordId);
+    if (bucket) bucket.push({ order, party });
+    else buckets.set(recordId, [{ order, party }]);
+  }
+
+  const out = new Map<string, PartyRef[]>();
+  for (const [recordId, entries] of buckets) {
+    entries.sort((a, b) => a.order - b.order);
+    out.set(recordId, mergeParticipants(entries.map((entry) => entry.party)));
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 //  SourceDocument
 // ---------------------------------------------------------------------------
@@ -244,6 +375,13 @@ export function toSourceDocument(
   entity: TenantEntity,
   fallbackScope: CorpusScope,
   sourceLabels: Record<string, string> = {},
+  /**
+   * People resolved from the tenant's `authored_by` / `involves` EDGES — which
+   * is where the connector pipeline actually puts them (bd startsim-768w.38.18).
+   * Passed in rather than fetched here because this module is pure; the client
+   * adapter owns the round trip. See `indexParticipants`.
+   */
+  edgeParticipants: PartyRef[] = [],
 ): SourceDocument {
   const data = bag(entity);
   const source = asText(pick(data, 'source', 'source_key', 'sourceKey')) || 'unknown';
@@ -276,9 +414,17 @@ export function toSourceDocument(
       asText(pick(data, 'source_ref', 'sourceRef')) ||
       asText(entity.external_id ?? entity.externalId),
     url: asText(pick(data, 'url', 'web_url', 'webUrl', 'link')) || undefined,
-    participants: asList(pick(data, 'participants', 'attendees', 'parties'))
-      .map(toPartyRef)
-      .filter((ref): ref is PartyRef => ref !== null),
+    // BOTH STORAGE SHAPES, because both are real. A connector that denormalizes
+    // its attendees onto the record writes an inline array; the shipped corpus
+    // delivery writes typed edges and a bare `participant_count`. Reading only
+    // the first is what made `participants` empty on every document the pipeline
+    // has ever delivered (bd startsim-768w.38.22).
+    participants: mergeParticipants(
+      asList(pick(data, 'participants', 'attendees', 'parties'))
+        .map(toPartyRef)
+        .filter((ref): ref is PartyRef => ref !== null),
+      edgeParticipants,
+    ),
     scope: scopeOf(entity, fallbackScope),
     ingestedAt: asIso(entity.created_at ?? entity.createdAt),
   };
@@ -292,10 +438,13 @@ export function toMoneyEvent(
   entity: TenantEntity,
   fallbackScope: CorpusScope,
   sourceLabels: Record<string, string> = {},
+  /** Resolved from the `billed_to` edge — the money side of the same seam. */
+  edgeParticipants: PartyRef[] = [],
 ): MoneyEvent {
   const data = bag(entity);
   const source = asText(pick(data, 'source', 'source_key', 'sourceKey')) || 'unknown';
-  const party = toPartyRef(pick(data, 'party', 'customer', 'counterparty'));
+  const party =
+    toPartyRef(pick(data, 'party', 'customer', 'counterparty')) ?? edgeParticipants[0] ?? null;
   return {
     id: String(entity.id),
     subtype: asText(pick(data, 'subtype', 'kind', 'event_type', 'eventType')) || 'charge',