@startsimpli/integrations 0.2.7 → 0.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.7",
+  "version": "0.2.11",
   "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-storage.test.ts

@@ -299,3 +299,100 @@ describe('the tenant’s filters are still not honoured, and are still not faked
     expect(page.count).toBe(FIXTURE_TENANT_DOCUMENTS.length);
   });
 });
+
+// ---------------------------------------------------------------------------
+//  the tracker's read, against the tenant's real filter vocabulary
+// ---------------------------------------------------------------------------
+
+describe('listCommitments speaks the tenant data API’s own filter language', () => {
+  function client(applied: string[] | undefined) {
+    const seen: Array<{ path: string; params: Record<string, unknown> }> = [];
+    const api = createCorpusApi({
+      http: {
+        async get<T>(path: string, options?: { params?: Record<string, unknown> }): Promise<T> {
+          seen.push({ path, params: options?.params ?? {} });
+          return {
+            count: 0, next: null, previous: null, results: [],
+            ...(applied ? { applied_filters: applied, ignored_filters: [] } : {}),
+          } as T;
+        },
+      },
+      scope: { orgId: 'tandem' },
+      supportedFilters: [],
+    });
+    return { api, seen };
+  }
+
+  it('sends status, owner, due window and order as attr.* parameters', async () => {
+    const { api, seen } = client(['attr.status__in']);
+    await api.listCommitments({
+      status: ['open', 'blocked'],
+      owner: 'Kate',
+      dueBefore: '2026-08-10T00:00:00.000Z',
+      changedAfter: '2026-08-03T00:00:00.000Z',
+      pageSize: 200,
+    });
+    expect(seen[0].params).toMatchObject({
+      type: 'commitment',
+      'attr.status__in': 'open,blocked',
+      'attr.owner_name__icontains': 'Kate',
+      'attr.due_at__lte': '2026-08-10T00:00:00.000Z',
+      'attr.last_seen_at__gte': '2026-08-03T00:00:00.000Z',
+      order: 'attr.due_at',
+      page_size: 200,
+    });
+  });
+
+  it('caps a text filter at the length the server documents', async () => {
+    const { api, seen } = client([]);
+    await api.listCommitments({ owner: 'x'.repeat(900), search: 'y'.repeat(900) });
+    expect(String(seen[0].params['attr.owner_name__icontains'])).toHaveLength(500);
+    expect(String(seen[0].params.search)).toHaveLength(500);
+  });
+
+  it('caps page size at the server’s maximum rather than asking for more', async () => {
+    const { api, seen } = client([]);
+    await api.listCommitments({ pageSize: 5000 });
+    expect(seen[0].params.page_size).toBe(200);
+  });
+
+  it('believes the SERVER about what it filtered, not a hardcoded list', async () => {
+    // The static `supportedFilters` says nothing is supported. The server says
+    // it applied status. The server wins — otherwise the screen keeps apologising
+    // for a gap that was closed while it was not looking.
+    const { api } = client(['attr.status__in', 'attr.due_at__lte']);
+    const page = await api.listCommitments({ status: ['open', 'blocked'], dueBefore: 'x', owner: 'Kate' });
+    expect(page.appliedFilters).toEqual(['status', 'dueBefore']);
+    // And owner is NOT claimed, because the server did not report it.
+    expect(page.appliedFilters).not.toContain('owner');
+  });
+
+  it('believes the server through the CAMELCASE client too', async () => {
+    // `@startsimpli/api` converts every response key snake_case -> camelCase, so
+    // in a browser the tenant's `applied_filters` arrives as `appliedFilters`.
+    // Reading only one spelling put "this workspace's data API did not filter by
+    // status" on a deployed screen while the server was demonstrably filtering
+    // by status. Same lesson as accepting `document_id` in a citation.
+    const seen: Array<Record<string, unknown>> = [];
+    const api = createCorpusApi({
+      http: {
+        async get<T>(_path: string, options?: { params?: Record<string, unknown> }): Promise<T> {
+          seen.push(options?.params ?? {});
+          return { count: 0, next: null, previous: null, results: [],
+                   appliedFilters: ['attr.status__in'], ignoredFilters: [] } as T;
+        },
+      },
+      scope: { orgId: 'tandem' },
+      supportedFilters: [],
+    });
+    const page = await api.listCommitments({ status: ['open', 'blocked'] });
+    expect(page.appliedFilters).toEqual(['status']);
+    expect(seen[0]['attr.status__in']).toBe('open,blocked');
+  });
+
+  it('falls back to the declared list on a server that does not report', async () => {
+    const { api } = client(undefined);
+    const page = await api.listCommitments({ status: 'open' });
+    expect(page.appliedFilters).toEqual([]);
+  });
+});

