@startsimpli/integrations 0.1.3 → 0.1.5

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./types": "./src/types/index.ts",
-    "./api": "./src/api/index.ts"
+    "./api": "./src/api/index.ts",
+    "./corpus": "./src/corpus/index.ts",
+    "./corpus-llm": "./src/corpus/llm.ts"
   },
   "files": [
     "src",
@@ -19,7 +21,8 @@
   "dependencies": {},
   "peerDependencies": {
     "react": ">=18.0.0",
-    "@tanstack/react-query": ">=5.0.0"
+    "@tanstack/react-query": ">=5.0.0",
+    "@startsimpli/llm": ">=0.4.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -27,6 +30,9 @@
     },
     "@tanstack/react-query": {
       "optional": true
+    },
+    "@startsimpli/llm": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -41,7 +47,8 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^6.0.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@startsimpli/llm": "0.4.14"
   },
   "scripts": {
     "type-check": "tsc --noEmit",

package/src/__tests__/connections.test.tsx

@@ -15,7 +15,7 @@
  * theme classNames.
  */
 import { describe, expect, it, vi } from 'vitest';
-import { render, screen, waitFor } from '@testing-library/react';
+import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 import { CredentialSchemaForm, schemaFields } from '../components/CredentialSchemaForm';
@@ -203,6 +203,7 @@ function stubApi(overrides: Partial<ConnectionsApi> = {}): ConnectionsApi {
       run_status: 'running', external_ref: null, output: {}, error: '',
     }),
     connectionRuns: vi.fn().mockResolvedValue({ results: [] }),
+    updateConnection: vi.fn().mockResolvedValue(CONNECTED.results[0]),
     ...overrides,
   } as ConnectionsApi;
 }
@@ -268,6 +269,120 @@ describe('ConnectionsPage — injected, not contextual', () => {
   });
 });
 
