@startsimpli/integrations 0.1.3 → 0.1.5

package/src/corpus/fixtures.ts

@@ -0,0 +1,486 @@
+/**
+ * A multi-source fixture corpus, shipped as a TESTING UTILITY.
+ *
+ * WHY IT IS IN THE PACKAGE and not in a test file or a harness app: the vitest
+ * suite and the browser harness must exercise the same corpus, or "it renders"
+ * and "it passes" are claims about two different things. Same reasoning as
+ * `startsimpli_connectors.testing.load_fixture` on the backend.
+ *
+ * PROVENANCE. The Granola rows carry the note ids, titles, timestamps,
+ * attendees and transcript lines from
+ * `start-simpli-api/packages/startsimpli-connectors/tests/fixtures/granola/`,
+ * and the money rows carry the ids, amounts and currencies from the `stripe/`
+ * set next to it. Those upstream fixtures are themselves CONSTRUCTED, not
+ * captured — Granola publishes no sandbox — and their README says so; nothing
+ * here is more real than they are.
+ *
+ * THE DROPBOX AND DRIVE ROWS ARE NOT DECORATION. bd startsim-768w.38.6's
+ * standing test is "would this row, badge, filter or empty state still make
+ * sense if the only connected source were Dropbox?". A fixture set containing
+ * only meeting notes cannot answer that question, so this one contains a signed
+ * contract from Dropbox and a pricing sheet from Drive, with their long-form
+ * text in `sections` exactly the way a transcript arrives. Any screen that
+ * renders the Granola rows well and these badly has failed the test visibly.
+ *
+ * THE SECOND ORG IS THE SCOPE TEST. `northwind` holds a document that answers a
+ * `tandem` question BETTER than anything `tandem` owns. That is deliberate: it
+ * is the shape of the leak that matters — not a random foreign row, but the one
+ * a ranker would happily pick if nothing stopped it.
+ */
+import type {
+  CorpusApi,
+  CorpusPage,
+  CorpusScope,
+  DocumentQuery,
+  MoneyEvent,
+  Party,
+  SourceDocument,
+  SourceFreshness,
+} from './types';
+
+/** The tenant every fixture document belongs to unless stated otherwise. */
+export const FIXTURE_ORG = 'tandem';
+/** A DIFFERENT customer workspace under the same foundry (bd startsim-768w.34.4). */
+export const FIXTURE_OTHER_ORG = 'northwind';
+
+const OWNER_A = 'usr_dana';
+const OWNER_B = 'usr_sam';
+
+const scope = (orgId: string, ownerSub: string): CorpusScope => ({ orgId, ownerSub });
+
+const DANA = { id: 'party_dana', name: 'Dana Reed', kind: 'person', email: 'dana.reed@example.com' };
+const SAM = { id: 'party_sam', name: 'Sam Ortiz', kind: 'person', email: 'sam.ortiz@example.com' };
+const KIM = { id: 'party_kim', name: 'Kim Li', kind: 'person', email: 'kim.li@example.com' };
+const ACME = { id: 'party_acme', name: 'Acme Robotics', kind: 'company', email: 'ada@example.com' };
+const BETA = { id: 'party_beta', name: 'Beta Foods', kind: 'company', email: 'bo@example.com' };
+
+export const FIXTURE_PARTIES: Party[] = [
+  { ...DANA, source: 'granola', sourceLabel: 'Granola', sourceRef: 'dana.reed@example.com', scope: scope(FIXTURE_ORG, OWNER_A) },
+  { ...SAM, source: 'granola', sourceLabel: 'Granola', sourceRef: 'sam.ortiz@example.com', scope: scope(FIXTURE_ORG, OWNER_A) },
+  { ...KIM, source: 'granola', sourceLabel: 'Granola', sourceRef: 'kim.li@example.com', scope: scope(FIXTURE_ORG, OWNER_A) },
+  { ...ACME, source: 'stripe', sourceLabel: 'Stripe', sourceRef: 'cus_RedSuite01Acme', scope: scope(FIXTURE_ORG, OWNER_A) },
+  { ...BETA, source: 'stripe', sourceLabel: 'Stripe', sourceRef: 'cus_RedSuite02Beta', scope: scope(FIXTURE_ORG, OWNER_A) },
+];
+
+const GRANOLA_TRANSCRIPT = [
+  'Dana Reed: Morning — let’s start with the connector.',
+  'Sam Ortiz: Sounds good. I pulled the OpenAPI shapes yesterday.',
+  'Dana Reed: The transcript is going on its own entity.',
+  'Sam Ortiz: Agreed — fifty transcripts a page is not a page.',
+  'Dana Reed: On renewal, Acme want the same rate for another twelve months.',
+  'Sam Ortiz: Then we hold at four thousand a month and cap the seats at forty.',
+].join('\n');
+
+export const FIXTURE_DOCUMENTS: SourceDocument[] = [
+  {
+    id: 'not_1d3tmYTlCICgjy',
+    title: 'Acme <> StartSimpli weekly sync',
+    body: 'Agreed to ship the connector RED suite first. Acme asked to renew at the same rate for another twelve months.',
+    sections: [{ key: 'transcript', label: 'Transcript', text: GRANOLA_TRANSCRIPT }],
+    occurredAt: '2026-01-27T15:30:00Z',
+    source: 'granola',
+    sourceLabel: 'Granola',
+    sourceRef: 'not_1d3tmYTlCICgjy',
+    url: 'https://notes.granola.ai/d/9f1c2b7e-2a44-4f3e-9a0d-6c1b8e5d4a21',
+    participants: [DANA, SAM, KIM, ACME],
+    scope: scope(FIXTURE_ORG, OWNER_A),
+    ingestedAt: '2026-01-27T16:10:00Z',
+  },
+  {
+    id: 'not_7Kq2ZbVnRt4aXm',
+    title: 'Design review',
+    body: 'Reviewed the two-entity split. Note and transcript become separate records so a page of fifty stays a page.',
+    sections: [],
+    occurredAt: '2026-01-26T11:00:00Z',
+    source: 'granola',
+    sourceLabel: 'Granola',
+    sourceRef: 'not_7Kq2ZbVnRt4aXm',
+    url: 'https://notes.granola.ai/d/2b7d41ce-8f05-4a19-b3d2-77e4c0a9f118',
+    participants: [DANA, SAM],
+    scope: scope(FIXTURE_ORG, OWNER_A),
+    ingestedAt: '2026-01-26T11:52:00Z',
+  },
+  {
+    // The upstream fixture has `title: null` and no calendar event. A row with
+    // no title is a real row and must still render — see `note_detail_no_calendar`.
+    id: 'not_Pd9wLs3EhY6cQz',
+    title: 'Untitled granola record',
+    body: 'Ad-hoc call, no calendar invite.',
+    sections: [],
+    occurredAt: '2026-01-25T09:15:00Z',
+    source: 'granola',
+    sourceLabel: 'Granola',
+    sourceRef: 'not_Pd9wLs3EhY6cQz',
+    participants: [DANA],
+    scope: scope(FIXTURE_ORG, OWNER_B),
+    ingestedAt: '2026-01-25T09:40:00Z',
+  },
+  {
+    // `note_detail_no_transcript.json`: the transcript was auto-deleted upstream
+    // and the summary is empty. A document with no readable text is the emptiest
+    // real row the Library will ever be handed.
+    id: 'not_Xa4mB8vTuN2kRe',
+    title: 'Board prep (transcript auto-deleted upstream)',
+    body: '',
+    sections: [],
+    occurredAt: '2026-01-20T13:00:00Z',
+    source: 'granola',
+    sourceLabel: 'Granola',
+    sourceRef: 'not_Xa4mB8vTuN2kRe',
+    participants: [DANA],
+    scope: scope(FIXTURE_ORG, OWNER_A),
+    ingestedAt: '2026-01-24T08:05:00Z',
+  },
+  {
+    // Dropbox: the second source John named, and the one the generic test is
+    // written against. Same type, same badge, same detail view, no new code.
+    id: 'dbx_9812f0',
+    title: 'Acme Robotics — Master Services Agreement (signed)',
+    body: 'Signed MSA between StartSimpli and Acme Robotics, effective 1 February 2026, initial term twelve months.',
+    sections: [
+      {
+        key: 'extracted_text',
+        label: 'Extracted text',
+        text: [
+          'MASTER SERVICES AGREEMENT',
+          '1. Term. This Agreement begins on 1 February 2026 and continues for twelve (12) months.',
+          '2. Fees. Customer shall pay USD 4,000 per month, invoiced monthly in advance.',
+          '3. Seats. The subscription covers up to forty (40) named seats.',
+          '4. Renewal. This Agreement renews for successive twelve-month terms unless either party gives sixty (60) days notice.',
+          '5. Termination for convenience requires ninety (90) days written notice.',
+        ].join('\n'),
+      },
+    ],
+    occurredAt: '2026-02-01T00:00:00Z',
+    source: 'dropbox',
+    sourceLabel: 'Dropbox',
+    sourceRef: 'id:9812f0a4b1',
+    url: 'https://www.dropbox.example/scl/fi/9812f0a4b1/acme-msa-signed.pdf',
+    participants: [ACME, DANA],
+    scope: scope(FIXTURE_ORG, OWNER_A),
+    ingestedAt: '2026-02-02T06:00:00Z',
+  },
+  {
+    id: 'gdrive_1QpZ',
+    title: 'Rate card 2026',
+    body: 'Standard pricing for 2026. Platform tier USD 4,000 per month up to forty seats; overage USD 90 per seat per month.',
+    sections: [
+      {
+        key: 'extracted_text',
+        label: 'Extracted text',
+        text: 'Platform: USD 4,000/mo (40 seats). Overage: USD 90/seat/mo. Discounts require VP approval above 15%.',
+      },
+    ],
+    occurredAt: '2026-01-05T00:00:00Z',
+    source: 'gdrive',
+    sourceLabel: 'Google Drive',
+    sourceRef: '1QpZv7t9kR',
+    url: 'https://docs.google.example/document/d/1QpZv7t9kR',
+    participants: [DANA],
+    scope: scope(FIXTURE_ORG, OWNER_A),
+    ingestedAt: '2026-01-06T07:30:00Z',
+  },
+  {
+    // ---- A DIFFERENT CUSTOMER WORKSPACE ----
+    // Deliberately the BEST answer to "what did we agree with Acme on renewal":
+    // more specific, more recent, and full of exactly the terms a ranker loves.
+    // Nothing but the scope guard stands between it and a very convincing leak.
+    id: 'nw_contract_44',
+    title: 'Acme Robotics renewal — Northwind terms (CONFIDENTIAL)',
+    body: 'Northwind renewed Acme Robotics at USD 2,750 per month with unlimited seats and a ninety-day out. Do not share outside Northwind.',
+    sections: [
+      {
+        key: 'extracted_text',
+        label: 'Extracted text',
+        text: 'Renewal rate USD 2,750/mo. Unlimited seats. Ninety (90) day termination for convenience. Acme renewal signed 2026-02-10.',
+      },
+    ],
+    occurredAt: '2026-02-10T00:00:00Z',
+    source: 'dropbox',
+    sourceLabel: 'Dropbox',
+    sourceRef: 'id:nw44a2',
+    participants: [ACME],
+    scope: scope(FIXTURE_OTHER_ORG, 'usr_northwind'),
+    ingestedAt: '2026-02-10T09:00:00Z',
+  },
+];
+
+export const FIXTURE_MONEY_EVENTS: MoneyEvent[] = [
+  {
+    id: 'in_RedSuiteUsd0001',
+    subtype: 'invoice',
+    amount: 500,
+    currency: 'usd',
+    status: 'paid',
+    occurredAt: '2026-08-01T00:00:00Z',
+    source: 'stripe',
+    sourceLabel: 'Stripe',
+    sourceRef: 'in_RedSuiteUsd0001',
+    url: 'https://invoice.stripe.example/i/in_RedSuiteUsd0001',
+    description: 'Subscription update proration',
+    party: BETA,
+    scope: scope(FIXTURE_ORG, OWNER_A),
+  },
+  {
+    id: 'ch_RedSuiteJpy0001',
+    subtype: 'charge',
+    amount: 1500,
+    currency: 'jpy',
+    status: 'refunded',
+    occurredAt: '2026-07-31T00:01:00Z',
+    source: 'stripe',
+    sourceLabel: 'Stripe',
+    sourceRef: 'ch_RedSuiteJpy0001',
+    description: 'Invoice REDSUITE-0001 — refunded in full',
+    party: ACME,
+    scope: scope(FIXTURE_ORG, OWNER_A),
+  },
+  {
+    id: 'sub_RedSuite01Acme',
+    subtype: 'subscription',
+    amount: 400000,
+    currency: 'usd',
+    status: 'active',
+    occurredAt: '2026-07-31T00:00:00Z',
+    source: 'stripe',
+    sourceLabel: 'Stripe',
+    sourceRef: 'sub_RedSuite01Acme',
+    description: 'Platform tier, monthly, forty seats',
+    party: ACME,
+    scope: scope(FIXTURE_ORG, OWNER_A),
+  },
+];
+
+/**
+ * One row per connected source, including one that is broken and one that has
+ * never delivered — because a freshness strip that only ever says "ok" has never
+ * been looked at.
+ */
+export const FIXTURE_SOURCES: SourceFreshness[] = [
+  {
+    source: 'granola',
+    label: 'Granola',
+    documentCount: 4,
+    lastSyncedAt: '2026-08-07T06:00:00Z',
+    status: 'ok',
+  },
+  {
+    source: 'dropbox',
+    label: 'Dropbox',
+    documentCount: 1,
+    lastSyncedAt: '2026-08-02T06:00:00Z',
+    status: 'stale',
+    detail: 'Last sync was more than 26 hours ago.',
+  },
+  {
+    source: 'gdrive',
+    label: 'Google Drive',
+    documentCount: 1,
+    lastSyncedAt: '2026-08-06T07:30:00Z',
+    status: 'error',
+    detail: 'The vendor rejected this key (401). Reconnect Google Drive.',
+  },
+  {
+    source: 'stripe',
+    label: 'Stripe',
+    documentCount: 0,
+    lastSyncedAt: null,
+    status: 'never',
+    detail: 'Connected, but nothing has arrived yet.',
+  },
+];
+
+// ---------------------------------------------------------------------------
+//  a CorpusApi over the fixtures
+// ---------------------------------------------------------------------------
+
+export interface FixtureCorpusOptions {
+  documents?: SourceDocument[];
+  moneyEvents?: MoneyEvent[];
+  parties?: Party[];
+  sources?: SourceFreshness[];
+  /** Page size when the caller does not ask for one. Small, to exercise paging. */
+  defaultPageSize?: number;
+  /**
+   * The scope this "server" enforces. Omit to model a CORRECT server that
+   * scopes every read; set `leakScope` to model a broken one and prove the
+   * client-side guard catches what the server should have.
+   */
+  scope?: CorpusScope;
+  /** Return rows from every org, as an over-broad server would. */
+  leakScope?: boolean;
+  /** Record every query the composers made, for assertions about server-side filtering. */
+  onQuery?: (endpoint: string, query: unknown) => void;
+}
+
+function haystack(document: SourceDocument): string {
+  return [
+    document.title,
+    document.body,
+    ...document.sections.map((section) => section.text),
+    ...document.participants.map((party) => `${party.name} ${party.email ?? ''}`),
+    document.sourceLabel,
+  ]
+    .join(' ')
+    .toLowerCase();
+}
+
+function paginate<T>(rows: T[], page: number, pageSize: number, applied: string[]): CorpusPage<T> {
+  const start = (page - 1) * pageSize;
+  return {
+    count: rows.length,
+    next: start + pageSize < rows.length ? String(page + 1) : null,
+    previous: page > 1 ? String(page - 1) : null,
+    results: rows.slice(start, start + pageSize),
+    appliedFilters: applied,
+  };
+}
+
+/**
+ * A `CorpusApi` that behaves the way the tenant API is SUPPOSED to: it filters
+ * and pages server-side and reports which filters it applied. It is the "server"
+ * in the harness and in the tests, which is what makes both of them a fair test
+ * of a composer that must never filter in the browser.
+ */
+export function createFixtureCorpusApi(options: FixtureCorpusOptions = {}): CorpusApi {
+  const {
+    documents = FIXTURE_DOCUMENTS,
+    moneyEvents = FIXTURE_MONEY_EVENTS,
+    parties = FIXTURE_PARTIES,
+    sources = FIXTURE_SOURCES,
+    defaultPageSize = 5,
+    scope: serverScope,
+    leakScope = false,
+    onQuery,
+  } = options;
+
+  const inScope = <T extends { scope: CorpusScope }>(rows: T[]): T[] => {
+    if (leakScope || !serverScope) return rows;
+    return rows.filter(
+      (row) =>
+        row.scope.orgId === serverScope.orgId &&
+        (!serverScope.ownerSub || row.scope.ownerSub === serverScope.ownerSub),
+    );
+  };
+
+  return {
+    async listDocuments(query: DocumentQuery) {
+      onQuery?.('documents', query);
+      const applied: string[] = [];
+      let rows = inScope(documents);
+
+      if (query.source) {
+        applied.push('source');
+        rows = rows.filter((document) => document.source === query.source);
+      }
+      if (query.partyId) {
+        applied.push('partyId');
+        rows = rows.filter((document) =>
+          document.participants.some((party) => party.id === query.partyId),
+        );
+      }
+      if (query.occurredAfter) {
+        applied.push('occurredAfter');
+        rows = rows.filter((d) => (d.occurredAt ?? '') >= query.occurredAfter!);
+      }
+      if (query.occurredBefore) {
+        applied.push('occurredBefore');
+        rows = rows.filter((d) => (d.occurredAt ?? '') <= query.occurredBefore!);
+      }
+      if (query.search) {
+        applied.push('search');
+        const needles = query.search.toLowerCase().split(/\s+/).filter(Boolean);
+        rows = rows.filter((document) => {
+          const text = haystack(document);
+          return needles.some((needle) => text.includes(needle));
+        });
+      }
+
+      rows = [...rows].sort((a, b) => (b.occurredAt ?? '').localeCompare(a.occurredAt ?? ''));
+      return paginate(rows, query.page ?? 1, query.pageSize ?? defaultPageSize, applied);
+    },
+
+    async getDocument(id: string) {
+      const found = inScope(documents).find((document) => document.id === id);
+      if (!found) {
+        // A row outside the caller's scope is ABSENT, not forbidden — same
+        // convention as the tenant API, where a cross-scope id is a 404.
+        const error = new Error('No such document.') as Error & { status?: number };
+        error.status = 404;
+        throw error;
+      }
+      return found;
+    },
+
+    async listParties(query = {}) {
+      onQuery?.('parties', query);
+      let rows = inScope(parties);
+      const applied: string[] = [];
+      if (query.search) {
+        applied.push('search');
+        const needle = query.search.toLowerCase();
+        rows = rows.filter((party) => `${party.name} ${party.email ?? ''}`.toLowerCase().includes(needle));
+      }
+      return paginate(rows, query.page ?? 1, query.pageSize ?? 50, applied);
+    },
+
+    async listMoneyEvents(query = {}) {
+      onQuery?.('money', query);
+      let rows = inScope(moneyEvents);
+      const applied: string[] = [];
+      if (query.partyId) {
+        applied.push('partyId');
+        rows = rows.filter((event) => event.party?.id === query.partyId);
+      }
+      if (query.search) {
+        applied.push('search');
+        const needles = query.search.toLowerCase().split(/\s+/).filter(Boolean);
+        rows = rows.filter((event) => {
+          const text = `${event.subtype} ${event.status} ${event.description ?? ''} ${event.party?.name ?? ''}`.toLowerCase();
+          return needles.some((needle) => text.includes(needle));
+        });
+      }
+      return paginate(rows, query.page ?? 1, query.pageSize ?? 20, applied);
+    },
+
+    async listSources() {
+      return sources;
+    },
+  };
+}
+
+/**
+ * A `CorpusLlm` that answers WITHOUT a provider, by quoting the documents it was
+ * handed and citing every one it quoted.
+ *
+ * It exists so the retrieval, citation-resolution and scope machinery can be
+ * driven end to end — in vitest and in a browser — with no API key. It reports
+ * `live: false` from `describe()`, and every surface renders that, so a run
+ * powered by this can never be mistaken on screen for a run powered by a model.
+ */
+export function createFixtureLlm(): import('./types').CorpusLlm {
+  return {
+    describe: () => ({ provider: 'fixture', model: 'fixture-echo', live: false }),
+    async answer(input) {
+      if (input.documents.length === 0) {
+        return { answer: '', citations: [], unanswerable: true };
+      }
+      const lines = input.documents.map((document) => {
+        const first = document.text.split('\n').find((line) => line.trim()) ?? document.title;
+        return `- ${document.title} (${document.source}): ${first.trim().slice(0, 180)}`;
+      });
+      const heading =
+        input.mode === 'generate'
+          ? `Draft assembled from ${input.documents.length} record(s):`
+          : `From ${input.documents.length} record(s) in your corpus:`;
+      return {
+        answer: [heading, ...lines].join('\n'),
+        citations: input.documents.map((document) => ({
+          documentId: document.id,
+          quote: document.text.slice(0, 120).trim(),
+        })),
+        unanswerable: false,
+      };
+    },
+  };
+}

