@startsimpli/integrations 0.1.5 → 0.2.1

package/src/corpus/client.ts

@@ -16,23 +16,51 @@
  * `apps/api/views.py`). So `supportedFilters` defaults to `[]` and the composer
  * says so on screen rather than pretending. Pass the real list once the tenant
  * API gains them; the request already sends every parameter.
+ *
+ * PEOPLE ARE A SECOND READ, NOT A SECOND COPY (bd startsim-768w.38.22). The
+ * corpus delivery writes participants as typed `authored_by` / `involves` edges
+ * and leaves only a `participant_count` on the document, so this adapter reads
+ * `/api/v1/relationships/` and joins. The alternative — denormalizing names back
+ * onto `data.participants` at delivery time — is one fewer round trip and a
+ * second copy of the graph that will drift; the edge is the declared contract,
+ * so the edge is what is read. The join is cached, bounded and fails soft.
  */
-import { toMoneyEvent, toParty, toSourceDocument, DEFAULT_TYPE_KEYS } from './entities';
-import type { CorpusTypeKeys, TenantEntity } from './entities';
+import {
+  DEFAULT_PARTICIPANT_EDGES,
+  DEFAULT_TYPE_KEYS,
+  commitmentToEntity,
+  indexParticipants,
+  toCommitment,
+  toMoneyEvent,
+  toParty,
+  toSourceDocument,
+} from './entities';
+import type { CorpusTypeKeys, TenantEntity, TenantRelationship } from './entities';
 import type {
+  Commitment,
+  CommitmentApi,
+  CommitmentQuery,
   CorpusApi,
   CorpusPage,
   CorpusScope,
   DocumentQuery,
   MoneyEvent,
   Party,
-  SourceDocument,
+  PartyRef,
   SourceFreshness,
 } from './types';
 
