@startsimpli/integrations 0.1.4 → 0.1.5

package/src/corpus/entities.ts

@@ -0,0 +1,346 @@
+/**
+ * The ONE file that knows how a corpus record is STORED.
+ *
+ * bd startsim-768w.38.2 is still open and its attribute names are expected to
+ * shift. Everything else in this package — retrieval, the ask pipeline, both
+ * composers, every test — speaks `SourceDocument`/`Party`/`MoneyEvent` and never
+ * touches an `Entity`. So a schema tweak is an edit here and nowhere else.
+ *
+ * THE STORAGE SHAPE it maps from is the tenant data plane's generic envelope
+ * (tenant-starter `apps/core/models.Entity`):
+ *
+ *   { id, entity_type, external_id, name, data: {...}, created_at }
+ *
+ * `entity_type` is a free-form string and `data` is a JSON blob of the
+ * attributes the tenant declared through the schema API. That genericness is the
+ * whole point — a future Drive connector fills `source_document` with
+ * `source: "gdrive"` and no type, no mapper and no screen changes.
+ *
+ * TOLERANT ON READ. Every accessor below accepts more than one spelling of a
+ * field and falls back rather than throwing. A record written by a connector
+ * that is one deploy ahead of this bundle must still render; a corpus that
+ * blanks itself because an attribute was renamed is worse than one that shows a
+ * row with a missing subtitle.
+ */
+import type {
+  CorpusScope,
+  DocumentSection,
+  MoneyEvent,
+  Party,
+  PartyRef,
+  SourceDocument,
+} from './types';
+
+/** The tenant data plane's generic record envelope, as the API returns it. */
+export interface TenantEntity {
+  id: string | number;
+  entity_type?: string;
+  entityType?: string;
+  external_id?: string | null;
+  externalId?: string | null;
+  name?: string;
+  data?: Record<string, unknown> | null;
+  created_at?: string | null;
+  createdAt?: string | null;
+  /** Present when the API echoes the tenant boundary back. */
+  org_id?: string;
+  orgId?: string;
+  owner_sub?: string;
+  ownerSub?: string;
+}
+
+/**
+ * The entity_type keys the corpus expects. Defaults, not a closed set: a tenant
+ * that modeled its types under different keys passes its own via
+ * `CorpusTypeKeys` rather than editing this file.
+ */
+export interface CorpusTypeKeys {
+  document: string;
+  party: string;
+  moneyEvent: string;
+}
+
+export const DEFAULT_TYPE_KEYS: CorpusTypeKeys = {
+  document: 'source_document',
+  party: 'party',
+  moneyEvent: 'money_event',
+};
+
+// ---------------------------------------------------------------------------
+//  tolerant accessors
+// ---------------------------------------------------------------------------
+
+function bag(entity: TenantEntity): Record<string, unknown> {
+  const data = entity.data;
+  return data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
+}
+
+/**
+ * First present value across candidate keys. The `@startsimpli/api` client
+ * snake_case↔camelCase transform recurses into `data`, so both spellings can
+ * legitimately arrive depending on which client fetched the row.
+ */
+function pick(data: Record<string, unknown>, ...keys: string[]): unknown {
+  for (const key of keys) {
+    const value = data[key];
+    if (value !== undefined && value !== null && value !== '') return value;
+  }
+  return undefined;
+}
+
+function asText(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return '';
+}
+
+function asIso(value: unknown): string | null {
+  const text = asText(value);
+  if (!text) return null;
+  const parsed = Date.parse(text);
+  return Number.isNaN(parsed) ? null : new Date(parsed).toISOString();
+}
+
+function asList(value: unknown): unknown[] {
+  if (Array.isArray(value)) return value;
+  if (value === undefined || value === null || value === '') return [];
+  return [value];
+}
+
+/**
+ * Money arrives in minor units from every payment vendor that matters, but a
+ * hand-entered record may carry a decimal. A `1200` that means £12.00 rendered
+ * as £1,200.00 is the kind of wrong that survives a demo, so the rule is stated
+ * once, here: an integer is minor units, a non-integer is major units.
+ */
+function asMinorUnits(value: unknown): number {
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? value : Math.round(value * 100);
+  }
+  const text = asText(value);
+  if (!text) return 0;
+  const parsed = Number(text);
+  if (Number.isNaN(parsed)) return 0;
+  return Number.isInteger(parsed) ? parsed : Math.round(parsed * 100);
+}
+
+/**
+ * The scope carried BY the row. When the API does not echo it (older builds
+ * did not), fall back to the scope the caller is already in — the guard in
+ * `./retrieval` still runs, it just cannot catch a server that lied.
+ */
+export function scopeOf(entity: TenantEntity, fallback: CorpusScope): CorpusScope {
+  const data = bag(entity);
+  const orgId =
+    asText(entity.org_id ?? entity.orgId) ||
+    asText(pick(data, 'org_id', 'orgId')) ||
+    fallback.orgId;
+  const ownerSub =
+    asText(entity.owner_sub ?? entity.ownerSub) ||
+    asText(pick(data, 'owner_sub', 'ownerSub')) ||
+    fallback.ownerSub ||
+    '';
+  return ownerSub ? { orgId, ownerSub } : { orgId };
+}
+
+// ---------------------------------------------------------------------------
+//  Party
+// ---------------------------------------------------------------------------
+
+/**
+ * A participant as it is EMBEDDED on a document. Accepts a bare string (an
+ * email, a name), an object with an id, or an object with only a name — because
+ * a connector that has not resolved a Party yet still knows who was there, and
+ * dropping the name until a join exists loses the thing the user recognises.
+ */
+export function toPartyRef(value: unknown): PartyRef | null {
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (!text) return null;
+    const isEmail = text.includes('@');
+    return { id: text, name: text, ...(isEmail ? { email: text } : {}) };
+  }
+  if (!value || typeof value !== 'object') return null;
+  const data = value as Record<string, unknown>;
+  const email = asText(pick(data, 'email', 'email_address', 'emailAddress'));
+  const name = asText(pick(data, 'name', 'label', 'full_name', 'fullName', 'title')) || email;
+  const id = asText(pick(data, 'id', 'party_id', 'partyId', 'external_id', 'externalId')) || email || name;
+  if (!id) return null;
+  const kind = asText(pick(data, 'kind', 'subtype', 'party_type', 'partyType'));
+  return { id, name: name || id, ...(kind ? { kind } : {}), ...(email ? { email } : {}) };
+}
+
+export function toParty(entity: TenantEntity, fallbackScope: CorpusScope): Party {
+  const data = bag(entity);
+  const emails = asList(pick(data, 'emails', 'email_addresses', 'emailAddresses'))
+    .map(asText)
+    .filter(Boolean);
+  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),
+    kind: asText(pick(data, 'kind', 'subtype', 'party_type', 'partyType')) || undefined,
+    ...(email ? { email } : {}),
+    ...(emails.length ? { emails } : {}),
+    source: asText(pick(data, 'source', 'source_key', 'sourceKey')) || 'unknown',
+    sourceLabel: asText(pick(data, 'source_label', 'sourceLabel')) || undefined,
+    sourceRef:
+      asText(pick(data, 'source_ref', 'sourceRef')) ||
+      asText(entity.external_id ?? entity.externalId) ||
+      undefined,
+    scope: scopeOf(entity, fallbackScope),
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  SourceDocument
+// ---------------------------------------------------------------------------
+
+/**
+ * Long-form text a source attached to a document.
+ *
+ * Accepts three storage shapes, because the connectors do not agree and should
+ * not have to: an array of `{key,label,text}`, an object of `{key: text}`, or
+ * the legacy single-blob attributes some early ingests wrote. Nothing here names
+ * a vendor — `transcript` is just a key a source may have used, exactly like
+ * `extracted_text`, and its LABEL comes from the data or from a title-cased key.
+ */
+export function toSections(value: unknown): DocumentSection[] {
+  const sections: DocumentSection[] = [];
+  const push = (key: string, label: string, text: unknown) => {
+    const body = asText(text).trim();
+    if (body) sections.push({ key, label, text: body });
+  };
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === 'string') {
+        push('section', 'Section', item);
+        continue;
+      }
+      if (!item || typeof item !== 'object') continue;
+      const data = item as Record<string, unknown>;
+      const key = asText(pick(data, 'key', 'name', 'kind')) || 'section';
+      const label = asText(pick(data, 'label', 'title')) || titleCase(key);
+      push(key, label, pick(data, 'text', 'body', 'value', 'content'));
+    }
+    return sections;
+  }
+
+  if (value && typeof value === 'object') {
+    for (const [key, text] of Object.entries(value as Record<string, unknown>)) {
+      push(key, titleCase(key), text);
+    }
+  }
+  return sections;
+}
+
+function titleCase(key: string): string {
+  const words = key.replace(/[_-]+/g, ' ').trim();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : key;
+}
+
+export function toSourceDocument(
+  entity: TenantEntity,
+  fallbackScope: CorpusScope,
+  sourceLabels: Record<string, string> = {},
+): SourceDocument {
+  const data = bag(entity);
+  const source = asText(pick(data, 'source', 'source_key', 'sourceKey')) || 'unknown';
+
+  const sections = toSections(pick(data, 'sections'));
+  // A source that stored its long-form under a bare attribute rather than in
+  // `sections` still contributes one. Listed keys are storage spellings, not
+  // vendor knowledge: the same loop picks up a Drive connector's `extracted_text`.
+  for (const key of ['transcript', 'extracted_text', 'extractedText', 'full_text', 'fullText']) {
+    if (sections.some((section) => section.key === key)) continue;
+    const text = asText(data[key]).trim();
+    if (text) sections.push({ key, label: titleCase(key), text });
+  }
+
+  return {
+    id: String(entity.id),
+    title:
+      asText(pick(data, 'title', 'subject', 'headline')) ||
+      entity.name ||
+      `Untitled ${source} record`,
+    body: asText(pick(data, 'body', 'text', 'summary', 'description', 'content')),
+    sections,
+    occurredAt: asIso(pick(data, 'occurred_at', 'occurredAt', 'happened_at', 'date')),
+    source,
+    sourceLabel:
+      asText(pick(data, 'source_label', 'sourceLabel')) ||
+      sourceLabels[source] ||
+      titleCase(source),
+    sourceRef:
+      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),
+    scope: scopeOf(entity, fallbackScope),
+    ingestedAt: asIso(entity.created_at ?? entity.createdAt),
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  MoneyEvent
+// ---------------------------------------------------------------------------
+
+export function toMoneyEvent(
+  entity: TenantEntity,
+  fallbackScope: CorpusScope,
+  sourceLabels: Record<string, string> = {},
+): MoneyEvent {
+  const data = bag(entity);
+  const source = asText(pick(data, 'source', 'source_key', 'sourceKey')) || 'unknown';
+  const party = toPartyRef(pick(data, 'party', 'customer', 'counterparty'));
+  return {
+    id: String(entity.id),
+    subtype: asText(pick(data, 'subtype', 'kind', 'event_type', 'eventType')) || 'charge',
+    amount: asMinorUnits(pick(data, 'amount', 'amount_minor', 'amountMinor', 'total')),
+    currency: (asText(pick(data, 'currency')) || 'usd').toLowerCase(),
+    status: asText(pick(data, 'status', 'state')) || 'unknown',
+    occurredAt: asIso(pick(data, 'occurred_at', 'occurredAt', 'created', 'date')),
+    source,
+    sourceLabel:
+      asText(pick(data, 'source_label', 'sourceLabel')) || sourceLabels[source] || titleCase(source),
+    sourceRef:
+      asText(pick(data, 'source_ref', 'sourceRef')) || asText(entity.external_id ?? entity.externalId),
+    url: asText(pick(data, 'url', 'hosted_invoice_url', 'hostedInvoiceUrl')) || undefined,
+    description: asText(pick(data, 'description', 'summary', 'memo')) || undefined,
+    party,
+    scope: scopeOf(entity, fallbackScope),
+  };
+}
+
+/**
+ * A `MoneyEvent` read as a document, so the Ask surface can retrieve over
+ * meetings and revenue with ONE ranking pass. The bead's motivating question —
+ * "what did we agree with this company" — spans a meeting note and an invoice,
+ * and it cannot span them if they are ranked in separate universes.
+ */
+export function moneyEventAsDocument(event: MoneyEvent): SourceDocument {
+  const major = (event.amount / 100).toFixed(2);
+  const amount = `${event.currency.toUpperCase()} ${major}`;
+  const who = event.party ? event.party.name : 'an unnamed party';
+  return {
+    id: event.id,
+    title: `${titleCase(event.subtype)} — ${amount}${event.party ? ` (${event.party.name})` : ''}`,
+    body: [
+      `${titleCase(event.subtype)} of ${amount} for ${who}, status ${event.status}.`,
+      event.description ?? '',
+    ]
+      .filter(Boolean)
+      .join(' '),
+    sections: [],
+    occurredAt: event.occurredAt,
+    source: event.source,
+    sourceLabel: event.sourceLabel,
+    sourceRef: event.sourceRef,
+    url: event.url,
+    participants: event.party ? [event.party] : [],
+    scope: event.scope,
+  };
+}