@oberik/sdk 0.65.0 → 0.67.0

package/dist/esm/index.js

@@ -758,6 +758,25 @@ function asBlob(input) {
     // handing that straight to Blob can carry bytes belonging to something else.
     return new Blob([bytes.slice()]);
 }
+/**
+ * The name a document is stored under: what the caller passed, the file's own, or a
+ * placeholder.
+ *
+ * One function for both clients, because they disagreed about it. The project client
+ * derived a name and fell back to `"upload.bin"`; the end-user client took `filename` in a
+ * **required** options object, so a JavaScript caller writing the documented
+ * `uploadAndWait(file)` got `TypeError: Cannot read properties of undefined (reading
+ * 'filename')` — thrown from inside the SDK, with nothing in the stack naming Oberik, at
+ * the reader most likely to have copied the snippet (OBE-195).
+ *
+ * Both are optional now and both land here. `"upload.bin"` rather than a refusal: a `File`
+ * carries its name and a Blob, Buffer or ArrayBuffer does not, and an upload that arrives
+ * with a placeholder name is visibly wrong in the listing, where a caller can fix it with
+ * `documents.update`. Pass `filename` — it is what the document is listed and cited under.
+ */
+function uploadName(file, filename) {
+    return filename || file?.name || "upload.bin";
+}
 /** Normalise whatever an `onQuestion` handler returned into an answer the API accepts.
  *
  *  A handler returning a bare string was silently ignored. `{ ...answer }` on a string
@@ -2346,17 +2365,35 @@ export class AgentFramework {
         },
     };
     documents = {
+        /**
+         * One PAGE of documents, newest first — `{ items, has_more, next_offset }`.
+         *
+         * It was a bare array, which asserts completeness by omission, on the one collection
+         * that only grows: a live project of 302 documents returned all 302 and 181KB on every
+         * call, and a 10k corpus would be ~6MB on a route a dashboard opens with (OBE-190).
+         * `limit` defaults to 100 and is capped at 500; page with `next_offset`, which is given
+         * rather than left as arithmetic because the cap can make `offset + limit` wrong.
+         *
+         * `with_total` adds a `total` and costs a second query — for a summary, not for paging.
+         * "Is there another page" is `has_more`, and it is free.
+         */
         list: (query = {}) => this.request("GET", "/documents", { query }),
         get: (id) => this.request("GET", `/documents/${id}`),
         delete: (id) => this.request("DELETE", `/documents/${id}`),
         retrieve: (body) => this.request("POST", "/documents/retrieve", { body }),
         /** Small-file convenience upload via multipart form (server proxies to S3). */
-        uploadSimple: async (file, opts) => {
+        uploadSimple: async (file, 
+        // Optional, and the same shape the project client takes: this signature required an
+        // options object, so `uploadSimple(file)` and `uploadAndWait(file)` — the way the
+        // docs write them — threw a TypeError out of the SDK's own body instead of saying
+        // what was missing (OBE-195).
+        opts = {}) => {
+            const filename = uploadName(file, opts.filename);
             const form = new FormData();
             const blob = typeof Blob !== "undefined" && file instanceof Blob
                 ? file
                 : new Blob([file], { type: opts.contentType ?? "application/octet-stream" });
-            form.append("file", blob, opts.filename);
+            form.append("file", blob, filename);
             form.append("tags", (opts.tags ?? []).join(","));
             // Set visibility AT UPLOAD, not after: a document is retrievable as soon as
             // ingestion finishes, so patching later leaves a window where it's readable by
@@ -2389,7 +2426,7 @@ export class AgentFramework {
             return (await res.json());
         },
         /** Resumable presigned multipart upload (direct to S3). */
-        upload: (file, opts) => this.multipartUpload(file, opts),
+        upload: (file, opts = {}) => this.multipartUpload(file, opts),
         /** Poll a document until ingestion finishes (status "ready" or "failed").
          *  Ingestion is async, so querying a just-uploaded doc may return nothing until
          *  this resolves. Throws on "failed" or timeout. */
@@ -2413,7 +2450,7 @@ export class AgentFramework {
         // Takes the ACL fields too: this is the upload most callers use, so omitting them
         // here forced a second `patch` and left a window where the document was already
         // retrievable at its default visibility.
-        opts) => {
+        opts = {}) => {
             const doc = await this.documents.uploadSimple(file, opts);
             return this.documents.waitReady(doc.id, { timeoutMs: opts.timeoutMs, signal: opts.signal });
         },
@@ -3074,7 +3111,7 @@ export class AgentFramework {
         const maxRetries = opts.maxRetries ?? 5;
         const presign = await this.request("POST", "/documents/presign-upload", {
             body: {
-                filename: opts.filename,
+                filename: uploadName(file, opts.filename),
                 content_type: opts.contentType,
                 tags: opts.tags ?? [],
                 ...(opts.visibility ? { visibility: opts.visibility } : {}),
@@ -3353,6 +3390,9 @@ export class OberikProject {
      * turning citation markers off, meant dropping to raw HTTP through `raw()`.
      */
     project = {
+        /** The project, its capability ceiling and its settings — plus `readiness` and the
+         *  `health` / `healthDetail` badge, so "is this project working" is answered by the
+         *  first thing you fetch rather than one route further on. */
         get: () => this.request("GET", ""),
         /** Merges — send only what you want to change. */
         set: (fields) => this.request("PATCH", "", fields),
@@ -3426,9 +3466,26 @@ export class OberikProject {
      * accepted nor needed — a recipe that worked by luck rather than by expression.
      */
     documents = {
-        /** Same filters as the end-user client's `documents.list`, so the two agree. */
+        /**
+         * One PAGE of the corpus — the same envelope, the same filters and the same paging as
+         * the end-user client's `documents.list`, because they are the same route.
+         *
+         * The route became a page in OBE-190 and this declaration did not move with it: it
+         * still said `Promise<DocumentOut[]>`, so a TypeScript caller wrote `.length` and got
+         * `undefined` with no type error and no exception — a census that counted documents
+         * reported zero. That is OBE-147 verbatim, one collection over, and the docstring
+         * describing it sits sixty lines above this one (OBE-195). The query type had the
+         * mirror-image gap: `limit`/`offset` worked at runtime and were unwritable in
+         * TypeScript, so the documented paging loop did not compile against the client that
+         * recommends it.
+         *
+         * `with_total` adds a `total`; it is what "how big is this corpus" is asked with, and
+         * it costs a second query. "Is there another page" is `has_more`, and it is free.
+         */
         list: (query = {}) => {
-            const qs = new URLSearchParams(Object.entries(query).filter(([, v]) => v != null)).toString();
+            const qs = new URLSearchParams(Object.entries(query)
+                .filter(([, v]) => v != null)
+                .map(([k, v]) => [k, String(v)])).toString();
             return this.request("GET", `/documents${qs ? `?${qs}` : ""}`);
         },
         get: (documentId) => this.request("GET", `/documents/${documentId}`),
@@ -3473,8 +3530,7 @@ export class OberikProject {
          */
         opts = {}) => {
             const form = new FormData();
-            const name = opts.filename ?? file.name ?? "upload.bin";
-            form.append("file", asBlob(file), name);
+            form.append("file", asBlob(file), uploadName(file, opts.filename));
             form.append("tags", (opts.tags ?? []).join(","));
             if (opts.visibility)
                 form.append("visibility", opts.visibility);