-/** The `@startsimpli/api` client surface this adapter needs, and no more. */
+/**
+ * The `@startsimpli/api` client surface this adapter needs, and no more.
+ *
+ * `post` is OPTIONAL: reading the corpus is the common case and a deployment
+ * that only reads should not have to supply a write method it never calls. The
+ * commitment write path checks for it and reports honestly when it is absent,
+ * rather than failing at the moment somebody presses a button.
+ */
 export interface CorpusHttp {
   get<T>(path: string, options?: { params?: Record<string, unknown> }): Promise<T>;
+  post?<T>(path: string, body?: unknown, options?: { params?: Record<string, unknown> }): Promise<T>;
 }
 
 export interface CreateCorpusApiOptions {
@@ -47,11 +75,36 @@ export interface CreateCorpusApiOptions {
    * Which `DocumentQuery` keys this deployment's API really applies. Anything
    * not listed is reported to the user as unfiltered rather than assumed.
    */
-  supportedFilters?: Array<keyof DocumentQuery>;
+  supportedFilters?: Array<keyof DocumentQuery | keyof CommitmentQuery>;
   /** Endpoint bases, without leading/trailing slashes (the client convention). */
-  paths?: { entities?: string; connections?: string };
+  paths?: { entities?: string; connections?: string; relationships?: string };
   /** How old a source's last sync may be before the Library calls it stale. */
   staleAfterHours?: number;
+  /**
+   * Resolve people from the tenant's typed EDGES into `participants`.
+   *
+   * On by default because it is what the shipped pipeline writes: the corpus
+   * delivery lands `source_document --involves--> party` edges and a bare
+   * `participant_count` on the document (bd startsim-768w.38.18). A deployment
+   * whose connectors denormalize participants inline can turn this off and save
+   * the round trip; the inline array is read either way.
+   */
+  resolveParticipants?: boolean;
+  /** Which edge types mean "this party is on this record". Data, not an enum. */
+  participantEdges?: readonly string[];
+  /**
+   * Bound on the graph read, in PAGES.
+   *
+   * The tenant relationships endpoint has no `?source=` filter today
+   * (`tenant-starter/apps/api/views.py` — see also bd startsim-768w.38.12 for
+   * the same gap on entities), so the edges for a page of documents cannot be
+   * requested directly and the graph is read in bulk and cached. This cap is
+   * what keeps that bounded rather than unbounded: past it, participants simply
+   * stop resolving for the older tail instead of the page hanging.
+   */
+  maxGraphPages?: number;
+  /** How long a loaded graph is reused before it is read again. */
+  graphTtlMs?: number;
 }
 
 interface DrfPage<T> {
@@ -63,6 +116,9 @@ interface DrfPage<T> {
 
 const EMPTY_PAGE = { count: 0, next: null, previous: null, results: [] };
 
+/** Rows written in parallel. Small enough not to look like a burst to the tenant. */
+const WRITE_CONCURRENCY = 6;
+
 function params(query: DocumentQuery, type: string) {
   const out: Record<string, unknown> = { type, page: query.page ?? 1 };
   if (query.pageSize) out.page_size = query.pageSize;
@@ -77,7 +133,7 @@ function params(query: DocumentQuery, type: string) {
 /** Which of the filters the caller asked for are actually honoured server-side. */
 function appliedFilters(
   query: DocumentQuery,
-  supported: Array<keyof DocumentQuery>,
+  supported: Array<string>,
 ): string[] {
   const requested = (['search', 'source', 'partyId', 'occurredAfter', 'occurredBefore'] as const).filter(
     (key) => Boolean(query[key]),
@@ -85,17 +141,22 @@ function appliedFilters(
   return requested.filter((key) => supported.includes(key));
 }
 
-export function createCorpusApi(options: CreateCorpusApiOptions): CorpusApi {
+export function createCorpusApi(options: CreateCorpusApiOptions): CorpusApi & CommitmentApi {
   const {
     http,
     scope,
     sourceLabels = {},
     supportedFilters = [],
     staleAfterHours = 26,
+    resolveParticipants = true,
+    participantEdges = DEFAULT_PARTICIPANT_EDGES,
+    maxGraphPages = 20,
+    graphTtlMs = 30_000,
   } = options;
   const types: CorpusTypeKeys = { ...DEFAULT_TYPE_KEYS, ...options.typeKeys };
   const entities = options.paths?.entities ?? 'api/v1/entities';
   const connections = options.paths?.connections ?? 'api/v1/connections';
+  const relationships = options.paths?.relationships ?? 'api/v1/relationships';
 
   async function page<T>(
     type: string,
@@ -114,26 +175,88 @@ export function createCorpusApi(options: CreateCorpusApiOptions): CorpusApi {
     };
   }
 
+  /** Every page of a DRF list, up to the cap. Stops on the first failure. */
+  async function readAll<T>(path: string, extra: Record<string, unknown>): Promise<T[]> {
+    const rows: T[] = [];
+    for (let index = 1; index <= maxGraphPages; index += 1) {
+      const response = await http.get<DrfPage<T>>(path, { params: { ...extra, page: index } });
+      const results = response?.results ?? [];
+      rows.push(...results);
+      if (!response?.next || results.length === 0) break;
+    }
+    return rows;
+  }
+
+  // ---------------------------------------------------------------------
+  //  the participant graph
+  // ---------------------------------------------------------------------
+  //
+  // ONE read for a page of documents, not one per document — and cached, so a
+  // screen that lists, opens a record and then asks a question spends it once.
+  // It FAILS SOFT: a tenant whose relationships endpoint is missing or refused
+  // renders exactly what it rendered before this existed, rather than an error
+  // where a Library used to be.
+  let graph: { at: number; value: Promise<Map<string, PartyRef[]>> } | null = null;
+
+  async function loadGraph(): Promise<Map<string, PartyRef[]>> {
+    const empty = new Map<string, PartyRef[]>();
+    if (!resolveParticipants) return empty;
+    try {
+      const partyRows = await readAll<TenantEntity>(entities, { type: types.party });
+      // No parties means no edge can resolve to a name, so the second read is
+      // pure cost — which is the common case on a freshly connected workspace.
+      if (partyRows.length === 0) return empty;
+      const parties = partyRows.map((entity) => toParty(entity, scope));
+      const edges = await readAll<TenantRelationship>(relationships, {});
+      return indexParticipants(edges, parties, participantEdges);
+    } catch {
+      return empty;
+    }
+  }
+
+  function participantGraph(): Promise<Map<string, PartyRef[]>> {
+    const now = Date.now();
+    if (!graph || now - graph.at > graphTtlMs) {
+      graph = { at: now, value: loadGraph() };
+    }
+    return graph.value;
+  }
+
   return {
-    listDocuments(query) {
-      return page<SourceDocument>(types.document, query, (entity) =>
-        toSourceDocument(entity, scope, sourceLabels),
-      );
+    async listDocuments(query) {
+      const documents = await page<TenantEntity>(types.document, query, (entity) => entity);
+      // Skip the graph entirely for an empty page: an empty corpus should cost
+      // exactly the one request it costs today.
+      const byRecord = documents.results.length ? await participantGraph() : new Map();
+      return {
+        ...documents,
+        results: documents.results.map((entity) =>
+          toSourceDocument(entity, scope, sourceLabels, byRecord.get(String(entity.id)) ?? []),
+        ),
+      };
     },
 
     async getDocument(id) {
-      const entity = await http.get<TenantEntity>(`${entities}/${encodeURIComponent(id)}`);
-      return toSourceDocument(entity, scope, sourceLabels);
+      const [entity, byRecord] = await Promise.all([
+        http.get<TenantEntity>(`${entities}/${encodeURIComponent(id)}`),
+        participantGraph(),
+      ]);
+      return toSourceDocument(entity, scope, sourceLabels, byRecord.get(String(entity.id)) ?? []);
     },
 
     listParties(query = {}) {
       return page<Party>(types.party, query, (entity) => toParty(entity, scope));
     },
 
-    listMoneyEvents(query = {}) {
-      return page<MoneyEvent>(types.moneyEvent, query, (entity) =>
-        toMoneyEvent(entity, scope, sourceLabels),
-      );
+    async listMoneyEvents(query = {}) {
+      const events = await page<TenantEntity>(types.moneyEvent, query, (entity) => entity);
+      const byRecord = events.results.length ? await participantGraph() : new Map();
+      return {
+        ...events,
+        results: events.results.map((entity) =>
+          toMoneyEvent(entity, scope, sourceLabels, byRecord.get(String(entity.id)) ?? []),
+        ),
+      };
     },
 
     /**
@@ -144,6 +267,71 @@ export function createCorpusApi(options: CreateCorpusApiOptions): CorpusApi {
      * Dropbox has contributed zero documents — and a count derived from the
      * corpus alone can never say it.
      */
+    /**
+     * The tracking surface's read (bd startsim-768w.38.25).
+     *
+     * SERVER-SIDE FILTERING, ALWAYS (CLAUDE.md rule 8) — status, owner and due
+     * window all go out as query parameters. The tenant does not honour them
+     * yet (bd startsim-768w.38.12 is the bead for that, and the filters that
+     * matter most for THIS screen are status/owner/dueBefore, not full text), so
+     * `appliedFilters` reports the gap and the composer says so on screen rather
+     * than rendering an unfiltered list under a filled-in control.
+     */
+    async listCommitments(query: CommitmentQuery = {}): Promise<CorpusPage<Commitment>> {
+      const statuses = Array.isArray(query.status) ? query.status : query.status ? [query.status] : [];
+      const response = await http.get<DrfPage<TenantEntity>>(entities, {
+        params: {
+          type: types.commitment,
+          page: query.page ?? 1,
+          ...(query.pageSize ? { page_size: query.pageSize } : {}),
+          ...(statuses.length ? { status: statuses.join(',') } : {}),
+          ...(query.subtype ? { subtype: query.subtype } : {}),
+          ...(query.owner ? { owner: query.owner } : {}),
+          ...(query.dueBefore ? { due_before: query.dueBefore } : {}),
+          ...(query.changedAfter ? { changed_after: query.changedAfter } : {}),
+          ...(query.search ? { search: query.search } : {}),
+        },
+      });
+      return {
+        count: response.count ?? response.results?.length ?? 0,
+        next: response.next ?? null,
+        previous: response.previous ?? null,
+        results: (response.results ?? []).map((entity) => toCommitment(entity, scope, sourceLabels)),
+        appliedFilters: (['status', 'subtype', 'owner', 'dueBefore', 'changedAfter', 'search'] as const)
+          .filter((key) => Boolean(query[key]))
+          .filter((key) => (supportedFilters as string[]).includes(key)),
+      };
+    },
+
+    /**
+     * Write a run's commitments back.
+     *
+     * ONE REQUEST PER ROW, because that is what the tenant offers: its
+     * `/api/v1/entities/upsert/` takes a single record (verified on the wire —
+     * a list body is rejected with `external_id: required for upsert`). The
+     * writes are therefore fanned out with a bounded concurrency rather than
+     * looped serially, and the missing bulk endpoint is filed rather than
+     * pretended away.
+     *
+     * Idempotency is the SERVER's, not this function's: the upsert is keyed on
+     * (entity_type, external_id), so a second run rewrites rows in place and two
+     * concurrent runs converge instead of duplicating.
+     */
+    async saveCommitments(commitments: Commitment[]): Promise<void> {
+      if (!http.post) {
+        throw new Error('This corpus client is read-only — no write method was supplied.');
+      }
+      const post = http.post.bind(http);
+      const payloads = commitments.map(commitmentToEntity);
+      for (let index = 0; index < payloads.length; index += WRITE_CONCURRENCY) {
+        await Promise.all(
+          payloads
+            .slice(index, index + WRITE_CONCURRENCY)
+            .map((payload) => post(`${entities}/upsert`, payload)),
+        );
+      }
+    },
+
     async listSources(): Promise<SourceFreshness[]> {
       const [connectionPage, documentPage] = await Promise.all([
         http