@startsimpli/integrations 0.2.33 → 0.2.35

package/src/corpus/types.ts

@@ -127,6 +127,16 @@ export interface SourceDocument {
   scope: CorpusScope;
   /** When the connector last wrote this row. Drives the freshness claim. */
   ingestedAt?: string | null;
+  /**
+   * WHERE IT LIVES — the CONTAINER, `/Contracts`, never `/Contracts/SOW.pdf`
+   * (start-simpli-api#369 ships `path` with exactly that meaning).
+   *
+   * Absent on a record whose source has no notion of a folder — a meeting note,
+   * an email — and that absence is honest rather than a gap to be filled: those
+   * records live in no folder and are reachable from the top of the Library, not
+   * from a bucket invented for them.
+   */
+  folder?: string;
   /**
    * Attribute names the SERVER withheld from this reader
    * (bd startsim-768w.38.33). The tenant's per-field read gate strips them from
@@ -222,6 +232,34 @@ export interface SourceFreshness {
   status: 'ok' | 'stale' | 'error' | 'never';
   /** Why it is not `ok`, in the words the server used. */
   detail?: string;
+  /**
+   * WHY THE LAST SYNC FAILED, in the vendor's own words, and a DIFFERENT FACT
+   * FROM THE CREDENTIAL'S VERDICT (bd startsim-ei8gm.2).
+   *
+   * The Tandem Granola card read "Failing — 20 syncs in a row failed, synced
+   * 16d ago" for sixteen days and nothing said why. It was our own 256 KiB
+   * egress cap — the per-note detail response peaked at 351 KB — which is a
+   * minutes-long diagnosis for anyone who could see the text and sixteen days
+   * for anyone who could not.
+   *
+   * `check_error` COULD NOT HAVE ANSWERED IT, which is why this is its own
+   * field rather than a wider read of that one. `check()` and `poll()` are
+   * different requests: Granola's check asks for `page_size=1` and passes,
+   * while its poll asks for thirty notes with transcripts and aborts. The
+   * credential verified cleanly throughout, so a strip built on `check_error`
+   * alone can count twenty failures and name none of them — and it sends the
+   * reader to re-enter a key that was never the problem.
+   *
+   * Central sends it only while the connection's NEWEST run is the failed one
+   * (`SubtreeConnectionsView._last_failure_reasons`), so it is never last
+   * Tuesday's error quoted over a fix that has already landed. It is SCRUBBED
+   * server-side against that connection's own stored credential plus the
+   * platform app_secret — a vendor can quote our key back inside its own error
+   * body — and a reason that could not be scrubbed arrives as a sentence saying
+   * so rather than as the raw text. Nothing here re-checks it; there is exactly
+   * one redaction path and it is not in the browser.
+   */
+  lastError?: string;
 }
 
 /** DRF PageNumberPagination, which is what the tenant data API speaks. */
@@ -261,6 +299,72 @@ export interface DocumentQuery {
   /** ISO instants, filtering on `occurredAt`. */
   occurredAfter?: string;
   occurredBefore?: string;
+  /**
+   * THE FILES ON ONE SHELF — the documents whose container is EXACTLY this
+   * folder, which is what clicking a folder in a file browser means. Goes out as
+   * `?attr.path=<folder>`.
+   */
+  folder?: string;
+  /**
+   * THE WHOLE SUBTREE — this folder and everything beneath it. Goes out as
+   * `?attr.path__under=<folder>`.
+   *
+   * TWO FIELDS AND NOT ONE, AND `__startswith` IS NEITHER OF THEM. The tenant's
+   * `filters.subtree_bound()` spells out why: `startswith=/Contracts` also
+   * matches the sibling `/Contracts-old`, and `startswith=/Contracts/` misses
+   * the documents sitting directly IN `/Contracts`, which is most of what a
+   * person means by the folder. The correct bound is the UNION of the two, a
+   * list endpoint ANDs its filters so a caller cannot express a union, and that
+   * is why the server ships it as ONE parameter. Reach for this, never for a
+   * prefix a client assembled.
+   */
+  underFolder?: string;
+  page?: number;
+  pageSize?: number;
+}
+
+/**
+ * A CONTAINER IN THE CORPUS — one node of the folder tree.
+ *
+ * NOTHING MINTS ONE (bd startsim-maios). A folder is DERIVED at read time from
+ * the `path` attribute every file-shaped source already carries, so it has no id
+ * and no row: a rename re-mints nothing and orphans nothing, which is exactly
+ * the failure a materialised folder table would have. That is also why `path`
+ * below is the address — there is no other.
+ */
+export interface CorpusFolder {
+  /**
+   * The FULL path, as the server returned it — `/Contracts/2026`, never `2026`.
+   *
+   * IT GOES STRAIGHT BACK OUT, unmodified, as the next `under=` and as
+   * `folder`. The client never joins segments: doing so is a small escaping bug
+   * in every client that tries, and the server returns the whole path precisely
+   * so nobody has to.
+   */
+  path: string;
+  /** The last segment, for display only. Derived from `path`, never sent back. */
+  name: string;
+  /**
+   * DESCENDANT documents, not direct children — `/Contracts` counts the ones in
+   * `/Contracts/2026/Q1` too. That is the number a person reading a collapsed
+   * folder wants, and it is why a folder can show 12 and open onto no files of
+   * its own.
+   */
+  count: number;
+  /**
+   * Whether anything sits BELOW this folder. The disclosure control, answered by
+   * the same response that listed the folder — so drawing a triangle costs no
+   * probe request per node.
+   */
+  hasChildren: boolean;
+}
+
+/**
+ * One level of the tree. `under` is a folder the server previously returned (or
+ * `/` for the root, which means the whole corpus).
+ */
+export interface FolderQuery {
+  under: string;
   page?: number;
   pageSize?: number;
 }
@@ -275,6 +379,23 @@ export interface CorpusApi {
   listParties(query?: { search?: string; page?: number; pageSize?: number }): Promise<CorpusPage<Party>>;
   /** Per-source freshness, for the strip at the top of the Library. */
   listSources(): Promise<SourceFreshness[]>;
+  /**
+   * THE CHILD FOLDERS of one container, paginated (bd startsim-ei8gm.5).
+   *
+   * The second of the two reads a navigable tree needs: `listDocuments({folder})`
+   * gives the files on a shelf, this gives the shelves below it. Server-side and
+   * ONE LEVEL AT A TIME (CLAUDE.md rule 8) — reading every document's path and
+   * building the tree in the browser is the thing this exists to remove; it
+   * works at 247 records and expires in the low thousands.
+   *
+   * OPTIONAL, and a deployment can also HAVE it and refuse it. The tenant route
+   * shipped in start-simpli-api #391, so a fork built before that answers 404
+   * and an older one that never learned the parameters answers 400. Both mean
+   * the same thing to a caller — this corpus cannot enumerate folders — so the
+   * composer treats a failure exactly like an absent method and renders the flat
+   * list it rendered before. Never a half-drawn tree.
+   */
+  listFolders?(query: FolderQuery): Promise<CorpusPage<CorpusFolder>>;
   /**
    * Optional because a tenant with no payment connector has no money events, and
    * a corpus surface that requires one would fail the Dropbox-only test.