package/src/corpus/index.ts

@@ -0,0 +1,79 @@
+/**
+ * The corpus layer (bd startsim-768w.38.6 Library, startsim-768w.38.7 Ask).
+ *
+ * Browser-safe: nothing reachable from here imports a provider client. The one
+ * module that does — `./llm` — is published separately as
+ * `@startsimpli/integrations/corpus-llm` and is server-only.
+ */
+export type {
+  AnswerDraft,
+  AnswerRequest,
+  AskMode,
+  AskRequest,
+  AskResult,
+  AskStatus,
+  Citation,
+  CorpusApi,
+  CorpusAskApi,
+  CorpusLlm,
+  CorpusPage,
+  CorpusScope,
+  DocumentQuery,
+  DocumentSection,
+  LlmDescription,
+  MoneyEvent,
+  Party,
+  PartyRef,
+  PromptDocument,
+  RetrievedDocument,
+  SourceDocument,
+  SourceFreshness,
+  SourceKey,
+} from './types';
+
+export {
+  DEFAULT_TYPE_KEYS,
+  moneyEventAsDocument,
+  scopeOf,
+  toMoneyEvent,
+  toParty,
+  toPartyRef,
+  toSections,
+  toSourceDocument,
+} from './entities';
+export type { CorpusTypeKeys, TenantEntity } from './entities';
+
+export {
+  enforceScope,
+  isInScope,
+  rankDocuments,
+  retrieveForQuestion,
+  snippetFor,
+  tokenize,
+} from './retrieval';
+export type { RetrieveOptions, ScopeFilterResult } from './retrieval';
+
+export {
+  answerSystemPrompt,
+  askCorpus,
+  buildAnswerRequest,
+  documentText,
+  renderAnswerPrompt,
+  resolveCitations,
+} from './ask';
+export type { AskCorpusOptions } from './ask';
+
+export { createCorpusApi } from './client';
+export type { CorpusHttp, CreateCorpusApiOptions } from './client';
+
+export {
+  createFixtureCorpusApi,
+  createFixtureLlm,
+  FIXTURE_DOCUMENTS,
+  FIXTURE_MONEY_EVENTS,
+  FIXTURE_ORG,
+  FIXTURE_OTHER_ORG,
+  FIXTURE_PARTIES,
+  FIXTURE_SOURCES,
+} from './fixtures';
+export type { FixtureCorpusOptions } from './fixtures';