package/src/__tests__/corpus-tracker.test.tsx

@@ -7,6 +7,7 @@
  * as though it had one, a filter that did nothing, a row with no traceable
  * source, a run that closed something and did not say why.
  */
+import * as React from 'react';
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { describe, expect, it, vi } from 'vitest';
@@ -92,6 +93,61 @@ function makeApi(options: {
   };
 }
 
+describe('TrackerPage — it must not loop', () => {
+  /**
+   * SHIPPED TO PRODUCTION AND CAUGHT BY A HUMAN, not by this suite: 917
+   * `entities` requests in ten minutes on the live tenant, the screen visibly
+   * flashing. The cause was three lines that each looked reasonable:
+   *
+   *   now = Date.now()                  a defaulted prop — a NEW value per render
+   *   useMemo(..., [tab, owner, now])   so a new query object per render
+   *   useCallback(..., [api, query])    so a new loader per render
+   *   useEffect(..., [load])            so a fetch per render -> setState -> render
+   *
+   * A defaulted `Date.now()` can never be a stable dependency. These tests count
+   * requests, because that is the only thing that catches this: at 1.5 requests
+   * a second the screenshot looks perfect.
+   */
+  it('fetches ONCE on mount and then stops', async () => {
+    let calls = 0;
+    const api = makeApi({ onQuery: () => { calls += 1; } });
+    render(<TrackerPage api={api} scope={SCOPE} />);
+    await screen.findByText('Chase the inventor for comments on 2148');
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    expect(calls).toBe(1);
+  });
+
+  it('does not loop even when the app hands it a NEW api object every render', async () => {
+    // The composer takes an injected capability. A caller that builds it inline
+    // is a mistake, but it must not be a runaway one — the identity of an api is
+    // not a reason to re-read the same query.
+    let calls = 0;
+    function Harness() {
+      const [, force] = React.useState(0);
+      React.useEffect(() => {
+        const timer = setInterval(() => force((value) => value + 1), 20);
+        return () => clearInterval(timer);
+      }, []);
+      // Deliberately unmemoized.
+      return <TrackerPage api={makeApi({ onQuery: () => { calls += 1; } })} scope={SCOPE} />;
+    }
+    render(<Harness />);
+    await screen.findByText('Chase the inventor for comments on 2148');
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(calls).toBe(1);
+  });
+
+  it('DOES re-read when the user actually changes something', async () => {
+    let calls = 0;
+    render(<TrackerPage api={makeApi({ onQuery: () => { calls += 1; } })} scope={SCOPE} now={NOW} />);
+    await screen.findByText('Chase the inventor for comments on 2148');
+    expect(calls).toBe(1);
+    await userEvent.click(screen.getByRole('tab', { name: 'Overdue' }));
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(calls).toBe(2);
+  });
+});
+
 describe('TrackerPage — what is outstanding', () => {
   it('shows open items and hides closed ones', async () => {
     render(<TrackerPage api={makeApi()} scope={SCOPE} now={NOW} />);
@@ -116,7 +172,7 @@ describe('TrackerPage — what is outstanding', () => {
     // The Library's `appliedFilters` contract, owed here about status — a
     // status filter that silently does nothing breaks the screen's only claim.
     expect(
-      await screen.findByText(/does not filter by .*status/i),
+      await screen.findByText(/did not filter by .*status/i),
     ).toBeInTheDocument();
   });
 
@@ -129,7 +185,7 @@ describe('TrackerPage — what is outstanding', () => {
       />,
     );
     await screen.findByText('Chase the inventor for comments on 2148');
-    expect(screen.queryByText(/does not filter by/i)).not.toBeInTheDocument();
+    expect(screen.queryByText(/did not filter by/i)).not.toBeInTheDocument();
   });
 
   it('puts an overdue item above one with no due date', async () => {

package/src/components/pages/TrackerPage.tsx

@@ -41,7 +41,15 @@ export interface TrackerPageProps {
   scope: CorpusScope;
   /** Click-through from a mention to the record, normally the Library route. */
   onOpenDocument?: (documentId: string) => void;
-  /** Injectable clock, so "overdue" and "this week" are testable. */
+  /**
+   * Injectable clock, so "overdue" and "this week" are testable.
+   *
+   * NOT DEFAULTED IN THE SIGNATURE. `now = Date.now()` is a new value on every
+   * render, which makes every memo below it new, which makes the load effect
+   * fire on every render, which sets state, which renders. That shipped, and it
+   * cost 917 requests in ten minutes on a live tenant. When the caller does not
+   * supply a clock, one is frozen ONCE for the life of the component.
+   */
   now?: number;
   classNames?: Partial<Record<TrackerSlot, string>>;
 }
@@ -79,11 +87,24 @@ export function TrackerPage({
   api,
   scope,
   onOpenDocument,
-  now = Date.now(),
+  now,
   classNames = {},
 }: TrackerPageProps) {
   const cn = { ...DEFAULTS, ...classNames };
 
+  // Frozen once. See the note on the prop.
+  const [mountedAt] = React.useState(() => Date.now());
+  const clock = now ?? mountedAt;
+
+  /**
+   * The api is an injected CAPABILITY, not data, so its identity is not a reason
+   * to re-read the same query — and an app that builds it inline must not turn
+   * that mistake into a runaway. Held in a ref and read at call time; a genuine
+   * change of workspace re-reads through `scope.orgId` below.
+   */
+  const apiRef = React.useRef(api);
+  apiRef.current = api;
+
   const [tab, setTab] = React.useState<'open' | 'overdue' | 'recent' | 'done'>('open');
   const [owner, setOwner] = React.useState('');
   const [rows, setRows] = React.useState<Commitment[]>([]);
@@ -101,18 +122,18 @@ export function TrackerPage({
       // and the banner alone would be doing all the work.
       status: tab === 'done' ? 'done' : (['open', 'blocked'] as CommitmentStatus[]),
       ...(owner.trim() ? { owner: owner.trim() } : {}),
-      ...(tab === 'recent' ? { changedAfter: new Date(now - WEEK_MS).toISOString() } : {}),
-      ...(tab === 'overdue' ? { dueBefore: new Date(now).toISOString() } : {}),
+      ...(tab === 'recent' ? { changedAfter: new Date(clock - WEEK_MS).toISOString() } : {}),
+      ...(tab === 'overdue' ? { dueBefore: new Date(clock).toISOString() } : {}),
       pageSize: 200,
     }),
-    [tab, owner, now],
+    [tab, owner, clock],
   );
 
   const load = React.useCallback(async () => {
     setLoading(true);
     setError('');
     try {
-      const page = await api.listCommitments(query);
+      const page = await apiRef.current.listCommitments(query);
       setRows(page.results);
       setApplied(page.appliedFilters ?? []);
     } catch (err) {
@@ -121,35 +142,36 @@ export function TrackerPage({
     } finally {
       setLoading(false);
     }
-  }, [api, query]);
+  }, [query]);
 
-  React.useEffect(() => { void load(); }, [load]);
+  // Real input only: the query the user asked for, and the workspace they are in.
+  React.useEffect(() => { void load(); }, [load, scope.orgId]);
 
   /**
    * The tab, applied in the browser as well as sent to the server.
    *
-   * NOT a violation of rule 8 — the query still goes out as parameters and the
-   * server still pages. This is the honest belt to the server's braces: until bd
-   * startsim-768w.38.12 teaches the tenant API `?status=`, the API returns
-   * everything, and a screen that showed closed items under "Outstanding" would
-   * be lying about the one thing it exists to say. The banner below states that
-   * the list is not server-filtered, so the user knows the count is over what
-   * this page could fetch rather than over the whole corpus.
+   * NOT a violation of rule 8 — the query goes out as `attr.*` parameters and
+   * the server pages and filters. This is the belt to the server's braces: a
+   * deployment whose API ignores one of them must not end up rendering closed
+   * items under "Outstanding", which is the one thing this screen exists to say.
+   * Re-applying a filter the server already applied is a no-op; not re-applying
+   * one it ignored is a lie. The banner below fires only when the SERVER itself
+   * reports it did not apply something.
    */
   const visible = React.useMemo(() => {
     const byTab = rows.filter((item) => {
       if (tab === 'done') return item.status === 'done' || item.status === 'dropped';
       if (item.status !== 'open' && item.status !== 'blocked') return false;
-      if (tab === 'overdue') return isOverdue(item, now);
-      if (tab === 'recent') return changedSince(item, now - WEEK_MS);
+      if (tab === 'overdue') return isOverdue(item, clock);
+      if (tab === 'recent') return changedSince(item, clock - WEEK_MS);
       return true;
     });
     const needle = owner.trim().toLowerCase();
     const byOwner = needle
       ? byTab.filter((item) => (item.ownerName ?? '').toLowerCase().includes(needle))
       : byTab;
-    return [...byOwner].sort(compareForScreen(now));
-  }, [rows, tab, owner, now]);
+    return [...byOwner].sort(compareForScreen(clock));
+  }, [rows, tab, owner, clock]);
 
   const unfiltered = (['status', 'owner', 'dueBefore', 'changedAfter'] as const).filter(
     (key) => Boolean(query[key]) && !applied.includes(key),
@@ -191,7 +213,7 @@ export function TrackerPage({
                 setRunning(true);
                 setError('');
                 try {
-                  setRun(await api.extract!({ scope }));
+                  setRun(await apiRef.current.extract!({ scope }));
                   await load();
                 } catch (err) {
                   setError(failureMessage(err));
@@ -210,7 +232,7 @@ export function TrackerPage({
           // status — and it matters more here, because "outstanding" is the
           // claim the whole screen makes.
           <p className={cn.warning} role="status">
-            This workspace’s data API does not filter by {unfiltered.join(', ')} yet, so this list was
+            This workspace’s data API did not filter by {unfiltered.join(', ')}, so this list was
             narrowed in the browser over the records it could fetch. Counts are over that set, not
             over the whole corpus.
           </p>
@@ -237,7 +259,7 @@ export function TrackerPage({
           <CommitmentRow
             key={item.externalId}
             item={item}
-            now={now}
+            now={clock}
             classNames={cn}
             onOpenDocument={onOpenDocument}
           />

package/src/corpus/client.ts

@@ -114,6 +114,101 @@ interface DrfPage<T> {
   results: T[];
 }
 
+/**
+ * What the tenant data API reports back about the query it was handed.
+ *
+ * `applied_filters` and `ignored_filters` are the whole reason a composer can
+ * stop guessing: a screen that narrows its own list has to know whether it is
+ * doing so because the server could not, or is duplicating work the server
+ * already did. Reported per response, so a capability that lands mid-week is
+ * picked up without a client deploy.
+ */
+interface ServerFilterReport {
+  applied_filters?: string[];
+  /**
+   * BOTH SPELLINGS, and this is not defensive padding — it is the difference
+   * between the banner telling the truth and telling a lie.
+   *
+   * `@startsimpli/api`'s fetch wrapper converts every response key from
+   * snake_case to camelCase by default (`transformKeys`), so the tenant's
+   * `applied_filters` reaches this adapter as `appliedFilters` in the browser
+   * and as `applied_filters` from a plain server-side `fetch`. Reading only one
+   * made the deployed Tracker report "this workspace's data API did not filter
+   * by status" while the server was, verifiably, filtering by status. Same
+   * lesson as `resolveCitations` accepting `document_id`: the tolerance belongs
+   * at the seam.
+   */
+  appliedFilters?: string[];
+  ignored_filters?: string[];
+  ignoredFilters?: string[];
+  search_backend?: string;
+}
+
+/**
+ * `CommitmentQuery` -> the tenant's own parameter vocabulary.
+ *
+ * Attribute filters are `attr.<declared name>` with an optional operator suffix,
+ * which is why every field the tracker filters on has to be a DECLARED
+ * AttributeDef — an undeclared attribute is invisible to the index and the
+ * server reports it under `ignored_filters` rather than silently returning
+ * everything.
+ */
+const TEXT_FILTER_MAX = 500;
+
+function commitmentParams(query: CommitmentQuery, type: string): Record<string, unknown> {
+  const statuses = Array.isArray(query.status) ? query.status : query.status ? [query.status] : [];
+  const out: Record<string, unknown> = {
+    type,
+    page: query.page ?? 1,
+    ...(query.pageSize ? { page_size: Math.min(query.pageSize, 200) } : {}),
+    // Oldest debt first, which is what the screen sorts by anyway — asking the
+    // server for it means page one is the right page one.
+    order: 'attr.due_at',
+  };
+  if (statuses.length === 1) out['attr.status'] = statuses[0];
+  else if (statuses.length > 1) out['attr.status__in'] = statuses.join(',');
+  if (query.subtype) out['attr.subtype'] = query.subtype;
+  if (query.owner) out['attr.owner_name__icontains'] = query.owner.slice(0, TEXT_FILTER_MAX);
+  if (query.dueBefore) out['attr.due_at__lte'] = query.dueBefore;
+  if (query.changedAfter) out['attr.last_seen_at__gte'] = query.changedAfter;
+  if (query.search) out.search = query.search.slice(0, TEXT_FILTER_MAX);
+  return out;
+}
+
+/** Which server parameter carries which `CommitmentQuery` key. */
+const FILTER_PARAMS: Array<[keyof CommitmentQuery, string[]]> = [
+  ['status', ['attr.status', 'attr.status__in']],
+  ['subtype', ['attr.subtype']],
+  ['owner', ['attr.owner_name__icontains']],
+  ['dueBefore', ['attr.due_at__lte']],
+  ['changedAfter', ['attr.last_seen_at__gte']],
+  ['search', ['search']],
+];
+
+/** Which server parameter carries which `DocumentQuery` key. */
+const DOCUMENT_FILTER_PARAMS: Array<[keyof DocumentQuery, string[]]> = [
+  ['search', ['search']],
+  ['source', ['source', 'attr.source']],
+  ['partyId', ['party', 'related_to']],
+  ['occurredAfter', ['occurred_after', 'attr.occurred_at__gte']],
+  ['occurredBefore', ['occurred_before', 'attr.occurred_at__lte']],
+];
+
+function reportedDocumentFilters(query: DocumentQuery, applied: string[]): string[] {
+  const server = new Set(applied);
+  return DOCUMENT_FILTER_PARAMS.filter(
+    ([key, names]) => Boolean(query[key]) && names.some((name) => server.has(name)),
+  ).map(([key]) => key);
+}
+
+/** Translate the server's report back into the composer's vocabulary. */
+function reportedFilters(query: CommitmentQuery, applied: string[]): string[] {
+  const server = new Set(applied);
+  return FILTER_PARAMS.filter(
+    ([key, params]) => Boolean(query[key]) && params.some((param) => server.has(param)),
+  ).map(([key]) => key);
+}
+
 const EMPTY_PAGE = { count: 0, next: null, previous: null, results: [] };
 
 /** Rows written in parallel. Small enough not to look like a burst to the tenant. */
@@ -163,15 +258,20 @@ export function createCorpusApi(options: CreateCorpusApiOptions): CorpusApi & Co
     query: DocumentQuery,
     map: (entity: TenantEntity) => T,
   ): Promise<CorpusPage<T>> {
-    const response = await http.get<DrfPage<TenantEntity>>(entities, {
+    const response = await http.get<DrfPage<TenantEntity> & ServerFilterReport>(entities, {
       params: params(query, type),
     });
+    // The SERVER's own report wins here too — the Library was reading a
+    // hardcoded list while the tenant had learned to filter.
+    const reported = response.applied_filters ?? response.appliedFilters;
     return {
       count: response.count ?? response.results?.length ?? 0,
       next: response.next ?? null,
       previous: response.previous ?? null,
       results: (response.results ?? []).map(map),
-      appliedFilters: appliedFilters(query, supportedFilters),
+      appliedFilters: reported
+        ? reportedDocumentFilters(query, reported)
+        : appliedFilters(query, supportedFilters as string[]),
     };
   }
 
@@ -278,28 +378,23 @@ export function createCorpusApi(options: CreateCorpusApiOptions): CorpusApi & Co
      * than rendering an unfiltered list under a filled-in control.
      */
     async listCommitments(query: CommitmentQuery = {}): Promise<CorpusPage<Commitment>> {
-      const statuses = Array.isArray(query.status) ? query.status : query.status ? [query.status] : [];
-      const response = await http.get<DrfPage<TenantEntity>>(entities, {
-        params: {
-          type: types.commitment,
-          page: query.page ?? 1,
-          ...(query.pageSize ? { page_size: query.pageSize } : {}),
-          ...(statuses.length ? { status: statuses.join(',') } : {}),
-          ...(query.subtype ? { subtype: query.subtype } : {}),
-          ...(query.owner ? { owner: query.owner } : {}),
-          ...(query.dueBefore ? { due_before: query.dueBefore } : {}),
-          ...(query.changedAfter ? { changed_after: query.changedAfter } : {}),
-          ...(query.search ? { search: query.search } : {}),
-        },
-      });
+      const params = commitmentParams(query, types.commitment);
+      const response = await http.get<DrfPage<TenantEntity> & ServerFilterReport>(entities, { params });
+      const reported = response.applied_filters ?? response.appliedFilters;
       return {
         count: response.count ?? response.results?.length ?? 0,
         next: response.next ?? null,
         previous: response.previous ?? null,
         results: (response.results ?? []).map((entity) => toCommitment(entity, scope, sourceLabels)),
-        appliedFilters: (['status', 'subtype', 'owner', 'dueBefore', 'changedAfter', 'search'] as const)
-          .filter((key) => Boolean(query[key]))
-          .filter((key) => (supportedFilters as string[]).includes(key)),
+        // THE SERVER'S OWN ANSWER WINS. `applied_filters` is reported by the
+        // tenant data API (capabilities.entities.reports_applied_filters), so
+        // the screen no longer has to be told out-of-band what the backend can
+        // do — and cannot claim a gap that has since been closed. The static
+        // `supportedFilters` list is only the fallback for a deployment old
+        // enough not to report.
+        appliedFilters: reported
+          ? reportedFilters(query, reported)
+          : appliedFilters(query as DocumentQuery, supportedFilters as string[]),
       };
     },