@startsimpli/integrations 0.1.5 → 0.1.6

package/src/components/Markdown.tsx

@@ -0,0 +1,193 @@
+/**
+ * The small amount of Markdown that actually arrives in a corpus, rendered.
+ *
+ * WHY THIS EXISTS. Sources write Markdown and the corpus stores it verbatim —
+ * Granola's summary is `## Decisions` and `**$4,800 per month**`, and a model
+ * asked for prose answers in the same dialect. Rendering that as plain text puts
+ * literal hashes and asterisks on the screen, which reads as a bug in the
+ * product rather than as punctuation from the source.
+ *
+ * WHY IT IS ~100 LINES AND NOT A DEPENDENCY. A Markdown library is a peer
+ * dependency every consuming app has to install and a sanitiser decision every
+ * consuming app has to get right. This renders to REACT ELEMENTS — there is no
+ * `dangerouslySetInnerHTML` anywhere below, so untrusted document text cannot
+ * become markup, which is the property that actually matters for a surface whose
+ * whole job is displaying text somebody else wrote.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. No tables, no block quotes, no images, no
+ * single-asterisk emphasis (`*` appears in real prose far more often than it
+ * means italics, and a false positive silently eats characters out of a
+ * contract). Anything unrecognised falls through as its own literal text, which
+ * is the same thing the screen showed before — never worse.
+ */
+import * as React from 'react';
+
+/**
+ * Markdown reduced to the text a human would read aloud.
+ *
+ * For places that need a STRING rather than elements — a truncated one-line
+ * preview, a title, an `aria-label`. Same syntax coverage as the renderer.
+ */
+export function stripMarkdown(text: string): string {
+  if (!text) return '';
+  return text
+    .replace(/```[\s\S]*?```/g, (block) => block.replace(/```[^\n]*\n?/g, ''))
+    .replace(/^\s{0,3}#{1,6}\s+/gm, '')
+    .replace(/^\s{0,3}([-*_])\s*\1\s*\1[-*_\s]*$/gm, '')
+    .replace(/^\s{0,3}[-*+]\s+/gm, '')
+    .replace(/^\s{0,3}>\s?/gm, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/__([^_]+)__/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/[ \t]+\n/g, '\n')
+    .trim();
+}
+
+/** `**bold**`, `` `code` `` and `[text](url)` inside one line of text. */
+function inline(text: string, keyPrefix: string): React.ReactNode[] {
+  const nodes: React.ReactNode[] = [];
+  // One pass, one regex: whichever construct starts first wins, so a link whose
+  // label contains asterisks is still a link.
+  const pattern = /(\*\*|__)([\s\S]+?)\1|`([^`]+)`|\[([^\]]+)\]\(([^)\s]+)[^)]*\)/g;
+  let cursor = 0;
+  let match: RegExpExecArray | null;
+  let index = 0;
+
+  while ((match = pattern.exec(text)) !== null) {
+    if (match.index > cursor) nodes.push(text.slice(cursor, match.index));
+    index += 1;
+    const key = `${keyPrefix}-${index}`;
+    if (match[2] !== undefined) {
+      nodes.push(<strong key={key}>{match[2]}</strong>);
+    } else if (match[3] !== undefined) {
+      nodes.push(
+        <code key={key} className="rounded bg-black/5 px-1 py-0.5 text-[0.9em]">
+          {match[3]}
+        </code>,
+      );
+    } else if (match[4] !== undefined) {
+      const href = match[5] ?? '';
+      const safe = /^(https?:|mailto:)/i.test(href);
+      nodes.push(
+        safe ? (
+          <a key={key} href={href} target="_blank" rel="noreferrer" className="underline">
+            {match[4]}
+          </a>
+        ) : (
+          // A `javascript:` or otherwise unrecognised scheme keeps its LABEL and
+          // loses its link. Silently dropping the text would edit the document.
+          <React.Fragment key={key}>{match[4]}</React.Fragment>
+        ),
+      );
+    }
+    cursor = pattern.lastIndex;
+  }
+  if (cursor < text.length) nodes.push(text.slice(cursor));
+  return nodes.length ? nodes : [text];
+}
+
+const HEADING_CLASS = ['font-semibold', 'font-semibold', 'font-medium'];
+
+/**
+ * Block-level Markdown as React elements.
+ *
+ * `className` lands on the wrapper so an app's theme slot still styles the whole
+ * block exactly as it did when this was a `<p>` of raw text.
+ */
+export function Markdown({ text, className }: { text: string; className?: string }) {
+  const blocks = React.useMemo(() => parseBlocks(text ?? ''), [text]);
+  if (!text) return null;
+  return (
+    <div className={className}>
+      {blocks.map((block, blockIndex) => {
+        const key = `b${blockIndex}`;
+        if (block.kind === 'heading') {
+          const level = Math.min(block.level ?? 3, 3);
+          return (
+            <p
+              key={key}
+              className={`${HEADING_CLASS[level - 1] ?? 'font-medium'} ${blockIndex ? 'mt-3' : ''}`}
+            >
+              {inline(block.lines[0] ?? '', key)}
+            </p>
+          );
+        }
+        if (block.kind === 'list') {
+          return (
+            <ul key={key} className={`list-disc space-y-1 pl-5 ${blockIndex ? 'mt-2' : ''}`}>
+              {block.lines.map((line, lineIndex) => (
+                <li key={`${key}-${lineIndex}`}>{inline(line, `${key}-${lineIndex}`)}</li>
+              ))}
+            </ul>
+          );
+        }
+        if (block.kind === 'rule') {
+          return <hr key={key} className="my-3 border-black/10" />;
+        }
+        return (
+          <p key={key} className={`whitespace-pre-wrap ${blockIndex ? 'mt-2' : ''}`}>
+            {inline(block.lines.join('\n'), key)}
+          </p>
+        );
+      })}
+    </div>
+  );
+}
+
+interface Block {
+  kind: 'paragraph' | 'heading' | 'list' | 'rule';
+  lines: string[];
+  level?: number;
+}
+
+function parseBlocks(text: string): Block[] {
+  const blocks: Block[] = [];
+  let paragraph: string[] = [];
+  let list: string[] = [];
+
+  const flushParagraph = () => {
+    if (paragraph.length) blocks.push({ kind: 'paragraph', lines: paragraph });
+    paragraph = [];
+  };
+  const flushList = () => {
+    if (list.length) blocks.push({ kind: 'list', lines: list });
+    list = [];
+  };
+
+  for (const raw of text.replace(/\r\n/g, '\n').split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    const heading = /^\s{0,3}(#{1,6})\s+(.*)$/.exec(line);
+    const bullet = /^\s{0,3}[-*+]\s+(.*)$/.exec(line);
+    const numbered = /^\s{0,3}\d+[.)]\s+(.*)$/.exec(line);
+    const rule = /^\s{0,3}([-*_])\s*\1\s*\1[-*_\s]*$/.test(line);
+
+    if (!line.trim()) {
+      flushList();
+      flushParagraph();
+      continue;
+    }
+    if (rule) {
+      flushList();
+      flushParagraph();
+      blocks.push({ kind: 'rule', lines: [] });
+      continue;
+    }
+    if (heading) {
+      flushList();
+      flushParagraph();
+      blocks.push({ kind: 'heading', lines: [heading[2] ?? ''], level: heading[1].length });
+      continue;
+    }
+    if (bullet || numbered) {
+      flushParagraph();
+      list.push((bullet ? bullet[1] : numbered?.[1]) ?? '');
+      continue;
+    }
+    flushList();
+    paragraph.push(line);
+  }
+  flushList();
+  flushParagraph();
+  return blocks;
+}

package/src/components/index.ts

@@ -3,6 +3,7 @@ export * from './ConnectAccountCard';
 export * from './EmailList';
 export * from './EventList';
 export * from './EventListItem';
+export * from './Markdown';
 export * from './ReconsentPromptCard';
 
 // The connections layer (bd startsim-768w.22.3.4): ONE schema-driven form and

package/src/components/pages/AskPage.tsx

@@ -31,6 +31,7 @@
  */
 import * as React from 'react';
 
+import { Markdown, stripMarkdown } from '../Markdown';
 import type {
   AskMode,
   AskRequest,
@@ -259,7 +260,10 @@ function AnswerPanel({
         </p>
       ) : null}
 
-      <div className={`mt-3 ${cn.answer}`}>{result.answer}</div>
+      {/* A model asked for prose answers in Markdown. Rendering it as literal
+          text puts "**$4,800**" on the screen, which reads as the product
+          failing rather than as the model emphasising the number. */}
+      <Markdown text={result.answer} className={`mt-3 ${cn.answer}`} />
 
       {canSave ? (
         <button
@@ -300,7 +304,10 @@ function AnswerPanel({
             {/* The model's own quote, so the claim can be checked against the
                 record without opening it. */}
             {citation.quote ? (
-              <p className="mt-1 text-sm italic text-gray-600">“{citation.quote}”</p>
+              // Flattened, not rendered: a quotation is a span of the record's
+              // own words, and it should read as one line inside the quote
+              // marks rather than re-opening as a heading or a bullet.
+              <p className="mt-1 text-sm italic text-gray-600">“{stripMarkdown(citation.quote)}”</p>
             ) : null}
           </div>
         ))}
@@ -337,7 +344,7 @@ function ConsideredList({
   return (
     <details className="mt-3">
       <summary className="cursor-pointer text-sm text-gray-600">
-        {unused.length} more record{unused.length === 1 ? '' : 's'} were searched but not cited
+        {unused.length} more record{unused.length === 1 ? ' was' : 's were'} searched but not cited
       </summary>
       <div className="mt-2 space-y-1">
         {unused.map((item) => (
@@ -360,16 +367,34 @@ function ConsideredList({
   );
 }
 
+/**
+ * Who answered, said plainly.
+ *
+ * THREE CASES, not two (bd startsim-768w.38.21). A live model names itself. A
+ * STUB says it is a stub. And a workspace with NO provider configured is not a
+ * stub at all — "Answered by a none stub ((provider default))" was neither
+ * English nor true. Every branch keeps the `live: false` honesty; the point is
+ * to say the true thing clearly, not to soften it.
+ */
+function providerSentence(provider: AskResult['provider']): string {
+  const model = provider.model?.trim() ?? '';
+  if (provider.live) {
+    return model ? `Answered by ${provider.provider} · ${model}` : `Answered by ${provider.provider}`;
+  }
+  if (!provider.provider || provider.provider === 'none') {
+    return 'No model is configured for this workspace — no live model was called.';
+  }
+  return model
+    ? `Answered by a ${provider.provider} stub (${model}) — no live model was called`
+    : `Answered by a ${provider.provider} stub — no live model was called`;
+}
+
 function ProvenanceFooter({
   result, classNames: cn,
 }: { result: AskResult; classNames: Record<AskSlot, string> }) {
   return (
     <div className="mt-4 border-t pt-2">
-      <p className={cn.muted}>
-        {result.provider.live
-          ? `Answered by ${result.provider.provider} · ${result.provider.model}`
-          : `Answered by a ${result.provider.provider} stub (${result.provider.model}) — no live model was called`}
-      </p>
+      <p className={cn.muted}>{providerSentence(result.provider)}</p>
       {/* A non-zero drop means something upstream returned rows from another
           workspace. It is stated rather than swallowed, because the guard
           catching it is good news about the guard and bad news about the API. */}

package/src/components/pages/LibraryPage.tsx

@@ -27,6 +27,7 @@
  */
 import * as React from 'react';
 
+import { Markdown, stripMarkdown } from '../Markdown';
 import { enforceScope } from '../../corpus/retrieval';
 import type {
   CorpusApi,
@@ -107,8 +108,13 @@ function relative(value: string | null | undefined, now: number): string {
   return `${Math.round(hours / 24)}d ago`;
 }
 
+/**
+ * A row's one-line preview. The Markdown is FLATTENED rather than rendered
+ * here — a truncated heading and half a bold span are worse than plain prose,
+ * and the row is a summary, not the document.
+ */
 function preview(document: SourceDocument, length = 180): string {
-  const text = document.body || document.sections[0]?.text || '';
+  const text = stripMarkdown(document.body || document.sections[0]?.text || '');
   if (!text) return '';
   return text.length > length ? `${text.slice(0, length).trim()}…` : text;
 }
@@ -586,7 +592,9 @@ function DocumentDetail({
       {document.body ? (
         <div className="mt-3">
           <p className="text-sm font-medium text-gray-900">Summary</p>
-          <p className="mt-1 whitespace-pre-wrap text-sm text-gray-700">{document.body}</p>
+          {/* Sources write Markdown — a literal "## Decisions" on the screen
+              reads as a broken product, not as the source's punctuation. */}
+          <Markdown text={document.body} className="mt-1 text-sm text-gray-700" />
         </div>
       ) : null}
 

package/src/corpus/client.ts

@@ -16,9 +16,24 @@
  * `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,
+  indexParticipants,
+  toMoneyEvent,
+  toParty,
+  toSourceDocument,
+} from './entities';
+import type { CorpusTypeKeys, TenantEntity, TenantRelationship } from './entities';
 import type {
   CorpusApi,
   CorpusPage,
@@ -26,7 +41,7 @@ import type {
   DocumentQuery,
   MoneyEvent,
   Party,
-  SourceDocument,
+  PartyRef,
   SourceFreshness,
 } from './types';
 
@@ -49,9 +64,34 @@ export interface CreateCorpusApiOptions {
    */
   supportedFilters?: Array<keyof DocumentQuery>;
   /** 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> {
@@ -92,10 +132,15 @@ export function createCorpusApi(options: CreateCorpusApiOptions): CorpusApi {
     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 +159,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)) ?? []),
+        ),
+      };
     },
 
     /**