@nsp-labs/agnostic-sdk 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -9,6 +9,15 @@ and pass the runtime OpenAPI schema check.
 
 ## Unreleased
 
+## 1.5.0 - 2026-09-06
+
+### Added
+
+- `data.table(name).records.query` for projected JSON pages and nested filters
+  without URL array encoding; `data.batchQuery` for bounded independent pages.
+- Updated runtime OpenAPI schema and exact public manifest. New methods require
+  the additive query/batch-query Runtime API; existing methods are unchanged.
+
 ## 1.4.0 - 2026-09-02
 
 ### Added

package/README.md

@@ -8,6 +8,19 @@ environment + runtime token` and does not expose control-plane resources.
 npm install @nsp-labs/agnostic-sdk
 ```
 
+## Projected and Batch Reads (1.5.0)
+
+`data.table(name).records.query({ fields: ['title'], filter, limit, cursor })`
+reads only requested technical fields plus id. JSON filters support the existing
+50-value `in` budget without URL-array encoding. Omit `fields` for full records.
+Changing fields or conditions requires a new cursor chain.
+
+`data.batchQuery([{ tableName: 'orders', query: { fields: ['status'], limit: 50 } }])`
+returns `{ results: [...] }` in request order, with independent page cursors.
+Limits: 20 queries, 1000 requested rows total, default 50 rows/query. One failed
+query fails the batch; reads are not a transactional snapshot. Requires the
+additive query/batch-query Runtime API and `data.read`. Old methods are unchanged.
+
 ## Context
 
 Inside managed runtime, context is resolved automatically:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsp-labs/agnostic-sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Server-side Runtime SDK for Agnostic project services, workers, automations, and trusted local scripts.",
   "license": "ISC",
   "type": "commonjs",

package/src/generated/openapi.d.ts

