@oddington/sdk 0.1.5 → 0.1.6

package/README.md

@@ -140,8 +140,41 @@ Each graph selection sends one request and returns only selected canonical
 values, expanded forward links and exact opaque public versions. Cursors
 continue the exact retained artifact and collection selection, even after
 replacement; repeat its options and links while omitting unrelated collections.
-No automatic retry, separate version fetch, search or history operation is
-included. Collection schemas omit Markdown storage hints.
+There is no automatic retry or separate version fetch. History is not included.
+Collection schemas omit Markdown storage hints.
+
+Use bounded plain-text lookup to find full Records and guards:
+
+```ts
+const found = await general.records.search('acme overdue', {
+  collections: ['invoices'], limit: 20,
+});
+const searchedVersion = found.$meta.version;
+for (const { collection, record } of found.matches) {
+  console.log(collection, record.$ref, record.$version);
+}
+```
+
+Search sends one request. The trimmed query has 1–256 Unicode code points;
+case-insensitive whitespace-separated terms match stable refs and structured
+scalar values, including link refs and array values. Every term must match;
+field names and Markdown bodies are excluded. Omitted options search all
+accessible collections with a limit of 20. Supplied collections contain 1–16
+distinct accessible names; the integer limit is 1–100. Invalid queries or
+unsupported options fail with `invalid_query`. There is no cursor, count,
+projection, highlighting, embedding or historical version option.
+
+Matches have deterministic order and complete canonical Records. Empty matches
+succeed with the exact searched version. Members search latest published data;
+routines search their captured version, advancing only through their own
+publication. Immediate `os routine run` uses hosted search. During
+`os routine prepare`, search uses the same committed local Index as select,
+ignores dirty/untracked files and advances only to that run's exact proposed
+version after its own Changes publication. Validation does not advance reads;
+another publisher does not move the captured view. Search Records can supply
+guards for subsequent Changes. Missing or incomplete search data, including
+retained versions without it, fails retryably with `unavailable` without an
+alternate read path.
 
 `where` combines field conditions with AND. Alongside exact scalar/null equality
 and `$in`, declared one-valued `integer`, `number` and `date` fields accept

package/dist/index.js

@@ -21709,6 +21709,49 @@ class DataOperationError extends Error {
   }
 }
 
