@startsimpli/integrations 0.1.5 → 0.2.1

package/src/corpus/entities.ts

@@ -23,6 +23,8 @@
  * row with a missing subtitle.
  */
 import type {
+  Commitment,
+  CommitmentMention,
   CorpusScope,
   DocumentSection,
   MoneyEvent,
@@ -31,6 +33,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;
@@ -58,12 +96,15 @@ export interface CorpusTypeKeys {
   document: string;
   party: string;
   moneyEvent: string;
+  /** The trackable-commitment type (bd startsim-768w.38.25). */
+  commitment: string;
 }
 
 export const DEFAULT_TYPE_KEYS: CorpusTypeKeys = {
   document: 'source_document',
   party: 'party',
   moneyEvent: 'money_event',
+  commitment: 'commitment',
 };
 
 // ---------------------------------------------------------------------------
@@ -178,7 +219,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 +239,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 +380,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 +419,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 +443,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',
@@ -344,3 +498,132 @@ export function moneyEventAsDocument(event: MoneyEvent): SourceDocument {
     scope: event.scope,
   };
 }
+
+// ---------------------------------------------------------------------------
+//  Commitment (bd startsim-768w.38.25)
+// ---------------------------------------------------------------------------
+//
+// STORED IN THE SAME GENERIC ENVELOPE as everything else: `entity_type:
+// "commitment"`, discriminated by `data.subtype`. No new table, no new model, no
+// new app — a tenant that wants a sixth kind of trackable thing writes a
+// different subtype string (feedback_brutally_generic).
+//
+// `external_id` IS THE IDEMPOTENCY. It carries the dedupe key, and the tenant's
+// `/api/v1/entities/upsert/` is keyed on (entity_type, external_id), so two runs
+// racing each other converge on one row instead of writing two. Verified on the
+// live tandem tenant: a second upsert of the same external_id returns 200 and
+// updates in place.
+//
+// MENTIONS LIVE IN `data`, NOT AS EDGES, and that is a stated compromise rather
+// than an oversight. The canonical `derived_from` edge is declared
+// source_document -> source_document, a relationship row carries only
+// (rel_type, source, target), and a mention has to carry its own verbatim quote
+// or the row on screen cannot be checked against the record. Putting the quote
+// in `data` and the graph nowhere is the honest half; writing the edge as well
+// needs a schema change on the tenant side and is filed rather than half-done.
+
+/** How many mentions to keep on a row. A commitment discussed thirty times is
+ *  interesting; the thirty-first quote is not, and the row has to stay small. */
+const MAX_MENTIONS = 20;
+
+export function toCommitment(
+  entity: TenantEntity,
+  fallbackScope: CorpusScope,
+  sourceLabels: Record<string, string> = {},
+): Commitment {
+  const data = bag(entity);
+  const source = asText(pick(data, 'source', 'source_key', 'sourceKey')) || 'unknown';
+  const externalId = asText(entity.external_id ?? entity.externalId);
+  const mentions = asList(pick(data, 'mentions'))
+    .map(toMention)
+    .filter((mention): mention is CommitmentMention => mention !== null);
+  const status = asText(pick(data, 'status')) as Commitment['status'];
+
+  return {
+    id: String(entity.id),
+    externalId: externalId || `commit:${entity.id}`,
+    dedupeKey: asText(pick(data, 'dedupe_key', 'dedupeKey')) || externalId.replace(/^commit:/, ''),
+    subtype: asText(pick(data, 'subtype')) || 'action',
+    title: asText(pick(data, 'title')) || entity.name || 'Untitled item',
+    detail: asText(pick(data, 'detail', 'description')),
+    status: ['open', 'done', 'blocked', 'dropped'].includes(status) ? status : 'open',
+    ...(pick(data, 'status_reason', 'statusReason')
+      ? { statusReason: asText(pick(data, 'status_reason', 'statusReason')) } : {}),
+    ...(pick(data, 'resolved_by', 'resolvedBy')
+      ? { resolvedBy: asText(pick(data, 'resolved_by', 'resolvedBy')) } : {}),
+    resolvedAt: asIso(pick(data, 'resolved_at', 'resolvedAt')),
+    ...(pick(data, 'owner_name', 'ownerName') ? { ownerName: asText(pick(data, 'owner_name', 'ownerName')) } : {}),
+    ...(pick(data, 'subject') ? { subject: asText(pick(data, 'subject')) } : {}),
+    subjectKey: asText(pick(data, 'subject_key', 'subjectKey')),
+    actionKey: asText(pick(data, 'action_key', 'actionKey')),
+    dueAt: asIso(pick(data, 'due_at', 'dueAt')),
+    mentions,
+    firstSeenAt: asIso(pick(data, 'first_seen_at', 'firstSeenAt')),
+    lastSeenAt: asIso(pick(data, 'last_seen_at', 'lastSeenAt')),
+    extractorVersion: asText(pick(data, 'extractor_version', 'extractorVersion')),
+    source,
+    sourceLabel:
+      asText(pick(data, 'source_label', 'sourceLabel')) || sourceLabels[source] || titleCase(source),
+    scope: scopeOf(entity, fallbackScope),
+  };
+}
+
+function toMention(value: unknown): CommitmentMention | null {
+  if (!value || typeof value !== 'object') return null;
+  const data = value as Record<string, unknown>;
+  const documentId = asText(pick(data, 'document_id', 'documentId'));
+  if (!documentId) return null;
+  const extractor = asText(pick(data, 'extractor'));
+  return {
+    documentId,
+    originKey: asText(pick(data, 'origin_key', 'originKey')),
+    occurredAt: asIso(pick(data, 'occurred_at', 'occurredAt')),
+    quote: asText(pick(data, 'quote')),
+    extractor: extractor === 'model' ? 'model' : 'rules',
+  };
+}
+
+/** The write side: a commitment as the tenant's upsert payload. */
+export function commitmentToEntity(commitment: Commitment): {
+  entity_type: string;
+  external_id: string;
+  name: string;
+  data: Record<string, unknown>;
+} {
+  return {
+    entity_type: DEFAULT_TYPE_KEYS.commitment,
+    external_id: commitment.externalId,
+    name: commitment.title.slice(0, 200),
+    data: {
+      subtype: commitment.subtype,
+      title: commitment.title,
+      detail: commitment.detail,
+      status: commitment.status,
+      ...(commitment.statusReason ? { status_reason: commitment.statusReason } : {}),
+      ...(commitment.resolvedBy ? { resolved_by: commitment.resolvedBy } : {}),
+      ...(commitment.resolvedAt ? { resolved_at: commitment.resolvedAt } : {}),
+      ...(commitment.ownerName ? { owner_name: commitment.ownerName } : {}),
+      ...(commitment.subject ? { subject: commitment.subject } : {}),
+      subject_key: commitment.subjectKey,
+      action_key: commitment.actionKey,
+      dedupe_key: commitment.dedupeKey,
+      ...(commitment.dueAt ? { due_at: commitment.dueAt } : {}),
+      first_seen_at: commitment.firstSeenAt,
+      last_seen_at: commitment.lastSeenAt,
+      mention_count: commitment.mentions.length,
+      mentions: commitment.mentions.slice(-MAX_MENTIONS).map((mention) => ({
+        document_id: mention.documentId,
+        origin_key: mention.originKey,
+        occurred_at: mention.occurredAt,
+        quote: mention.quote.slice(0, 400),
+        extractor: mention.extractor,
+      })),
+      extractor_version: commitment.extractorVersion,
+      source: commitment.source,
+      // Marks the row as pipeline-written, the same way the corpus delivery
+      // marks its own — so a human-created item is distinguishable from a
+      // derived one, and a re-derivation knows what it is allowed to rewrite.
+      _origin: 'tenant-extraction',
+    },
+  };
+}