@nsp-labs/agnostic-sdk 1.0.4 → 1.4.0

package/CHANGELOG.md

@@ -9,6 +9,73 @@ and pass the runtime OpenAPI schema check.
 
 ## Unreleased
 
+## 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
+
+- Added an exact public-surface drift guard and a deterministic manifest
+  fingerprint so Agent codegen can re-read the installed SDK contract on every
+  generation step instead of relying on a copied namespace list.
+- Added `auth.getSession()` for optional App Auth sessions and
+  `auth.requireScopes()` for application-level scope guardrails after session
+  verification.
+
+### Changed
+
+- Runtime SDK manifest consumers can now derive scaffold versions, Agent review
+  allowlists, and source-write deny rules from the exported package contract.
+  The runtime OpenAPI schema is unchanged; the callable SDK surface adds only
+  the backwards-compatible App Auth helpers listed above.
+
 ## 1.0.4 - 2026-06-18
 
 ### Changed

package/README.md

@@ -36,7 +36,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
 
@@ -46,13 +47,33 @@ the incoming App Auth session through the runtime helper:
 ```ts
 const session = await agnostic.auth.requireSession(request);
 
-await agnostic.data.table('orders').records.update(
-  'order_123',
-  { values: { status: 'fulfilled' } },
-  { actor: session.actor },
-);
+await agnostic.data
+  .table('orders')
+  .records.update(
+    'order_123',
+    { values: { status: 'fulfilled' } },
+    { actor: session.actor },
+  );
+```
+
+Use `getSession(request)` for routes that support both guests and signed-in
+users. It returns `null` when the request has no App Auth session:
+
+```ts
+const session = await agnostic.auth.getSession(request);
 ```
 
+Use `requireScopes(request, scopes)` for application-level scope guardrails.
+This verifies the session first and throws `app_auth_scope_missing` when one of
+the required app-user scopes is absent:
+
+```ts
+const session = await agnostic.auth.requireScopes(request, ['orders:write']);
+```
+
+Scope checks do not replace ownership or other business rules in the
+application backend.
+
 The helper extracts `Authorization: Bearer <app-session>` or an
 `agnostic_app_session_*` cookie, then calls
 `/api/v1/runtime/app-auth/session/verify` with the server-side runtime token.
@@ -60,6 +81,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
@@ -68,6 +98,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',
@@ -82,6 +123,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
@@ -94,6 +139,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.0.4",
+  "version": "1.4.0",
   "description": "Server-side Runtime SDK for Agnostic project services, workers, automations, and trusted local scripts.",
   "license": "ISC",
   "type": "commonjs",