@startsimpli/integrations 0.2.26 → 0.2.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "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",

package/src/__tests__/corpus-document-lookup.test.tsx

@@ -0,0 +1,319 @@
+/**
+ * OPENING ONE RECORD (bd startsim-4s4um RED / startsim-2lt8y GREEN).
+ *
+ * REPORTED, with a live URL:
+ * `https://tandem.ai.startsimpli.com/library?doc=5ab48b58-8573-4114-b408-215dd0eaf5d7`
+ * renders no document.
+ *
+ * WHAT THE TENANT ACTUALLY DOES, read out of
+ * `start-simpli-api/tenant-starter/apps/api/{views,filters}.py` @ origin/main
+ * rather than assumed:
+ *
+ *   - `/api/v1/entities/<id>/` is a real DRF detail route. It answers the ONE
+ *     row, or 404 when the row is absent for this reader — the read gate makes a
+ *     forbidden row ABSENT rather than refused, deliberately.
+ *   - `/api/v1/entities/` applies `?type=` plus a fixed vocabulary
+ *     (`search`, `source`, `party`, `occurred_after`, `occurred_before`,
+ *     `related_*`, `order`) and `attr.*`. `_note_unknown` sweeps EVERY OTHER
+ *     KEY into `ignored_filters` and returns the page unnarrowed. `id` is not in
+ *     that vocabulary, which is why `?id=<uuid>` comes back with count 180.
+ *
+ * SO THE FAKE BELOW IGNORES UNKNOWN PARAMETERS RATHER THAN ERRORING ON THEM,
+ * and that is the whole point of writing a new one instead of reaching for
+ * `createFixtureCorpusHttp`: that fixture applies `?search=` when a backend is
+ * named and never reports `ignored_filters`, so a lookup expressed as a filter
+ * would come back plausibly narrowed there. A fake that answers an unsupported
+ * filter with `[]` — or with a filtered page — makes this suite green while the
+ * deployed Library stays blank, which is the exact trap this bead names.
+ *
+ * WHAT IS NOT THE BUG, established before any of this was written. The DEPLOYED
+ * bundle on tandem.ai.startsimpli.com already asks the detail route:
+ *
+ *     getDocument(e){let[a,r]=await Promise.all([
+ *       t.get(`${m}/${encodeURIComponent(e)}`),f()]);...}
+ *
+ * and that slash-less path resolves — `curl` returns 401 with
+ * `allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS`, the detail route's own verb
+ * set, not a redirect and not the list's. The request shape is right. What is
+ * missing is everything that happens when it does not come back: the client
+ * accepts whatever it is handed without checking it is the record it asked for,
+ * and the composer turns every failure into an empty screen.
+ */
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+
+import { LibraryPage } from '../components/pages/LibraryPage';
+import { createCorpusApi } from '../corpus/client';
+import type { CorpusHttp } from '../corpus/client';
+import type { TenantEntity } from '../corpus/entities';
+import type { CorpusScope } from '../corpus/types';
+
+const SCOPE: CorpusScope = { orgId: 'org_tandem' };
+
+/** The record the user deep-linked, live, when they reported this. */
+const OPENED = '5ab48b58-8573-4114-b408-215dd0eaf5d7';
+/** A well-formed id for a row that is simply not there. */
+const ABSENT = '00000000-0000-4000-8000-000000000000';
+
+function document(id: string, title: string, index: number): TenantEntity {
+  return {
+    id,
+    entity_type: 'source_document',
+    external_id: `granola:${id}`,
+    name: title,
+    org_id: SCOPE.orgId,
+    created_at: `2026-08-${String((index % 27) + 1).padStart(2, '0')}T10:00:00Z`,
+    data: {
+      source: 'granola',
+      title,
+      summary: `Summary of ${title}.`,
+      occurred_at: `2026-08-${String((index % 27) + 1).padStart(2, '0')}T09:00:00Z`,
+    },
+  };
+}
+
+/**
+ * A corpus the size of the reported one, with the deep-linked record buried
+ * where the composer's on-page shortcut cannot reach it.
+ *
+ * THE POSITION MATTERS. The record is 100 rows in, so page one does not contain
+ * it and `documents.find(...)` misses — which is precisely the state the
+ * reported URL lands in and the only state where the lookup is exercised at all.
+ */
+const CORPUS: TenantEntity[] = Array.from({ length: 180 }, (_, index) =>
+  index === 100
+    ? document(OPENED, 'Tandem <> Obwb quarterly review', index)
+    : document(`doc-${index}`, `Record ${index}`, index),
+);
+
+/** Parameters this tenant recognises on `/entities/`. Everything else is ignored. */
+const HONOURED = new Set([
+  'search', 'source', 'party', 'occurred_after', 'occurred_before',
+  'related_to', 'related_via', 'related_direction', 'related_depth', 'order',
+]);
+const RESERVED = new Set(['page', 'page_size', 'format', 'type']);
+
+interface Recorded {
+  path: string;
+  params: Record<string, unknown>;
+}
+
+/**
+ * The tenant, as the tenant is.
+ *
+ * `detailStatus` stands in for the read gate and the session: the tenant answers
+ * an absent row with 404 and an expired bearer with 401, and those are different
+ * facts that must not collapse into the same screen.
+ */
+function tenantHttp(options: {
+  entities?: TenantEntity[];
+  pageSize?: number;
+  detailStatus?: number;
+} = {}) {
+  const rows = options.entities ?? CORPUS;
+  const pageSize = options.pageSize ?? 20;
+  const requests: Recorded[] = [];
+
+  const http: CorpusHttp = {
+    async get<T>(path: string, init?: { params?: Record<string, unknown> }): Promise<T> {
+      const params = init?.params ?? {};
+      requests.push({ path, params });
+
+      if (path.includes('relationships')) {
+        return { count: 0, next: null, previous: null, results: [] } as T;
+      }
+      if (path.includes('connections')) {
+        return { count: 0, next: null, previous: null, results: [] } as T;
+      }
+      if (!path.includes('entities')) {
+        throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
+      }
+
+      // BOTH SPELLINGS OF THE DETAIL ROUTE, because both were measured to
+      // resolve on the live tenant. A fake that insisted on the trailing slash
+      // would manufacture evidence for a path change the wire does not ask for.
+      const detail = /entities\/([^/?]+)\/?$/.exec(path)?.[1];
+      if (detail) {
+        if (options.detailStatus) {
+          throw Object.assign(new Error(`${path} responded ${options.detailStatus}`), {
+            status: options.detailStatus,
+          });
+        }
+        const found = rows.find((row) => String(row.id) === decodeURIComponent(detail));
+        // ABSENT, NOT REFUSED — `readable_types_q` / `readable_rows_q` narrow the
+        // queryset, so a row this reader may not see 404s exactly like one that
+        // was never written.
+        if (!found) throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
+        return found as T;
+      }
+
+      // The LIST. `?type=` narrows; every other key is swept into
+      // `ignored_filters` and the page comes back exactly as wide as it was.
+      const type = params.type ? String(params.type) : '';
+      const matching = type ? rows.filter((row) => row.entity_type === type) : rows;
+      const size = Number(params.page_size ?? pageSize) || pageSize;
+      const page = Number(params.page ?? 1) || 1;
+      const start = (page - 1) * size;
+      const applied: string[] = [];
+      const ignored: string[] = [];
+      for (const key of Object.keys(params)) {
+        if (RESERVED.has(key)) continue;
+        (HONOURED.has(key) ? applied : ignored).push(key);
+      }
+      return {
+        count: matching.length,
+        next: start + size < matching.length ? `?page=${page + 1}` : null,
+        previous: page > 1 ? `?page=${page - 1}` : null,
+        results: matching.slice(start, start + size),
+        applied_filters: applied,
+        ignored_filters: ignored,
+      } as T;
+    },
+  };
+
+  return { http, requests };
+}
+
+/**
+ * The tenant as it answers a lookup that was expressed as a FILTER.
+ *
+ * `GET /api/v1/entities/?id=5ab48b58-…` was checked against prod for this epic
+ * and returned 200 with count 180 — the whole corpus, unnarrowed, because `id`
+ * is not a filter this API has. Any client that reaches the entity list instead
+ * of the detail route gets THIS: a page envelope where it expected a row.
+ *
+ * The contract under test is that such a response is a FAILURE, not a document.
+ * Mapping it produces a record with no id and no title that renders as a blank
+ * panel — an arbitrary answer wearing a real record's clothes, which is worse
+ * than an error because nobody can tell it is wrong.
+ */
+function pageEnvelopeHttp() {
+  const { requests } = tenantHttp();
+  const http: CorpusHttp = {
+    async get<T>(path: string, init?: { params?: Record<string, unknown> }): Promise<T> {
+      requests.push({ path, params: init?.params ?? {} });
+      if (path.includes('entities')) {
+        return {
+          count: CORPUS.length,
+          next: '?page=2',
+          previous: null,
+          results: CORPUS.slice(0, 20),
+          ignored_filters: ['id'],
+        } as T;
+      }
+      return { count: 0, next: null, previous: null, results: [] } as T;
+    },
+  };
+  return { http, requests };
+}
+
+function corpusOver(http: CorpusHttp) {
+  return createCorpusApi({ http, scope: SCOPE, supportedFilters: [] });
+}
+
+// ---------------------------------------------------------------------------
+//  the client
+// ---------------------------------------------------------------------------
+
+describe('a document lookup returns THAT document', () => {
+  it('answers with the record that was asked for, not the first of many', async () => {
+    const api = corpusOver(tenantHttp().http);
+    const found = await api.getDocument(OPENED);
+    expect(found.id).toBe(OPENED);
+    expect(found.title).toBe('Tandem <> Obwb quarterly review');
+  });
+
+  it('asks the DETAIL route, and never expresses the id as a filter', async () => {
+    // The distinction the whole bead turns on. `?id=` is swept into
+    // `ignored_filters` by this API, so a lookup spelled that way is handed the
+    // unfiltered corpus and has to guess.
+    const { http, requests } = tenantHttp();
+    await corpusOver(http).getDocument(OPENED);
+
+    const lookup = requests.find((request) => request.path.includes(OPENED));
+    expect(lookup, 'the id belongs in the PATH').toBeTruthy();
+    expect(
+      requests.every((request) => !('id' in request.params)),
+      'no request may carry the id as a query parameter',
+    ).toBe(true);
+  });
+
+  it('refuses a page envelope instead of fabricating a record from it', async () => {
+    // A response that is a LIST is not the record, whatever produced it — an
+    // ignored `?id=`, a proxy that dropped the path segment, a deployment whose
+    // detail route is a list. Mapping it yields id `undefined` and the title
+    // "Untitled unknown record": a blank panel that claims to be the document.
+    const api = corpusOver(pageEnvelopeHttp().http);
+    await expect(api.getDocument(OPENED)).rejects.toMatchObject({ status: 404 });
+  });
+
+  it('surfaces a record that is genuinely absent as not-found', async () => {
+    const api = corpusOver(tenantHttp().http);
+    await expect(api.getDocument(ABSENT)).rejects.toMatchObject({ status: 404 });
+  });
+
+  it('never answers one id with a different record', async () => {
+    const api = corpusOver(tenantHttp().http);
+    const found = await api.getDocument('doc-3');
+    expect(found.id).toBe('doc-3');
+    await expect(api.getDocument(ABSENT)).rejects.toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  the screen
+// ---------------------------------------------------------------------------
+
+describe('the Library opens the record it was deep-linked to', () => {
+  it('renders a record that is not on the first page', async () => {
+    const api = corpusOver(tenantHttp().http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={OPENED} />);
+
+    expect(
+      await screen.findByRole('region', { name: 'Record detail' }),
+    ).toHaveTextContent('Tandem <> Obwb quarterly review');
+  });
+
+  it('SAYS SO when the record cannot be found, instead of rendering nothing', async () => {
+    // THE REPORTED SYMPTOM. `?doc=<id>` in the address bar, a list on screen,
+    // and no record and no explanation — the composer swallowed the failure into
+    // `setSelected(null)`. A screen that asked for a record and shows neither the
+    // record nor a reason is the one outcome the user cannot act on.
+    const api = corpusOver(tenantHttp().http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={ABSENT} />);
+
+    const notice = await screen.findByRole('region', { name: 'Record' });
+    expect(notice).toHaveTextContent(/could not be found/i);
+    expect(notice).toHaveTextContent(new RegExp(ABSENT));
+  });
+
+  it('calls an expired session an expired session, not a missing record', async () => {
+    // "Sign in again" and "that record is gone" send the reader to different
+    // places, and only one of them is true at a time.
+    const api = corpusOver(tenantHttp({ detailStatus: 401 }).http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={OPENED} />);
+
+    const notice = await screen.findByRole('region', { name: 'Record' });
+    expect(notice).toHaveTextContent(/session has expired/i);
+    expect(notice).not.toHaveTextContent(/could not be found/i);
+  });
+
+  it('calls a refusal a refusal', async () => {
+    const api = corpusOver(tenantHttp({ detailStatus: 403 }).http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={OPENED} />);
+
+    expect(await screen.findByRole('region', { name: 'Record' })).toHaveTextContent(
+      /do not have access/i,
+    );
+  });
+
+  it('lets the reader dismiss the notice and get back to the list', async () => {
+    // Without this the `?doc=` in the URL is a dead end: the panel cannot be
+    // closed because there is no panel, only a message.
+    const api = corpusOver(tenantHttp().http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={ABSENT} />);
+
+    const notice = await screen.findByRole('region', { name: 'Record' });
+    expect(within(notice).getByRole('button', { name: /close/i })).toBeInTheDocument();
+  });
+});

package/src/components/pages/LibraryPage.tsx

@@ -85,6 +85,29 @@ function readFailureMessage(err: unknown): string {
   return (err as { message?: string })?.message || 'Could not load the library.';
 }
 
+/**
+ * Why the record the screen was asked to open is not on the screen
+ * (bd startsim-2lt8y).
+ *
+ * FOUR ANSWERS, NOT ONE, and the branch is the point: "sign in again", "you may
+ * not see this", "that record is not here" and "something went wrong" send the
+ * reader to four different places, and only one of them is true at a time.
+ * Calling an expired session a missing record is a different lie from the one
+ * this bead is fixing, not a smaller version of it.
+ *
+ * The id is NAMED because it came out of the address bar. A citation or a
+ * bookmark that no longer resolves is worth being able to quote back to
+ * somebody, and "a record" is not quotable.
+ */
+function openFailureMessage(err: unknown, id: string): string {
+  const status = (err as { status?: number })?.status;
+  if (status === 404) {
+    return `That record could not be found in this workspace (${id}). It may have been removed, or it may not be one you can see.`;
+  }
+  if (status === 401 || status === 403) return readFailureMessage(err);
+  return (err as { message?: string })?.message || `That record could not be opened (${id}).`;
+}
+
 function formatDate(value: string | null | undefined): string {
   if (!value) return 'No date';
   const at = Date.parse(value);
@@ -160,6 +183,13 @@ export function LibraryPage({
   const [parties, setParties] = React.useState<Party[]>([]);
   const [selectedId, setSelectedId] = React.useState<string | null>(initialDocumentId ?? null);
   const [selected, setSelected] = React.useState<SourceDocument | null>(null);
+  /**
+   * Why the open record is not open. Held separately from `loadError`, which is
+   * about the LIST: a Library that loaded fine and a citation that no longer
+   * resolves are different facts, and blanking the list for the second one would
+   * be a worse answer than the silence this replaces.
+   */
+  const [selectError, setSelectError] = React.useState('');
   const [loading, setLoading] = React.useState(true);
   const [loadError, setLoadError] = React.useState('');
   /**
@@ -216,18 +246,22 @@ export function LibraryPage({
   }, [api, filters, scope]);
 
   React.useEffect(() => {
-    if (!selectedId) { setSelected(null); return; }
+    if (!selectedId) { setSelected(null); setSelectError(''); return; }
     let live = true;
     void (async () => {
       // Prefer the row already on screen; fall back to a fetch so a citation
       // deep-link opens a record that is not on the current page.
       const onPage = documents.find((document) => document.id === selectedId);
-      if (onPage) { setSelected(onPage); return; }
+      if (onPage) { setSelected(onPage); setSelectError(''); return; }
       try {
         const fetched = await api.getDocument(selectedId);
-        if (live) setSelected(fetched);
-      } catch {
-        if (live) setSelected(null);
+        if (live) { setSelected(fetched); setSelectError(''); }
+      } catch (err) {
+        // THE REPORTED BUG (bd startsim-4s4um). This was `setSelected(null)` and
+        // nothing else, so `?doc=<id>` in the address bar produced a Library
+        // with no record and no explanation — the one outcome a reader cannot
+        // act on, and indistinguishable from a page that simply ignored them.
+        if (live) { setSelected(null); setSelectError(openFailureMessage(err, selectedId)); }
       }
     })();
     return () => { live = false; };
@@ -235,6 +269,7 @@ export function LibraryPage({
 
   const select = React.useCallback((id: string | null) => {
     setSelectedId(id);
+    if (!id) setSelectError('');
     onSelectDocument?.(id);
   }, [onSelectDocument]);
 
@@ -459,6 +494,16 @@ export function LibraryPage({
           onFilterByParty={(partyId) => update({ partyId })}
         />
       ) : null}
+
+      {/* Asked for, and not shown — said out loud rather than left blank. */}
+      {!selected && selectError ? (
+        <section className={cn.card} aria-label="Record">
+          <div className="flex items-start justify-between gap-4">
+            <p className={cn.warning} role="alert">{selectError}</p>
+            <button type="button" className={cn.button} onClick={() => select(null)}>Close</button>
+          </div>
+        </section>
+      ) : null}
     </div>
   );
 }

package/src/corpus/client.ts

@@ -320,6 +320,38 @@ function appliedFilters(
   return requested.filter((key) => supported.includes(key));
 }
 
+/**
+ * Is this response the ROW that was asked for, or something else wearing a 200?
+ *
+ * Three things are refused, and each of them has been seen answering a
+ * single-record request somewhere: a DRF page (what an ignored `?id=` returns —
+ * verified on the live tenant, 200 with count 180), a body with no id at all,
+ * and a row whose id is somebody else's.
+ */
+function isRecord(value: unknown, id: string): value is TenantEntity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  // A page is the shape a LIST answers with. It is never one record, whatever
+  // its count happens to be.
+  if (Array.isArray((value as { results?: unknown }).results)) return false;
+  const own = (value as TenantEntity).id;
+  if (own === undefined || own === null || String(own).trim() === '') return false;
+  // Case-insensitively, because a UUID has two legal spellings and the server
+  // answers in its own. Anything else different is a DIFFERENT RECORD, which is
+  // the entire reason this function exists.
+  return String(own).trim().toLowerCase() === String(id).trim().toLowerCase();
+}
+
+/**
+ * The tenant's own word for a row that is not there.
+ *
+ * 404 and not a bespoke error, because the tenant's read gate makes a row this
+ * principal may not see ABSENT rather than refused — so callers get one status
+ * to branch on, and "not found" is already the honest word for both.
+ */
+function notFound(id: string): Error & { status: number } {
+  return Object.assign(new Error(`No record ${id} in this workspace.`), { status: 404 });
+}
+
 export function createCorpusApi(
   options: CreateCorpusApiOptions,
 ): CorpusApi & CommitmentApi & ExtractionRunStore {
@@ -423,11 +455,34 @@ export function createCorpusApi(
       };
     },
 
+    /**
+     * ONE record, by the DETAIL ROUTE — never by a filter (bd startsim-2lt8y).
+     *
+     * `/api/v1/entities/<id>/` is a real route on the tenant and it answers the
+     * one row. The entity LIST has no `id` filter: `EntityQuery._note_unknown`
+     * sweeps every unrecognised parameter into `ignored_filters` and returns the
+     * page exactly as wide as it was, so `?id=<uuid>` comes back 200 with the
+     * whole corpus. A lookup spelled that way cannot fail — it just answers with
+     * somebody else's record.
+     *
+     * WHICH IS WHY THE RESPONSE IS CHECKED. Asking the right route is not the
+     * same as being answered by it: a proxy that drops the path segment, a
+     * deployment whose detail route lists, an `?id=` that got ignored upstream —
+     * all hand back a DRF page where a row was expected, and `toSourceDocument`
+     * will map it without complaint into a document with the id `undefined` and
+     * the title "Untitled unknown record". That renders as a blank panel that
+     * claims to be the record, which is worse than an error because nobody
+     * downstream can tell it is wrong. So a response that is not the row that
+     * was asked for is a 404, reported the same way the tenant reports an absent
+     * row — the read gate makes a forbidden row ABSENT rather than refused, so
+     * "not found" is already the honest word for both.
+     */
     async getDocument(id) {
       const [entity, byRecord] = await Promise.all([
         http.get<TenantEntity>(`${entities}/${encodeURIComponent(id)}`),
         participantGraph(),
       ]);
+      if (!isRecord(entity, id)) throw notFound(id);
       return toSourceDocument(entity, scope, sourceLabels, byRecord.get(String(entity.id)) ?? []);
     },