+// --------------------------------------------------------------------------
+//  the capability choice (bd startsim-768w.22.22)
+// --------------------------------------------------------------------------
+
+/**
+ * WHAT WENT WRONG ON PRODUCTION. An admin connected Granola on the `tandem`
+ * foundry through this very page. The card went green — `check()` really
+ * reached the vendor — and `capabilities_enabled` was stored as `[]`. With an
+ * empty list NO capability is enabled: not `poll`, not `action`, not
+ * `webhook_in`. So `poll_is_enabled()` answered false, no scheduled ingest leg
+ * was ever created, and the card sat there connected and completely inert.
+ *
+ * The server was not the liar. `POST /connections/` has accepted
+ * `capabilities_enabled[]` since the endpoint was designed, and
+ * `PATCH /connections/<id>/` has accepted edits to it and created the poll leg
+ * on the spot. THIS PAGE never sent either one — there was no control for it
+ * anywhere, at connect time or after — so the server received nothing, wrote
+ * nothing, and the admin had no way to say what they wanted.
+ *
+ * Both halves are asserted here: the choice is offered when connecting, and it
+ * stays changeable afterwards, because the connections that already exist
+ * cannot be fixed by anything the connect form does.
+ */
+describe('capabilities are the admin’s choice, and the page has to ask', () => {
+  /** The capability picker inside ONE card. Both surfaces render one. */
+  function picker(scope: HTMLElement, which: 'catalog' | 'connection') {
+    const group = scope.querySelector<HTMLElement>(`[data-capabilities="${which}"]`);
+    if (!group) throw new Error(`no ${which} capability picker rendered`);
+    return within(group);
+  }
+
+  async function openConnectForm() {
+    const api = stubApi();
+    const { container } = render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    // The catalog's available row. The unavailable one offers no button at all.
+    await userEvent.click(await screen.findByRole('button', { name: /^connect$/i }));
+    return { api, container };
+  }
+
+  it('offers every capability the connector declares, from the catalog row', async () => {
+    const { container } = await openConnectForm();
+    // The n8n fixture declares action + poll. Both are offered; nothing else is.
+    const boxes = picker(container, 'catalog').getAllByRole('checkbox');
+    expect(boxes.map((b) => b.getAttribute('value')).sort()).toEqual(['action', 'poll']);
+    for (const box of boxes) expect(box).toBeChecked();
+  });
+
+  it('SENDS the capability list on connect instead of leaving the card inert', async () => {
+    const { api } = await openConnectForm();
+    await userEvent.type(screen.getByLabelText(/Instance URL/i), 'https://n8n.example.com');
+    await userEvent.click(screen.getByRole('button', { name: /test and save/i }));
+
+    await waitFor(() => expect(api.connect).toHaveBeenCalled());
+    const sent = (api.connect as ReturnType<typeof vi.fn>).mock.calls[0][1];
+    expect(sent.capabilities_enabled).toEqual(['action', 'poll']);
+  });
+
+  it('honours an admin who unchecks one before saving', async () => {
+    const { api, container } = await openConnectForm();
+    await userEvent.type(screen.getByLabelText(/Instance URL/i), 'https://n8n.example.com');
+    await userEvent.click(picker(container, 'catalog').getByRole('checkbox', { name: /action/i }));
+    await userEvent.click(screen.getByRole('button', { name: /test and save/i }));
+
+    await waitFor(() => expect(api.connect).toHaveBeenCalled());
+    const sent = (api.connect as ReturnType<typeof vi.fn>).mock.calls[0][1];
+    expect(sent.capabilities_enabled).toEqual(['poll']);
+  });
+
+  it('will not let an admin save a connection that can do nothing', async () => {
+    const { container } = await openConnectForm();
+    await userEvent.type(screen.getByLabelText(/Instance URL/i), 'https://n8n.example.com');
+    for (const box of picker(container, 'catalog').getAllByRole('checkbox')) {
+      await userEvent.click(box);
+    }
+    // The server refuses an empty list with a 400 (bd startsim-768w.22.22);
+    // refusing it here means the admin finds out before a round trip.
+    expect(screen.getByRole('button', { name: /test and save/i })).toBeDisabled();
+  });
+
+  it('lets an admin turn a capability ON for a connection that already exists', async () => {
+    // THE UNBLOCK. The `tandem` Granola card is already there with an empty
+    // list; nothing the connect form does can reach it. `Ops n8n` here has only
+    // `action` enabled, and the connector declares `poll` too.
+    const api = stubApi();
+    const { container } = render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+
+    const on = picker(container, 'connection');
+    const poll = on.getByRole('checkbox', { name: /poll/i });
+    expect(poll).not.toBeChecked();
+    await userEvent.click(poll);
+    await userEvent.click(on.getByRole('button', { name: /save/i }));
+
+    await waitFor(() => expect(api.updateConnection).toHaveBeenCalledWith('acme', 'c1', {
+      capabilities_enabled: ['action', 'poll'],
+    }));
+  });
+
+  it('shows the capability state read-only when manage is false', async () => {
+    const api = stubApi({
+      connections: vi.fn().mockResolvedValue({
+        ...CONNECTED,
+        permissions: { view: true, manage: false, issue_tokens: false },
+      }),
+    });
+    const { container } = render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+
+    const on = picker(container, 'connection');
+    expect(on.queryByRole('button', { name: /save/i })).not.toBeInTheDocument();
+    for (const box of on.getAllByRole('checkbox')) expect(box).toBeDisabled();
+  });
+});
+
 describe('the catalog envelope, as the server actually ships it', () => {
   // REGRESSION. The first browser drive of this page died on
   // `(entry.credential_schema ?? []) is not iterable`, because these fixtures

package/src/__tests__/corpus-ask.test.ts

@@ -0,0 +1,279 @@
+/**
+ * The Ask pipeline: citations, batching, and the honesty rules
+ * (bd startsim-768w.38.7).
+ *
+ * THE THING THIS SUITE PROTECTS: "an answer he cannot trace is an answer he
+ * cannot trust with a contract". So the assertions are not about the answer
+ * text — a model writes that — they are about whether the surface can ever
+ * present an untraceable answer as a traceable one. Every dishonest rendering
+ * has a test that forbids it.
+ *
+ * Scope isolation has its own file (`corpus-scope.test.ts`) because it is a
+ * different failure with a different blast radius.
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+  askCorpus,
+  buildAnswerRequest,
+  documentText,
+  renderAnswerPrompt,
+  resolveCitations,
+} from '../corpus/ask';
+import {
+  createFixtureCorpusApi,
+  createFixtureLlm,
+  FIXTURE_DOCUMENTS,
+  FIXTURE_ORG,
+} from '../corpus/fixtures';
+import { rankDocuments } from '../corpus/retrieval';
+import type { AnswerDraft, AskRequest, CorpusLlm, RetrievedDocument } from '../corpus/types';
+
+const SCOPE = { orgId: FIXTURE_ORG };
+const ask = (question: string): AskRequest => ({ question, mode: 'ask', scope: SCOPE });
+
+/** A model that returns exactly what the test tells it to. */
+function scriptedLlm(draft: AnswerDraft, calls: unknown[] = []): CorpusLlm {
+  return {
+    describe: () => ({ provider: 'scripted', model: 'scripted-1', live: false }),
+    async answer(input) {
+      calls.push(input);
+      return draft;
+    },
+  };
+}
+
+function retrievedFor(question: string): RetrievedDocument[] {
+  const own = FIXTURE_DOCUMENTS.filter((document) => document.scope.orgId === FIXTURE_ORG);
+  return rankDocuments(own, question, { limit: 5 });
+}
+
+// ---------------------------------------------------------------------------
+
+describe('batching — N documents, ONE call', () => {
+  it('sends every retrieved document in a single request', async () => {
+    const calls: unknown[] = [];
+    const corpus = createFixtureCorpusApi({ scope: SCOPE });
+    const llm = scriptedLlm({ answer: 'ok', citations: [] }, calls);
+
+    await askCorpus(ask('Acme renewal rate and seats'), { corpus, llm });
+
+    expect(calls).toHaveLength(1);
+    const input = calls[0] as { documents: unknown[] };
+    expect(input.documents.length).toBeGreaterThan(1);
+  });
+
+  it('gives the model an id per document and repeats it in the prompt', () => {
+    const retrieved = retrievedFor('Acme renewal');
+    const request = buildAnswerRequest(ask('Acme renewal'), retrieved, 4000);
+    const prompt = renderAnswerPrompt(request);
+
+    for (const document of request.documents) {
+      // The echoed id is the whole citation mechanism. Without it in the prompt
+      // there is nothing the model could return that resolves to a record.
+      expect(prompt).toContain(`<document id="${document.id}">`);
+    }
+    expect(request.documents.map((d) => d.id)).toEqual(retrieved.map((r) => r.document.id));
+  });
+
+  it('carries the SOURCE into the prompt, so the model can say where it learned it', () => {
+    const retrieved = retrievedFor('Acme renewal contract');
+    const prompt = renderAnswerPrompt(buildAnswerRequest(ask('Acme renewal contract'), retrieved, 4000));
+    expect(prompt).toMatch(/source: (Granola|Dropbox|Google Drive|Stripe)/);
+  });
+
+  it('truncates a long document rather than dropping it from the batch', () => {
+    const long = {
+      ...FIXTURE_DOCUMENTS[0],
+      sections: [{ key: 'transcript', label: 'Transcript', text: 'x'.repeat(50_000) }],
+    };
+    const text = documentText(long, 500);
+    expect(text.length).toBeLessThan(700);
+    expect(text).toContain('[truncated]');
+  });
+});
+
+describe('citations resolve to records retrieval actually supplied', () => {
+  it('resolves a good citation to the record itself', () => {
+    const retrieved = retrievedFor('Acme renewal');
+    const id = retrieved[0].document.id;
+    const { citations, unresolved } = resolveCitations(
+      { citations: [{ documentId: id, quote: 'twelve months' }] },
+      retrieved,
+    );
+    expect(unresolved).toEqual([]);
+    expect(citations).toHaveLength(1);
+    expect(citations[0].document.id).toBe(id);
+    expect(citations[0].quote).toBe('twelve months');
+  });
+
+  it('drops an invented id and REPORTS it', () => {
+    const retrieved = retrievedFor('Acme renewal');
+    const { citations, unresolved } = resolveCitations(
+      { citations: [{ documentId: 'not_this_never_existed' }] },
+      retrieved,
+    );
+    expect(citations).toHaveLength(0);
+    // Swallowing this would render a clean answer over a hallucinated source.
+    expect(unresolved).toEqual(['not_this_never_existed']);
+  });
+
+  it('deduplicates a repeated citation', () => {
+    const retrieved = retrievedFor('Acme renewal');
+    const id = retrieved[0].document.id;
+    const { citations } = resolveCitations(
+      { citations: [{ documentId: id }, { documentId: id }] },
+      retrieved,
+    );
+    expect(citations).toHaveLength(1);
+  });
+
+  it('substitutes the record’s own text when the model returns no quote', () => {
+    const retrieved = retrievedFor('Acme renewal');
+    const { citations } = resolveCitations(
+      { citations: [{ documentId: retrieved[0].document.id }] },
+      retrieved,
+    );
+    expect(citations[0].quote.length).toBeGreaterThan(0);
+  });
+
+  it('accepts the snake_case spelling a model may emit', () => {
+    const retrieved = retrievedFor('Acme renewal');
+    const id = retrieved[0].document.id;
+    const { citations } = resolveCitations(
+      { citations: [{ document_id: id } as unknown as { documentId: string }] },
+      retrieved,
+    );
+    expect(citations).toHaveLength(1);
+  });
+});
+
+describe('the surface can never present an untraceable answer as traceable', () => {
+  const corpus = () => createFixtureCorpusApi({ scope: SCOPE });
+
+  it('marks a cited answer as answered', async () => {
+    const result = await askCorpus(ask('Acme renewal rate'), {
+      corpus: corpus(),
+      llm: createFixtureLlm(),
+    });
+    expect(result.status).toBe('answered');
+    expect(result.citations.length).toBeGreaterThan(0);
+  });
+
+  it('marks an answer with NO resolvable citation as uncited, not answered', async () => {
+    const result = await askCorpus(ask('Acme renewal rate'), {
+      corpus: corpus(),
+      llm: scriptedLlm({ answer: 'You agreed four thousand a month.', citations: [] }),
+    });
+    // The text is still returned — hiding it would be its own kind of lying —
+    // but the status is what the UI keys its warning off.
+    expect(result.status).toBe('uncited');
+    expect(result.answer).toContain('four thousand');
+    expect(result.citations).toHaveLength(0);
+  });
+
+  it('marks an answer whose every citation was invented as uncited, and names them', async () => {
+    const result = await askCorpus(ask('Acme renewal rate'), {
+      corpus: corpus(),
+      llm: scriptedLlm({
+        answer: 'You agreed four thousand a month.',
+        citations: [{ documentId: 'doc_that_does_not_exist' }],
+      }),
+    });
+    expect(result.status).toBe('uncited');
+    expect(result.unresolvedCitations).toEqual(['doc_that_does_not_exist']);
+  });
+
+  it('reports no_evidence when the corpus has nothing, without calling the model', async () => {
+    const calls: unknown[] = [];
+    const result = await askCorpus(ask('zzzznothingmatchesthis'), {
+      corpus: corpus(),
+      llm: scriptedLlm({ answer: 'I could make something up.', citations: [] }, calls),
+    });
+    expect(result.status).toBe('no_evidence');
+    // Not calling the model at all is the only way to guarantee it cannot
+    // improvise an answer over an empty document list.
+    expect(calls).toHaveLength(0);
+  });
+
+  it('names the provider that actually answered, and whether it was live', async () => {
+    const result = await askCorpus(ask('Acme renewal'), {
+      corpus: corpus(),
+      llm: createFixtureLlm(),
+    });
+    expect(result.provider.live).toBe(false);
+    expect(result.provider.provider).toBe('fixture');
+  });
+
+  it('carries freshness onto the answer so a stale corpus is visible', async () => {
+    const result = await askCorpus(ask('Acme renewal'), {
+      corpus: corpus(),
+      llm: createFixtureLlm(),
+    });
+    expect(result.freshness?.some((source) => source.status !== 'ok')).toBe(true);
+  });
+});
+
+describe('retrieval spans documents and money, and stays generic', () => {
+  it('retrieves a Stripe money event alongside meeting notes', async () => {
+    const calls: unknown[] = [];
+    await askCorpus(ask('Acme Robotics charge refunded'), {
+      corpus: createFixtureCorpusApi({ scope: SCOPE }),
+      llm: scriptedLlm({ answer: 'ok', citations: [] }, calls),
+    });
+    const ids = (calls[0] as { documents: Array<{ id: string }> }).documents.map((d) => d.id);
+    // "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.
+    expect(ids).toContain('ch_RedSuiteJpy0001');
+  });
+
+  it('still answers when the tenant has NO money connector at all', async () => {
+    const corpus = createFixtureCorpusApi({ scope: SCOPE });
+    delete (corpus as { listMoneyEvents?: unknown }).listMoneyEvents;
+
+    const result = await askCorpus(ask('Acme renewal rate'), { corpus, llm: createFixtureLlm() });
+    expect(result.status).toBe('answered');
+  });
+
+  it('answers a Dropbox-only question with a Dropbox citation', async () => {
+    // The standing generic test: nothing in the pipeline may be better at
+    // meeting notes than at files.
+    const result = await askCorpus(ask('master services agreement seats cap'), {
+      corpus: createFixtureCorpusApi({ scope: SCOPE }),
+      llm: createFixtureLlm(),
+    });
+    expect(result.citations.some((citation) => citation.document.source === 'dropbox')).toBe(true);
+  });
+
+  it('survives a money endpoint that fails, rather than failing the whole answer', async () => {
+    const corpus = createFixtureCorpusApi({ scope: SCOPE });
+    corpus.listMoneyEvents = async () => { throw new Error('money service is down'); };
+
+    const result = await askCorpus(ask('Acme renewal rate'), { corpus, llm: createFixtureLlm() });
+    expect(result.status).toBe('answered');
+  });
+});
+
+describe('generate mode', () => {
+  it('asks the model for a draft and still requires citations', async () => {
+    const calls: unknown[] = [];
+    const result = await askCorpus(
+      {
+        question: 'Draft a renewal letter for Acme Robotics',
+        mode: 'generate',
+        scope: SCOPE,
+        instructions: 'Formal, one page',
+      },
+      { corpus: createFixtureCorpusApi({ scope: SCOPE }), llm: scriptedLlm({
+        answer: 'Dear Acme…',
+        citations: [{ documentId: 'dbx_9812f0', quote: 'twelve (12) months' }],
+      }, calls) },
+    );
+
+    const input = calls[0] as { mode: string; instructions?: string };
+    expect(input.mode).toBe('generate');
+    expect(input.instructions).toBe('Formal, one page');
+    expect(result.status).toBe('answered');
+    expect(result.citations[0].document.source).toBe('dropbox');
+  });
+});