+// ../../shared/data-search-input.ts
+var invalid = () => {
+  throw new DataOperationError("invalid_query");
+};
+var scalarText = (value) => typeof value === "string" && !/[\u0000\uD800-\uDFFF]/u.test(value);
+function captureRecordsSearchInput(query, options) {
+  if (!scalarText(query))
+    return invalid();
+  const length = [...query.trim()].length;
+  if (length < 1 || length > 256)
+    return invalid();
+  if (options === undefined)
+    return { query };
+  if (!options || typeof options !== "object" || Array.isArray(options) || ![Object.prototype, null].includes(Object.getPrototypeOf(options)))
+    return invalid();
+  const descriptors = Object.getOwnPropertyDescriptors(options);
+  if (Reflect.ownKeys(options).some((key) => typeof key !== "string" || !["collections", "limit"].includes(key) || !descriptors[key]?.enumerable || !Object.hasOwn(descriptors[key], "value")))
+    return invalid();
+  const captured = {};
+  if (Object.hasOwn(descriptors, "collections")) {
+    const supplied = descriptors.collections.value;
+    if (!Array.isArray(supplied) || supplied.length < 1 || supplied.length > 16 || Reflect.ownKeys(supplied).length !== supplied.length + 1)
+      return invalid();
+    const collections = [];
+    for (let index = 0;index < supplied.length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(supplied, String(index));
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value") || !scalarText(descriptor.value))
+        return invalid();
+      collections.push(descriptor.value);
+    }
+    if (new Set(collections).size !== collections.length)
+      return invalid();
+    captured.collections = collections;
+  }
+  if (Object.hasOwn(descriptors, "limit")) {
+    const supplied = descriptors.limit.value;
+    if (!Number.isInteger(supplied) || supplied < 1 || supplied > 100)
+      return invalid();
+    captured.limit = supplied;
+  }
+  return { query, options: captured };
+}
+
 // ../../shared/data-envelope.ts
 var DATA_REQUEST_LIMIT = 256 * 1024;
 var invalidChange = () => {
@@ -21842,55 +21885,55 @@ class FileOperationError extends Error {
 }
 var FILE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 function parseFileDescriptor(value) {
-  const invalid = () => {
+  const invalid2 = () => {
     throw new FileOperationError("unavailable", 503, true);
   };
   if (!value || typeof value !== "object" || Array.isArray(value))
-    return invalid();
+    return invalid2();
   const f = value;
   if (Object.keys(f).sort().join(",") !== "details,enrichments,id,mediaType,name,path,sha256,size" || typeof f.id !== "string" || !FILE_ID_PATTERN.test(f.id) || !safeFileName(f.name) || !safeFilePath(f.path) || !Number.isSafeInteger(f.size) || f.size < 0 || f.size > 16 * 1024 * 1024 || typeof f.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(f.sha256) || !f.enrichments || typeof f.enrichments !== "object" || Array.isArray(f.enrichments) || !f.details || typeof f.details !== "object" || Array.isArray(f.details))
-    return invalid();
+    return invalid2();
   const d = f.details;
   if (d.kind === "other") {
     if (Object.keys(d).length !== 1 || f.mediaType !== "application/octet-stream")
-      return invalid();
+      return invalid2();
   } else if (d.kind === "csv") {
     if (Object.keys(d).sort().join(",") !== "dataRows,delimiter,encoding,headerRow,kind" || f.mediaType !== "text/csv" || !["utf-8", "windows-1252"].includes(d.encoding) || ![",", ";", "\t"].includes(d.delimiter) || !Number.isSafeInteger(d.headerRow) || d.headerRow < 1 || !Number.isSafeInteger(d.dataRows) || d.dataRows < 0)
-      return invalid();
+      return invalid2();
   } else
-    return invalid();
+    return invalid2();
   for (const [name, descriptor] of Object.entries(f.enrichments)) {
     if (!safeEnrichmentName(name))
-      return invalid();
+      return invalid2();
     parseEnrichmentDescriptor(descriptor);
   }
   if (new TextEncoder().encode(JSON.stringify(f)).byteLength > 16 * 1024)
-    return invalid();
+    return invalid2();
   return f;
 }
 function parseEnrichmentDescriptor(value) {
-  const invalid = () => {
+  const invalid2 = () => {
     throw new FileOperationError("unavailable", 503, true);
   };
   if (!value || typeof value !== "object" || Array.isArray(value))
-    return invalid();
+    return invalid2();
   const d = value;
   if (Object.keys(d).sort().join(",") !== "mediaType,sha256,size" || !["application/octet-stream", "text/plain", "text/markdown", "application/json"].includes(d.mediaType) || !Number.isSafeInteger(d.size) || d.size < 0 || d.size > 16 * 1024 * 1024 || typeof d.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(d.sha256))
-    return invalid();
+    return invalid2();
   return d;
 }
 function safeEnrichmentName(value) {
   return safeFileName(value) && !/^original(?:\.|$)/i.test(value);
 }
 function parseFileEnrichMetadata(value, maxBytes) {
-  const invalid = () => {
+  const invalid2 = () => {
     throw new FileOperationError("invalid_input", 400);
   };
   if (!value || typeof value !== "object" || Array.isArray(value))
-    return invalid();
+    return invalid2();
   const d = value;
   if (Object.keys(d).some((key) => !["name", "size", "mediaType", "replace"].includes(key)) || !safeEnrichmentName(d.name) || !Number.isSafeInteger(d.size) || d.size < 0 || d.mediaType !== undefined && (typeof d.mediaType !== "string" || d.mediaType.length > 255 || /[\u0000-\u001f\u007f]/.test(d.mediaType)) || d.replace !== undefined && (typeof d.replace !== "string" || !/^[0-9a-f]{64}$/.test(d.replace)))
-    return invalid();
+    return invalid2();
   if (d.size > maxBytes)
     throw new FileOperationError("request_too_large", 413);
   return d;
@@ -21902,37 +21945,37 @@ function safeFilePath(value) {
   return typeof value === "string" && value.length <= 1024 && value.split("/").every(safeFileName);
 }
 function parseFileCreateMetadata(value, maxBytes) {
-  const invalid = () => {
+  const invalid2 = () => {
     throw new FileOperationError("invalid_input", 400);
   };
   if (!value || typeof value !== "object" || Array.isArray(value))
-    return invalid();
+    return invalid2();
   const input = value;
   if (Object.keys(input).some((key) => !["name", "path", "storage", "csv", "size", "requestKey"].includes(key)))
-    return invalid();
+    return invalid2();
   const path = input.path === undefined ? "Files" : input.path;
   if (!safeFileName(input.name) || !safeFilePath(path))
-    return invalid();
+    return invalid2();
   if (input.storage !== undefined && input.storage !== "remote" && input.storage !== "local")
-    return invalid();
+    return invalid2();
   if (!Number.isSafeInteger(input.size) || input.size < 0)
-    return invalid();
+    return invalid2();
   if (input.size > maxBytes)
     throw new FileOperationError("request_too_large", 413);
   if (typeof input.requestKey !== "string" || input.requestKey.length < 1 || input.requestKey.length > 256 || input.requestKey !== input.requestKey.trim() || /[\u0000-\u001f\u007f]/.test(input.requestKey))
-    return invalid();
+    return invalid2();
   let csv;
   if (input.csv !== undefined) {
     if (!input.csv || typeof input.csv !== "object" || Array.isArray(input.csv))
-      return invalid();
+      return invalid2();
     const hints = input.csv;
     if (Object.keys(hints).some((key) => !["encoding", "delimiter", "headerRow"].includes(key)))
-      return invalid();
+      return invalid2();
     const encoding = hints.encoding === undefined ? "utf-8" : hints.encoding;
     const delimiter = hints.delimiter === undefined ? "," : hints.delimiter;
     const headerRow = hints.headerRow === undefined ? 1 : hints.headerRow;
     if (encoding !== "utf-8" && encoding !== "windows-1252" || ![",", ";", "\t"].includes(delimiter) || !Number.isSafeInteger(headerRow) || headerRow < 1 || headerRow > 1e5)
-      return invalid();
+      return invalid2();
     csv = { encoding, delimiter, headerRow };
   }
   return {
@@ -22156,7 +22199,16 @@ var data = {
         list: () => send({ operation: "collections.list" }),
         schema: (name) => send({ operation: "collections.schema", name })
       },
-      records: { select: (query) => send({ operation: "records.select", query }) },
+      records: {
+        select: (query) => send({ operation: "records.select", query }),
+        search: (query, options) => {
+          try {
+            return send({ operation: "records.search", ...captureRecordsSearchInput(query, options) });
+          } catch (error) {
+            return Promise.reject(error);
+          }
+        }
+      },
       changes() {
         let updates = [], creates = [], deletes = [], publicationId;
         let pending, confirmed;
@@ -22261,7 +22313,7 @@ var TIMEOUT_MS = 30000;
 var MAX_ACTIVE = 4;
 var ATTEMPTS = 2;
 var active = 0;
-var invalid = () => new FileOperationError("invalid_input", 400);
+var invalid2 = () => new FileOperationError("invalid_input", 400);
 var unavailable = () => new FileOperationError("unavailable", 503, true);
 var failures = {
   400: ["invalid_input", "unsupported_context"],
@@ -22285,7 +22337,7 @@ async function boundedBytes(stream, limit) {
       if (done)
         break;
       if (!(value instanceof Uint8Array))
-        throw invalid();
+        throw invalid2();
       size += value.byteLength;
       if (size > limit)
         throw new FileOperationError("request_too_large", 413);
@@ -22325,6 +22377,74 @@ async function result(response) {
     throw unavailable();
   }
 }
+async function hostedContent(url, init, parent) {
+  const delivery = new AbortController;
+  const abort = () => delivery.abort(parent.reason);
+  parent.addEventListener("abort", abort, { once: true });
+  if (parent.aborted)
+    abort();
+  const detach = () => parent.removeEventListener("abort", abort);
+  try {
+    const response = await fetch(url, { ...init, signal: delivery.signal });
+    if (delivery.signal.aborted) {
+      response.body?.cancel().catch(() => {});
+      throw unavailable();
+    }
+    if (!response.body) {
+      detach();
+      return response;
+    }
+    const source = response.body;
+    let reader;
+    let settled = false;
+    const cancel = async (reason) => {
+      if (settled)
+        return;
+      settled = true;
+      detach();
+      delivery.abort(reason);
+      try {
+        await (reader ? reader.cancel(reason) : source.cancel(reason));
+      } catch (error) {
+        if (error !== delivery.signal.reason && !(error instanceof Error && error.name === "AbortError"))
+          throw error;
+      } finally {
+        reader?.releaseLock();
+      }
+    };
+    const body = new ReadableStream({
+      async pull(controller) {
+        try {
+          reader ??= source.getReader();
+          const { done, value } = await reader.read();
+          if (settled)
+            return;
+          if (done) {
+            settled = true;
+            detach();
+            reader.releaseLock();
+            controller.close();
+          } else
+            controller.enqueue(value);
+        } catch (error) {
+          if (settled)
+            return;
+          controller.error(error);
+          await cancel(error).catch(() => {});
+        }
+      },
+      cancel
+    }, { highWaterMark: 0 });
+    const wrapped = new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+    for (const key of ["url", "redirected", "type"])
+      Object.defineProperty(wrapped, key, { value: response[key] });
+    return wrapped;
+  } catch (error) {
+    detach();
+    delivery.abort(error);
+    throw error;
+  }
+}
 async function send(suffix, init, descriptor, initial, parent) {
   const original = initial;
   const checkCurrent = () => {
@@ -22360,13 +22480,17 @@ async function send(suffix, init, descriptor, initial, parent) {
             return new Response(Uint8Array.from(data2, (c) => c.charCodeAt(0)), { status: value2.status, headers: value2.headers });
           }
           return Response.json(value2.json, { status: value2.status, headers: value2.headers });
-        })() : await fetch(`${context.url}${suffix}`, {
-          ...init,
-          signal: parent,
-          headers: { ...context.headers, ...init.headers },
-          redirect: "error",
-          cache: "no-store"
-        });
+        })() : await (async () => {
+          const url = `${context.url}${suffix}`;
+          const request = {
+            ...init,
+            signal: parent,
+            headers: { ...context.headers, ...init.headers },
+            redirect: "error",
+            cache: "no-store"
+          };
+          return descriptor ? fetch(url, request) : hostedContent(url, request, parent);
+        })();
         if (!response.ok) {
           const value2 = await result(response);
           const error = value2 && typeof value2 === "object" && "error" in value2 ? value2.error : undefined;
@@ -22410,7 +22534,7 @@ async function send(suffix, init, descriptor, initial, parent) {
 }
 function idPath(id2) {
   if (typeof id2 !== "string" || !FILE_ID_PATTERN.test(id2))
-    throw invalid();
+    throw invalid2();
   return `/${id2}`;
 }
 async function operation(work, initial, parent) {
@@ -22433,7 +22557,7 @@ function contentPath(id2, name) {
   if (name === undefined)
     return `${path}/content`;
   if (!safeEnrichmentName(name))
-    throw invalid();
+    throw invalid2();
   return `${path}/enrichments/${encodeURIComponent(name)}/content`;
 }
 async function read(id2, names) {
@@ -22444,16 +22568,16 @@ async function read(id2, names) {
     return operation((context2, signal) => send(path, { method: "GET" }, false, context2, signal), context);
   }
   if (!Array.isArray(names))
-    throw invalid();
+    throw invalid2();
   const distinct = [];
   const seen = new Set;
   for (const name of names) {
     if (typeof name !== "string" || !safeEnrichmentName(name))
-      throw invalid();
+      throw invalid2();
     if (seen.has(name))
       continue;
     if (seen.size === 16)
-      throw invalid();
+      throw invalid2();
     seen.add(name);
     distinct.push(name);
   }
@@ -22487,15 +22611,15 @@ var files = {
   async create(input, options) {
     const context = await resolveFilesContext();
     if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !["file", "size", "path", "name", "storage", "csv"].includes(key)) || options !== undefined && (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some((key) => key !== "requestKey")))
-      throw invalid();
+      throw invalid2();
     const blob = input.file instanceof Blob;
     const array2 = input.file instanceof Uint8Array;
     const stream = input.file instanceof ReadableStream;
     if (!blob && !array2 && !stream)
-      throw invalid();
+      throw invalid2();
     const intrinsic = blob ? input.file.size : array2 ? input.file.byteLength : undefined;
     if (intrinsic !== undefined && input.size !== undefined && input.size !== intrinsic)
-      throw invalid();
+      throw invalid2();
     let name = input.name;
     if (name === undefined && blob && "name" in input.file && typeof input.file.name === "string") {
       name = typeof globalThis.File !== "undefined" && input.file instanceof globalThis.File ? input.file.name : input.file.name.split(/[\\/]/).at(-1);
@@ -22512,7 +22636,7 @@ var files = {
       throw new FileOperationError("unsupported_context", 400);
     const header = encodeURIComponent(JSON.stringify(metadata));
     if (new TextEncoder().encode(header).byteLength > METADATA_BYTES)
-      throw invalid();
+      throw invalid2();
     if (active >= MAX_ACTIVE)
       throw new FileOperationError("capacity", 429, true);
     active++;
@@ -22520,7 +22644,7 @@ var files = {
       try {
         const bytes = array2 ? input.file.slice() : await boundedBytes(blob ? input.file.stream() : input.file, metadata.size);
         if (bytes.byteLength !== metadata.size)
-          throw invalid();
+          throw invalid2();
         if (signal.aborted)
           throw unavailable();
         return await send("", {
@@ -22538,7 +22662,7 @@ var files = {
   async enrich(input) {
     const context = await resolveFilesContext();
     if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !["file", "name", "content", "mediaType", "replace"].includes(key)) || typeof input.content !== "string" && !(input.content instanceof Uint8Array))
-      throw invalid();
+      throw invalid2();
     const path = `${idPath(input.file)}/enrichments`;
     if (typeof input.content === "string" ? input.content.length > MAX_BYTES : input.content.byteLength > MAX_BYTES)
       throw new FileOperationError("request_too_large", 413);
@@ -22560,7 +22684,7 @@ var files = {
       }, MAX_BYTES);
       const header = encodeURIComponent(JSON.stringify(metadata));
       if (new TextEncoder().encode(header).byteLength > METADATA_BYTES)
-        throw invalid();
+        throw invalid2();
       const result2 = await send(path, { method: "POST", headers: {
         "content-type": "application/octet-stream",
         "x-oddington-enrichment": header

package/dist/types/packages/sdk/src/public.d.ts

@@ -13,7 +13,7 @@ export { AirtableOperationError } from '../../../shared/airtable-contract.js';
 export type { AirtableField, AirtableTable, AirtableRecord, AirtableListInput, AirtableGetInput, AirtableCreateInput, AirtableUpdateInput, AirtableDeleteInput, AirtableReceipt, AirtableWriteResult, AirtableClient, Connections } from '../../../shared/airtable-contract.js';
 export declare const connections: import('../../../shared/airtable-contract.js').Connections;
 export { DataOperationError } from '../../../shared/data-contract.js';
-export type { DataRepository, DataErrorCode, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordIdentity, RecordCreation, RecordUpdateSet, DataPublication, DataChangeSet, DataEffect } from '../../../shared/data-contract.js';
+export type { DataRepository, DataErrorCode, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordsSearchOptions, RecordsSearchResult, RecordIdentity, RecordCreation, RecordUpdateSet, DataPublication, DataChangeSet, DataEffect } from '../../../shared/data-contract.js';
 export declare const data: {
     repository(name: string): import('../../../shared/data-contract.js').DataRepository;
 };

package/dist/types/shared/data-contract.d.ts

@@ -107,6 +107,19 @@ export type RecordsResult = {
     [collection: string]: SelectedRecord[] | SelectionMetadata;
 };
 export type RecordIdentity = Pick<SelectedRecord, '$ref' | '$version'>;
+export type RecordsSearchOptions = {
+    collections?: string[];
+    limit?: number;
+};
+export type RecordsSearchResult = {
+    $meta: {
+        version: string;
+    };
+    matches: Array<{
+        collection: string;
+        record: SelectedRecord;
+    }>;
+};
 export type RecordUpdateSet = Record<string, DataValue>;
 export type RecordCreation = {
     $ref: string;
@@ -135,6 +148,7 @@ export interface DataRepository {
     };
     records: {
         select(query: RecordsQuery): Promise<RecordsResult>;
+        search(query: string, options?: RecordsSearchOptions): Promise<RecordsSearchResult>;
     };
     changes(): DataChangeSet;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Oddington routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",