@@ -38,6 +38,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/runtime/data/tables/{tableName}/records/query": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Read one projected Data page using a JSON query */
+        post: operations["runtimeDataQueryRecords"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/runtime/data/records/batch-query": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Read bounded independent Data pages in the runtime scope */
+        post: operations["runtimeDataBatchQueryRecords"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/runtime/data/tables/{tableName}/records/aggregate": {
         parameters: {
             query?: never;
@@ -835,6 +869,55 @@ export interface components {
             capabilities: string[];
             actor?: components["schemas"]["RuntimeActorMetadataDto"] | null;
         };
+        RuntimeDataBatchQueryDto: {
+            /** @description Independent read-only pages; sum of requested page limits must not exceed 1000 (default 50 per page). */
+            queries: components["schemas"]["RuntimeDataBatchQueryItemDto"][];
+        };
+        RuntimeDataBatchQueryItemDto: {
+            /** @example orders */
+            tableName: string;
+            query: components["schemas"]["RuntimeDataQueryDto"];
+        };
+        RuntimeDataBatchResultDto: {
+            /** @description Pages in request order, each with its own cursor. Not a transactional snapshot. Any failed query fails the whole request. */
+            results: components["schemas"]["DataRecordsListDto"][];
+        };
+        RuntimeDataQueryDto: {
+            /** @example 50 */
+            limit?: number;
+            /**
+             * @description Opaque versioned pagination cursor bound to this exact query. Legacy offset cursors are temporarily accepted.
+             * @example k1.b3BhcXVlLWl2.b3BhcXVlLXBheWxvYWQ.b3BhcXVlLXRhZw
+             */
+            cursor?: string;
+            /**
+             * @description Search text applied across searchable text columns
+             * @example alex
+             */
+            q?: string;
+            /** @example created_at:desc */
+            sort?: string;
+            /**
+             * @example {
+             *       "id": {
+             *         "in": [
+             *           "record-a",
+             *           "record-b"
+             *         ]
+             *       }
+             *     }
+             */
+            filter?: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description Technical field names to read. Record id is always included. Omit for all fields.
+             * @example [
+             *       "title"
+             *     ]
+             */
+            fields?: string[];
+        };
         RuntimeStartWorkflowDto: {
             /**
              * @example {
@@ -1070,6 +1153,82 @@ export interface operations {
             };
         };
     };
+    runtimeDataQueryRecords: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                tableName: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RuntimeDataQueryDto"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DataRecordsListDto"];
+                };
+            };
+            /** @description Invalid runtime token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing runtime capability */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    runtimeDataBatchQueryRecords: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RuntimeDataBatchQueryDto"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RuntimeDataBatchResultDto"];
+                };
+            };
+            /** @description Invalid runtime token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing runtime capability */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     runtimeDataAggregateRecords: {
         parameters: {
             query?: never;

package/src/index.d.ts

@@ -2,4 +2,4 @@ export { AgnosticRuntime, RuntimeAppAuthNamespace, RuntimeContextNamespace, Runt
 export { normalizeApiUrl, resolveRuntimeContext } from './lib/context';
 export { AgnosticRuntimeError } from './lib/errors';
 export { AGNOSTIC_RUNTIME_SDK_MANIFEST, type AgnosticRuntimeSdkManifest, } from './lib/manifest';
-export type { AgnosticRuntimeConfig, RuntimeAggregateMetric, RuntimeAggregateOperation, RuntimeAggregateOrderBy, RuntimeAggregateRecordsInput, RuntimeAggregateRecordsResult, RuntimeAggregateRow, ResolvedRuntimeContext, RuntimeActorMetadata, RuntimeActorType, RuntimeAnonymousClaimFileHandle, RuntimeAnonymousClaimInput, RuntimeAnonymousClaimResult, RuntimeAppAuthActor, RuntimeAppAuthCachePolicy, RuntimeAppAuthRequestLike, RuntimeAppAuthSession, RuntimeAppAuthSessionClaims, RuntimeAppAuthUserClaims, RuntimeAppAuthUserResult, RuntimeCreateRecordInput, RuntimeCreateFileUploadInput, RuntimeDataField, RuntimeDataViewState, RuntimeIdentityContext, RuntimeFileAccessMode, RuntimeFileDownloadUrl, RuntimeFileObject, RuntimeFileObjectStatus, RuntimeFileUploadCompletion, RuntimeFileUploadGrant, RuntimeListRecordsOptions, RuntimeListWindowOptions, RuntimeRecord, RuntimeRecordMutation, RuntimeRecordsList, RuntimeRequestOptions, RuntimeRowData, RuntimeRowValue, RuntimeTableWindow, RuntimeUpdateRecordInput, RuntimeWorkflowRun, RuntimeWorkflowStepRun, RuntimeWorkflowWaitOptions, WorkflowRunStatus, } from './lib/types';
+export type { RuntimeQueryRecordsInput, RuntimeBatchQueryItem, RuntimeBatchQueryResult, AgnosticRuntimeConfig, RuntimeAggregateMetric, RuntimeAggregateOperation, RuntimeAggregateOrderBy, RuntimeAggregateRecordsInput, RuntimeAggregateRecordsResult, RuntimeAggregateRow, ResolvedRuntimeContext, RuntimeActorMetadata, RuntimeActorType, RuntimeAnonymousClaimFileHandle, RuntimeAnonymousClaimInput, RuntimeAnonymousClaimResult, RuntimeAppAuthActor, RuntimeAppAuthCachePolicy, RuntimeAppAuthRequestLike, RuntimeAppAuthSession, RuntimeAppAuthSessionClaims, RuntimeAppAuthUserClaims, RuntimeAppAuthUserResult, RuntimeCreateRecordInput, RuntimeCreateFileUploadInput, RuntimeDataField, RuntimeDataViewState, RuntimeIdentityContext, RuntimeFileAccessMode, RuntimeFileDownloadUrl, RuntimeFileObject, RuntimeFileObjectStatus, RuntimeFileUploadCompletion, RuntimeFileUploadGrant, RuntimeListRecordsOptions, RuntimeListWindowOptions, RuntimeRecord, RuntimeRecordMutation, RuntimeRecordsList, RuntimeRequestOptions, RuntimeRowData, RuntimeRowValue, RuntimeTableWindow, RuntimeUpdateRecordInput, RuntimeWorkflowRun, RuntimeWorkflowStepRun, RuntimeWorkflowWaitOptions, WorkflowRunStatus, } from './lib/types';

package/src/lib/manifest.d.ts

@@ -9,7 +9,7 @@ export declare const AGNOSTIC_RUNTIME_SDK_MANIFEST: Readonly<{
     readonly schema: "agnostic_runtime_sdk_manifest.v1";
     readonly package: Readonly<{
         name: "@nsp-labs/agnostic-sdk";
-        version: "1.4.0";
+        version: "1.5.0";
         factory: "createAgnosticRuntime";
         runtime: "server_only";
     }>;
@@ -23,7 +23,7 @@ export declare const AGNOSTIC_RUNTIME_SDK_MANIFEST: Readonly<{
     readonly namespaces: Readonly<{
         auth: readonly ("requireSession" | "getSession" | "requireScopes" | "getUser")[];
         context: readonly "get"[];
-        data: readonly ("table(name).records.delete" | "table(name).records.list" | "table(name).records.aggregate" | "table(name).records.create" | "table(name).records.update" | "view(id).table.window")[];
+        data: readonly ("batchQuery" | "table(name).records.delete" | "table(name).records.query" | "table(name).records.list" | "table(name).records.aggregate" | "table(name).records.create" | "table(name).records.update" | "view(id).table.window")[];
         storage: readonly ("bucket(name).get" | "bucket(name).delete" | "bucket(name).createUpload" | "bucket(name).completeUpload" | "bucket(name).createDownloadUrl" | "bucket(name).anonymousUploads.claim")[];
         workflows: readonly ("start" | "getRun")[];
         workflowRuns: readonly ("get" | "wait" | "listSteps")[];

package/src/lib/manifest.js

@@ -11,12 +11,13 @@ const AUTH_KEYS_LITERAL = [
 const AUTH_KEYS = AUTH_KEYS_LITERAL;
 const CONTEXT_KEYS_LITERAL = ['get'];
 const CONTEXT_KEYS = CONTEXT_KEYS_LITERAL;
-const DATA_NAMESPACE_KEYS_LITERAL = ['table', 'view'];
+const DATA_NAMESPACE_KEYS_LITERAL = ['table', 'view', 'batchQuery'];
 const DATA_NAMESPACE_KEYS = DATA_NAMESPACE_KEYS_LITERAL;
 const DATA_TABLE_KEYS_LITERAL = ['records'];
 const DATA_TABLE_KEYS = DATA_TABLE_KEYS_LITERAL;
 const DATA_RECORD_KEYS_LITERAL = [
     'list',
+    'query',
     'aggregate',
     'create',
     'update',
@@ -51,6 +52,7 @@ const NAMESPACES = Object.freeze({
     data: Object.freeze([
         ...DATA_RECORD_KEYS.map((method) => `${DATA_NAMESPACE_KEYS[0]}(name).${DATA_TABLE_KEYS[0]}.${method}`),
         ...DATA_VIEW_TABLE_KEYS.map((method) => `${DATA_NAMESPACE_KEYS[1]}(id).${DATA_VIEW_KEYS[0]}.${method}`),
+        DATA_NAMESPACE_KEYS[2],
     ]),
     storage: Object.freeze([
         ...STORAGE_BUCKET_KEYS.filter((method) => method !== 'anonymousUploads').map((method) => `${STORAGE_NAMESPACE_KEYS[0]}(name).${method}`),
@@ -68,7 +70,7 @@ const MANIFEST_CONTRACT = Object.freeze({
     schema: 'agnostic_runtime_sdk_manifest.v1',
     package: Object.freeze({
         name: '@nsp-labs/agnostic-sdk',
-        version: '1.4.0',
+        version: '1.5.0',
         factory: 'createAgnosticRuntime',
         runtime: 'server_only',
     }),

package/src/lib/runtime-client.d.ts

@@ -1,5 +1,5 @@
 import { type RuntimeOpenApiClient } from './http-client';
-import type { AgnosticRuntimeConfig, ResolvedRuntimeContext, RuntimeAppAuthRequestLike, RuntimeAppAuthSession, RuntimeAppAuthUserResult, RuntimeAnonymousClaimInput, RuntimeAnonymousClaimResult, RuntimeAggregateRecordsInput, RuntimeAggregateRecordsResult, RuntimeCreateFileUploadInput, RuntimeCreateRecordInput, RuntimeIdentityContext, RuntimeFileDownloadUrl, RuntimeFileObject, RuntimeFileUploadCompletion, RuntimeFileUploadGrant, RuntimeListRecordsOptions, RuntimeListWindowOptions, RuntimeRecordMutation, RuntimeRecordsList, RuntimeRequestOptions, RuntimeRowData, RuntimeTableWindow, RuntimeUpdateRecordInput, RuntimeWorkflowRun, RuntimeWorkflowStepRun, RuntimeWorkflowWaitOptions } from './types';
+import type { AgnosticRuntimeConfig, ResolvedRuntimeContext, RuntimeAppAuthRequestLike, RuntimeAppAuthSession, RuntimeAppAuthUserResult, RuntimeAnonymousClaimInput, RuntimeAnonymousClaimResult, RuntimeAggregateRecordsInput, RuntimeAggregateRecordsResult, RuntimeCreateFileUploadInput, RuntimeCreateRecordInput, RuntimeIdentityContext, RuntimeFileDownloadUrl, RuntimeFileObject, RuntimeFileUploadCompletion, RuntimeFileUploadGrant, RuntimeListRecordsOptions, RuntimeQueryRecordsInput, RuntimeBatchQueryItem, RuntimeBatchQueryResult, RuntimeListWindowOptions, RuntimeRecordMutation, RuntimeRecordsList, RuntimeRequestOptions, RuntimeRowData, RuntimeTableWindow, RuntimeUpdateRecordInput, RuntimeWorkflowRun, RuntimeWorkflowStepRun, RuntimeWorkflowWaitOptions } from './types';
 export declare class AgnosticRuntime {
     readonly auth: RuntimeAppAuthNamespace;
     readonly context: RuntimeContextNamespace;
@@ -31,6 +31,7 @@ export declare class RuntimeDataNamespace {
     constructor(openapi: RuntimeOpenApiClient);
     table(tableName: string): RuntimeDataTableClient;
     view(viewId: string): RuntimeDataViewClient;
+    batchQuery(queries: RuntimeBatchQueryItem[], options?: RuntimeRequestOptions): Promise<RuntimeBatchQueryResult>;
 }
 export declare class RuntimeStorageNamespace {
     private readonly openapi;
@@ -64,6 +65,7 @@ export declare class RuntimeDataRecordsClient {
     private readonly tableName;
     constructor(openapi: RuntimeOpenApiClient, tableName: string);
     list(query?: RuntimeListRecordsOptions, options?: RuntimeRequestOptions): Promise<RuntimeRecordsList>;
+    query(input?: RuntimeQueryRecordsInput, options?: RuntimeRequestOptions): Promise<RuntimeRecordsList>;
     aggregate(input: RuntimeAggregateRecordsInput, options?: RuntimeRequestOptions): Promise<RuntimeAggregateRecordsResult>;
     create(input: RuntimeCreateRecordInput | RuntimeRowData, options?: RuntimeRequestOptions): Promise<RuntimeRecordMutation>;
     update(recordId: string, input: RuntimeUpdateRecordInput | RuntimeRowData, options?: RuntimeRequestOptions): Promise<RuntimeRecordMutation>;

package/src/lib/runtime-client.js

@@ -9,6 +9,8 @@ const APP_AUTH_VERIFY_SESSION_PATH = '/api/v1/runtime/app-auth/session/verify';
 const APP_AUTH_USER_PATH = '/api/v1/runtime/app-auth/users/{userId}';
 const AUTH_CONTEXT_PATH = '/api/v1/runtime/auth/context';
 const DATA_RECORDS_PATH = '/api/v1/runtime/data/tables/{tableName}/records';
+const DATA_QUERY_PATH = '/api/v1/runtime/data/tables/{tableName}/records/query';
+const DATA_BATCH_QUERY_PATH = '/api/v1/runtime/data/records/batch-query';
 const DATA_AGGREGATE_PATH = '/api/v1/runtime/data/tables/{tableName}/records/aggregate';
 const DATA_RECORD_PATH = '/api/v1/runtime/data/tables/{tableName}/records/{recordId}';
 const DATA_VIEW_WINDOW_PATH = '/api/v1/runtime/data/views/{viewId}/table/window';
@@ -138,6 +140,13 @@ class RuntimeDataNamespace {
     view(viewId) {
         return new RuntimeDataViewClient(this.openapi, viewId);
     }
+    async batchQuery(queries, options) {
+        const result = await this.openapi.POST(DATA_BATCH_QUERY_PATH, {
+            body: { queries },
+            headers: (0, http_client_1.runtimeRequestHeaders)(options),
+        });
+        return (0, http_client_1.unwrapRuntimeResult)(result, 'Failed to batch query data records');
+    }
 }
 exports.RuntimeDataNamespace = RuntimeDataNamespace;
 class RuntimeStorageNamespace {
@@ -232,6 +241,14 @@ class RuntimeDataRecordsClient {
         });
         return (0, http_client_1.unwrapRuntimeResult)(result, 'Failed to list data records');
     }
+    async query(input = {}, options) {
+        const result = await this.openapi.POST(DATA_QUERY_PATH, {
+            body: input,
+            headers: (0, http_client_1.runtimeRequestHeaders)(options),
+            params: { path: { tableName: this.tableName } },
+        });
+        return (0, http_client_1.unwrapRuntimeResult)(result, 'Failed to query data records');
+    }
     async aggregate(input, options) {
         const result = await this.openapi.POST(DATA_AGGREGATE_PATH, {
             body: input,

package/src/lib/types.d.ts

@@ -159,6 +159,18 @@ export interface RuntimeListRecordsOptions {
     sort?: string;
 }
 export type RuntimeAggregateOperation = 'count' | 'sum' | 'avg' | 'min' | 'max';
+export interface RuntimeQueryRecordsInput extends RuntimeListRecordsOptions {
+    /** Technical names; id is always included. Omit to read all fields. */
+    fields?: string[];
+}
+export interface RuntimeBatchQueryItem {
+    tableName: string;
+    query: RuntimeQueryRecordsInput;
+}
+export interface RuntimeBatchQueryResult {
+    /** Independent pages, in request order; no shared transactional snapshot. */
+    results: RuntimeRecordsList[];
+}
 export interface RuntimeAggregateMetric {
     operation: RuntimeAggregateOperation;
     field?: string;