@nsp-labs/agnostic-sdk 1.1.0 → 1.5.0

package/CHANGELOG.md

@@ -9,6 +9,64 @@ 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
+
+- Added `data.table(name).records.aggregate(...)` for bounded server-side
+  `count`, `sum`, `avg`, `min`, and `max` queries with filters, search, up to
+  two grouping dimensions, ordering, and a capped result size.
+
+### Changed
+
+- Regenerated the Runtime OpenAPI client with the backwards-compatible Data
+  aggregate endpoint. The runtime identity remains the only source of project
+  and environment scope.
+
+## 1.3.0 - 2026-08-12
+
+### Added
+
+- Added `storage.bucket(name).createUpload`, `completeUpload`, `get`,
+  `createDownloadUrl`, and `delete` with project/environment/runtime-owner
+  binding and stable Files errors.
+- Added the canonical `files.read`, `files.write`, `files.delete`, and
+  `files.links.create` Runtime API capability mapping.
+
+### Changed
+
+- Regenerated the Runtime OpenAPI client for the complete Files facade while
+  keeping provider bucket names, object keys, and credentials outside public
+  types.
+- Bumped the compatible server-only SDK contract to `1.3.0`; existing runtime
+  paths remain backwards compatible.
+
+## 1.2.0 - 2026-08-10
+
+### Added
+
+- Added the server-only
+  `storage.bucket(name).anonymousUploads.claim(...)` helper and its Runtime API
+  schema for idempotent anonymous session claim with ready/processing handles.
+
+### Changed
+
+- Clarified in the exported Runtime SDK manifest that App Auth self-service
+  profile mutations use the public App Auth API through the project backend/BFF;
+  they are not runtime-token mutations and do not expand the callable SDK
+  surface.
+- Generated the runtime OpenAPI layer with the backwards-compatible Files claim
+  endpoint; existing Runtime API paths are unchanged.
+
 ## 1.1.0 - 2026-07-26
 
 ### 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:
@@ -36,7 +49,8 @@ Runtime tokens are server-side credentials. Do not put
 `AGNOSTIC_RUNTIME_TOKEN` in browser, mobile, Vite, or static frontend bundles.
 
 The current public runtime surface includes `auth`, `context`, `data`,
-`workflows`, and `workflowRuns`.
+`storage`, `workflows`, and `workflowRuns`. `storage.bucket(name)` supports the
+server-side Files lifecycle and anonymous upload claim.
 
 ## App Auth
 
@@ -80,6 +94,15 @@ It returns sanitized user/session claims and an `app_user` actor for audit
 metadata. `agnostic.auth.getUser(userId)` reads sanitized App Auth user claims
 for the same runtime project.
 
+For a browser frontend and backend deployed on different hosts, login must use
+the application backend/BFF. The BFF requests bearer mode from App Auth and
+places the tokens in host-only HttpOnly cookies on its own host before calling
+`requireSession(request)`. A host-only cookie set by `api.agn0.ru` is not sent
+to an application backend host. Do not solve this with `Domain=.agn0.ru` or
+browser token storage. For cross-origin frontend/backend pairs, return a
+separate non-secret CSRF token from the BFF and validate it on state-changing
+cookie-authenticated requests.
+
 ## Data
 
 ```ts
@@ -88,6 +111,17 @@ const orders = await agnostic.data.table('orders').records.list({
   limit: 50,
 });
 
+const revenueByStatus = await agnostic.data.table('orders').records.aggregate({
+  filter: { currency: 'RUB' },
+  groupBy: ['status'],
+  metrics: [
+    { operation: 'count', as: 'orders' },
+    { operation: 'sum', field: 'amount', as: 'revenue' },
+  ],
+  orderBy: [{ by: 'revenue', direction: 'desc' }],
+  limit: 20,
+});
+
 const created = await agnostic.data.table('orders').records.create({
   values: {
     customerId: 'cust_123',
@@ -102,6 +136,10 @@ await agnostic.data.table('orders').records.update(created.id, {
 await agnostic.data.table('orders').records.delete(created.id);
 ```
 
+Aggregate queries support `count`, `sum`, `avg`, `min`, and `max`. They are
+executed by the data provider, allow at most two grouping fields, return at
+most 100 groups, and require the existing `data.read` capability.
+
 ## Workflows
 
 ```ts
@@ -114,6 +152,55 @@ const finished = await agnostic.workflowRuns.wait(run.id, {
 });
 ```
 
+## Anonymous File Claim
+
+After creating the business object, claim the anonymous upload session from the
+application backend. Reuse the same `externalRef` and `idempotencyKey` for saga
+retries:
+
+```ts
+const attachments = await agnostic.storage
+  .bucket('order-files')
+  .anonymousUploads.claim({
+    token: attachmentSessionToken,
+    externalRef: `order:${order.id}`,
+    idempotencyKey: `order:${order.id}`,
+  });
+```
+
+The runtime token and anonymous claim token must remain server-side. The result
+contains server-selected `ready` or `processing` file handles; callers do not
+submit file IDs.
+
+## Files
+
+```ts
+const bucket = agnostic.storage.bucket('uploads');
+const upload = await bucket.createUpload({
+  fileName: 'invoice.pdf',
+  contentType: 'application/pdf',
+  size: contents.byteLength,
+  checksumSha256,
+  access: 'private',
+  idempotencyKey: `invoice:${invoice.id}:v1`,
+});
+
+await fetch(upload.uploadUrl, {
+  method: 'PUT',
+  headers: upload.requiredHeaders,
+  body: contents,
+});
+
+const completed = await bucket.completeUpload(upload.id);
+const file = await bucket.get(completed.file.id);
+const download = await bucket.createDownloadUrl(file.id);
+await bucket.delete(file.id);
+```
+
+Reuse the same idempotency key and IDs when retrying. Keep the SDK and runtime
+token server-side; only a short scoped upload/download URL may cross into a
+browser after the application has authorized the request.
+
 ## Actor Metadata
 
 After an application backend has verified its App Auth session and business

package/package.json

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