@startsimpli/integrations 0.2.25 → 0.2.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.25",
+  "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();
+  });
+});