@startsimpli/integrations 0.1.6 → 0.2.1

package/src/components/pages/TrackerPage.tsx

@@ -0,0 +1,437 @@
+/**
+ * THE TRACKING SURFACE — what came out of your meetings and is still owed
+ * (bd startsim-768w.38.25).
+ *
+ * `<TrackerPage api={trackerApi} scope={scope} />`, the same injected shape as
+ * `ConnectionsPage`, `LibraryPage` and `AskPage`. The app owns className slots
+ * and a wrapper; extraction happens behind `api.extract`, server-side, where the
+ * provider key is. Nothing in this file imports a provider.
+ *
+ * THE SCREEN ANSWERS FOUR QUESTIONS and nothing else, because those are the four
+ * a person actually has: what is outstanding, who owns it, what is overdue, and
+ * what changed since last week. Everything on it is either one of those or the
+ * evidence for one of those.
+ *
+ * EVERY ROW IS TRACEABLE, for exactly the reason `AskPage` enforces citations:
+ * an item nobody can trace back to something a person said is an item nobody
+ * will act on. So each row carries the meetings it came from, the verbatim quote
+ * from each, and a click-through to the record. A commitment with no mention
+ * cannot be rendered, because it cannot exist.
+ *
+ * FILTERS ARE SERVER PARAMETERS (CLAUDE.md rule 8) and the screen SAYS SO when
+ * the deployment's data API does not honour one — same `appliedFilters`
+ * mechanism the Library uses. A status filter that silently does nothing is
+ * worse on this screen than on any other: the whole product claim is "this is
+ * what is still open".
+ */
+import * as React from 'react';
+
+import { stripMarkdown } from '../Markdown';
+import type {
+  Commitment,
+  CommitmentQuery,
+  CommitmentStatus,
+  CommitmentTrackerApi,
+  CorpusScope,
+  ExtractionResult,
+} from '../../corpus/types';
+
+export interface TrackerPageProps {
+  api: CommitmentTrackerApi;
+  scope: CorpusScope;
+  /** Click-through from a mention to the record, normally the Library route. */
+  onOpenDocument?: (documentId: string) => void;
+  /** Injectable clock, so "overdue" and "this week" are testable. */
+  now?: number;
+  classNames?: Partial<Record<TrackerSlot, string>>;
+}
+
+type TrackerSlot =
+  | 'root' | 'section' | 'heading' | 'card' | 'badge' | 'button' | 'secondaryButton'
+  | 'input' | 'muted' | 'error' | 'warning' | 'row' | 'due';
+
+const DEFAULTS: Record<TrackerSlot, string> = {
+  root: 'space-y-6',
+  section: 'space-y-3',
+  heading: 'text-lg font-semibold text-gray-900',
+  card: 'rounded-lg border border-gray-200 p-4',
+  badge: 'inline-flex items-center rounded-full border border-gray-300 px-2 py-0.5 text-xs text-gray-700',
+  button: 'rounded-md bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50',
+  secondaryButton: 'rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium text-gray-800 disabled:opacity-50',
+  input: 'rounded-md border border-gray-300 px-3 py-1.5 text-sm',
+  muted: 'text-sm text-gray-500',
+  error: 'text-sm text-red-600',
+  warning: 'rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900',
+  row: 'rounded-lg border border-gray-200 p-4',
+  due: 'text-sm font-medium text-red-700',
+};
+
+const STATUS_TABS: Array<{ key: 'open' | 'overdue' | 'recent' | 'done'; label: string }> = [
+  { key: 'open', label: 'Outstanding' },
+  { key: 'overdue', label: 'Overdue' },
+  { key: 'recent', label: 'Changed this week' },
+  { key: 'done', label: 'Closed' },
+];
+
+const WEEK_MS = 7 * 24 * 3600 * 1000;
+
+export function TrackerPage({
+  api,
+  scope,
+  onOpenDocument,
+  now = Date.now(),
+  classNames = {},
+}: TrackerPageProps) {
+  const cn = { ...DEFAULTS, ...classNames };
+
+  const [tab, setTab] = React.useState<'open' | 'overdue' | 'recent' | 'done'>('open');
+  const [owner, setOwner] = React.useState('');
+  const [rows, setRows] = React.useState<Commitment[]>([]);
+  const [applied, setApplied] = React.useState<string[]>([]);
+  const [loading, setLoading] = React.useState(true);
+  const [error, setError] = React.useState('');
+  const [run, setRun] = React.useState<ExtractionResult | null>(null);
+  const [running, setRunning] = React.useState(false);
+
+  const query = React.useMemo<CommitmentQuery>(
+    () => ({
+      // The SERVER is asked for what the tab means. What comes back is then
+      // narrowed again below — see `visible` — because a deployment whose API
+      // ignores `status` would otherwise render closed items under "Outstanding"
+      // and the banner alone would be doing all the work.
+      status: tab === 'done' ? 'done' : (['open', 'blocked'] as CommitmentStatus[]),
+      ...(owner.trim() ? { owner: owner.trim() } : {}),
+      ...(tab === 'recent' ? { changedAfter: new Date(now - WEEK_MS).toISOString() } : {}),
+      ...(tab === 'overdue' ? { dueBefore: new Date(now).toISOString() } : {}),
+      pageSize: 200,
+    }),
+    [tab, owner, now],
+  );
+
+  const load = React.useCallback(async () => {
+    setLoading(true);
+    setError('');
+    try {
+      const page = await api.listCommitments(query);
+      setRows(page.results);
+      setApplied(page.appliedFilters ?? []);
+    } catch (err) {
+      setRows([]);
+      setError(failureMessage(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [api, query]);
+
+  React.useEffect(() => { void load(); }, [load]);
+
+  /**
+   * The tab, applied in the browser as well as sent to the server.
+   *
+   * NOT a violation of rule 8 — the query still goes out as parameters and the
+   * server still pages. This is the honest belt to the server's braces: until bd
+   * startsim-768w.38.12 teaches the tenant API `?status=`, the API returns
+   * everything, and a screen that showed closed items under "Outstanding" would
+   * be lying about the one thing it exists to say. The banner below states that
+   * the list is not server-filtered, so the user knows the count is over what
+   * this page could fetch rather than over the whole corpus.
+   */
+  const visible = React.useMemo(() => {
+    const byTab = rows.filter((item) => {
+      if (tab === 'done') return item.status === 'done' || item.status === 'dropped';
+      if (item.status !== 'open' && item.status !== 'blocked') return false;
+      if (tab === 'overdue') return isOverdue(item, now);
+      if (tab === 'recent') return changedSince(item, now - WEEK_MS);
+      return true;
+    });
+    const needle = owner.trim().toLowerCase();
+    const byOwner = needle
+      ? byTab.filter((item) => (item.ownerName ?? '').toLowerCase().includes(needle))
+      : byTab;
+    return [...byOwner].sort(compareForScreen(now));
+  }, [rows, tab, owner, now]);
+
+  const unfiltered = (['status', 'owner', 'dueBefore', 'changedAfter'] as const).filter(
+    (key) => Boolean(query[key]) && !applied.includes(key),
+  );
+
+  return (
+    <div className={cn.root}>
+      <section className={cn.section}>
+        <div className="flex flex-wrap items-center gap-2">
+          <div className="flex gap-2" role="tablist" aria-label="What to show">
+            {STATUS_TABS.map((entry) => (
+              <button
+                key={entry.key}
+                type="button"
+                role="tab"
+                aria-selected={tab === entry.key}
+                className={tab === entry.key ? cn.button : cn.secondaryButton}
+                onClick={() => setTab(entry.key)}
+              >
+                {entry.label}
+              </button>
+            ))}
+          </div>
+          <label className="ml-auto flex items-center gap-2">
+            <span className="sr-only">Filter by owner</span>
+            <input
+              className={cn.input}
+              value={owner}
+              placeholder="Owner"
+              onChange={(event) => setOwner(event.target.value)}
+            />
+          </label>
+          {api.extract ? (
+            <button
+              type="button"
+              className={cn.secondaryButton}
+              disabled={running}
+              onClick={async () => {
+                setRunning(true);
+                setError('');
+                try {
+                  setRun(await api.extract!({ scope }));
+                  await load();
+                } catch (err) {
+                  setError(failureMessage(err));
+                } finally {
+                  setRunning(false);
+                }
+              }}
+            >
+              {running ? 'Reading your meetings…' : 'Pull from meetings'}
+            </button>
+          ) : null}
+        </div>
+
+        {unfiltered.length ? (
+          // The same honesty the Library owes about search, owed here about
+          // status — and it matters more here, because "outstanding" is the
+          // claim the whole screen makes.
+          <p className={cn.warning} role="status">
+            This workspace’s data API does not filter by {unfiltered.join(', ')} yet, so this list was
+            narrowed in the browser over the records it could fetch. Counts are over that set, not
+            over the whole corpus.
+          </p>
+        ) : null}
+
+        {error ? <p className={cn.error} role="alert">{error}</p> : null}
+        {run ? <RunSummary result={run} classNames={cn} onOpenDocument={onOpenDocument} /> : null}
+      </section>
+
+      <section className={cn.section} aria-label="Commitments">
+        <h2 className={cn.heading}>
+          {loading ? 'Loading…' : `${visible.length} item${visible.length === 1 ? '' : 's'}`}
+        </h2>
+
+        {!loading && visible.length === 0 ? (
+          <p className={cn.muted}>
+            {rows.length === 0
+              ? 'Nothing has been pulled out of your meetings yet. Connect a source, then run “Pull from meetings”.'
+              : 'Nothing matches this view. Everything here is either closed or filtered out.'}
+          </p>
+        ) : null}
+
+        {visible.map((item) => (
+          <CommitmentRow
+            key={item.externalId}
+            item={item}
+            now={now}
+            classNames={cn}
+            onOpenDocument={onOpenDocument}
+          />
+        ))}
+      </section>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+
+function CommitmentRow({
+  item, now, classNames: cn, onOpenDocument,
+}: {
+  item: Commitment;
+  now: number;
+  classNames: Record<TrackerSlot, string>;
+  onOpenDocument?: (documentId: string) => void;
+}) {
+  const overdue = isOverdue(item, now);
+  const age = item.firstSeenAt ? Math.floor((now - Date.parse(item.firstSeenAt)) / 86_400_000) : null;
+
+  return (
+    <article className={cn.row}>
+      <div className="flex flex-wrap items-center gap-2">
+        <span className={cn.badge}>{item.subtype}</span>
+        {item.status !== 'open' ? <span className={cn.badge}>{item.status}</span> : null}
+        <h3 className="text-sm font-medium text-gray-900">{item.title}</h3>
+      </div>
+
+      <div className="mt-1 flex flex-wrap items-center gap-3">
+        {item.ownerName ? (
+          <span className="text-sm text-gray-700">{item.ownerName}</span>
+        ) : (
+          // Stated, not blank. "Nobody said who" is a fact about the meeting and
+          // it is the single most actionable thing on this screen.
+          <span className={cn.muted}>No owner named</span>
+        )}
+        {item.subject ? <span className={cn.muted}>· {item.subject}</span> : null}
+        {item.dueAt ? (
+          <span className={overdue ? cn.due : cn.muted}>
+            {overdue ? 'Overdue ' : 'Due '}
+            {new Date(item.dueAt).toLocaleDateString()}
+          </span>
+        ) : null}
+        {age !== null && age > 0 ? (
+          <span className={cn.muted}>
+            {/* The sentence the product exists to say. */}
+            open for {age} day{age === 1 ? '' : 's'}
+          </span>
+        ) : null}
+        {item.mentions.length > 1 ? (
+          <span className={cn.badge}>raised in {item.mentions.length} meetings</span>
+        ) : null}
+      </div>
+
+      {item.detail ? <p className="mt-2 text-sm text-gray-700">{item.detail}</p> : null}
+
+      {item.statusReason ? (
+        <p className="mt-2 text-sm text-gray-600">
+          {/* Why does it say this is closed? Answerable without opening the
+              meeting, or nobody will trust a single closed row. */}
+          {item.status === 'done' ? 'Closed by' : 'Blocked by'}: “{stripMarkdown(item.statusReason)}”
+        </p>
+      ) : null}
+
+      <details className="mt-2">
+        <summary className="cursor-pointer text-sm text-gray-600">
+          From {item.mentions.length} meeting{item.mentions.length === 1 ? '' : 's'}
+        </summary>
+        <div className="mt-2 space-y-2">
+          {item.mentions.map((mention) => (
+            <div key={`${mention.documentId}:${mention.originKey}`} className="border-t pt-2">
+              <div className="flex flex-wrap items-center gap-2">
+                <button
+                  type="button"
+                  className="text-sm text-blue-700 underline"
+                  onClick={() => onOpenDocument?.(mention.documentId)}
+                >
+                  {mention.occurredAt ? new Date(mention.occurredAt).toLocaleDateString() : 'Undated meeting'}
+                </button>
+                {/* Where the row came from. A model-derived item and one the
+                    summariser itself wrote down are different levels of
+                    evidence, and the difference belongs on screen. */}
+                <span className={cn.badge}>
+                  {mention.extractor === 'rules' ? 'from the meeting’s own next steps' : 'read from the notes'}
+                </span>
+              </div>
+              {mention.quote ? (
+                <p className="mt-1 text-sm italic text-gray-600">“{stripMarkdown(mention.quote)}”</p>
+              ) : null}
+            </div>
+          ))}
+        </div>
+      </details>
+    </article>
+  );
+}
+
+/**
+ * What the last run did, in the terms that make it arguable.
+ *
+ * `fromRules` vs `fromModel` is here on purpose: it is the measurement of what
+ * the model is actually contributing over the structure the summariser already
+ * wrote, and if that number is ever zero the model call should be switched off
+ * rather than paid for.
+ */
+function RunSummary({
+  result, classNames: cn, onOpenDocument,
+}: {
+  result: ExtractionResult;
+  classNames: Record<TrackerSlot, string>;
+  onOpenDocument?: (documentId: string) => void;
+}) {
+  return (
+    <div className={cn.card}>
+      <p className="text-sm text-gray-800">
+        Read {result.documentsProcessed} meeting{result.documentsProcessed === 1 ? '' : 's'}:{' '}
+        {result.created} new, {result.merged} matched to something already tracked,{' '}
+        {result.resolved} closed by a later meeting.
+      </p>
+      <p className={cn.muted}>
+        {result.fromRules} came from the meetings’ own next-step lists, {result.fromModel} were read
+        out of the notes by {result.provider.live ? `${result.provider.provider} · ${result.provider.model}` : 'no live model'}.
+      </p>
+
+      {result.needsReview.length ? (
+        // Weak resolution matches are shown, never applied. A to-do list that
+        // quietly empties itself is the one failure with no symptom.
+        <div className={`mt-2 ${cn.warning}`} role="status">
+          <p>
+            {result.needsReview.length} meeting statement
+            {result.needsReview.length === 1 ? '' : 's'} looked like they closed something, but not
+            closely enough to act on. Nothing was closed automatically.
+          </p>
+          <ul className="mt-1 space-y-1">
+            {result.needsReview.map((entry) => (
+              <li key={`${entry.commitmentId}:${entry.documentId}`}>
+                <button
+                  type="button"
+                  className="text-sm underline"
+                  onClick={() => onOpenDocument?.(entry.documentId)}
+                >
+                  “{stripMarkdown(entry.quote).slice(0, 120)}”
+                </button>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+
+      {result.droppedOutOfScope > 0 ? (
+        <p className={cn.error} role="status">
+          {result.droppedOutOfScope} record{result.droppedOutOfScope === 1 ? '' : 's'} from another
+          workspace were returned by the data API and excluded before extracting.
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+
+function isOverdue(item: Commitment, now: number): boolean {
+  if (!item.dueAt) return false;
+  if (item.status !== 'open' && item.status !== 'blocked') return false;
+  const at = Date.parse(item.dueAt);
+  return !Number.isNaN(at) && at < now;
+}
+
+function changedSince(item: Commitment, since: number): boolean {
+  const stamps = [item.lastSeenAt, item.resolvedAt].filter(Boolean) as string[];
+  return stamps.some((stamp) => Date.parse(stamp) >= since);
+}
+
+/**
+ * Overdue first, then the oldest thing still open.
+ *
+ * Sorting by "raised longest ago and still not done" rather than by recency is
+ * the whole difference between a list of meetings and a list of debts.
+ */
+function compareForScreen(now: number) {
+  return (a: Commitment, b: Commitment): number => {
+    const overdue = Number(isOverdue(b, now)) - Number(isOverdue(a, now));
+    if (overdue !== 0) return overdue;
+    if (a.dueAt && b.dueAt && a.dueAt !== b.dueAt) return a.dueAt.localeCompare(b.dueAt);
+    if (a.dueAt !== b.dueAt) return a.dueAt ? -1 : 1;
+    return (a.firstSeenAt ?? '').localeCompare(b.firstSeenAt ?? '');
+  };
+}
+
+function failureMessage(err: unknown): string {
+  const status = (err as { status?: number })?.status;
+  if (status === 403) return 'You do not have access to this workspace’s records.';
+  if (status === 401) return 'Your session has expired. Sign in again.';
+  return (err as { message?: string })?.message || 'That could not be loaded right now.';
+}

package/src/corpus/client.ts

@@ -28,13 +28,18 @@
 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,
@@ -45,9 +50,17 @@ import type {
   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 {
@@ -62,7 +75,7 @@ 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; relationships?: string };
   /** How old a source's last sync may be before the Library calls it stale. */
@@ -103,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;
@@ -117,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]),
@@ -125,7 +141,7 @@ 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,
@@ -251,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