@nsp-labs/agnostic-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@nsp-labs/agnostic-sdk` are recorded here.
+
+This package follows the Runtime SDK release policy in
+`docs/shared/runtime-sdk-release.md`. Every published package version must move
+entries out of `Unreleased`, include the runtime API/schema compatibility note,
+and pass the runtime OpenAPI schema check.
+
+## Unreleased
+
+- Prepared npm package metadata for `@nsp-labs/agnostic-sdk`.
+- Added CI coverage for generated Runtime SDK OpenAPI schema drift.
+- Documented Runtime SDK semver, changelog, and browser-token security policy.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Newsmart Pro
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# @nsp-labs/agnostic-sdk
+
+TypeScript Runtime SDK for server-side code running inside an Agnostic project
+runtime or trusted local scripts. It is scoped to one `projectId +
+environment + runtime token` and does not expose control-plane resources.
+
+```bash
+npm install @nsp-labs/agnostic-sdk
+```
+
+## Context
+
+Inside managed runtime, context is resolved automatically:
+
+```text
+AGNOSTIC_API_URL=
+AGNOSTIC_PROJECT_ID=
+AGNOSTIC_ENVIRONMENT=
+AGNOSTIC_RUNTIME_TOKEN=
+```
+
+Local scripts can pass the same context explicitly:
+
+```ts
+import { createAgnosticRuntime } from '@nsp-labs/agnostic-sdk';
+
+const agnostic = createAgnosticRuntime({
+  apiUrl: 'https://api.agn0.ru',
+  projectId: 'proj_123',
+  environment: 'production',
+  token: process.env.AGNOSTIC_RUNTIME_TOKEN,
+});
+```
+
+Runtime tokens are server-side credentials. Do not put
+`AGNOSTIC_RUNTIME_TOKEN` in browser, mobile, Vite, or static frontend bundles.
+
+## App Auth
+
+Use `agnostic.auth.requireSession(request)` in an application backend to verify
+the incoming App Auth session through the runtime helper:
+
+```ts
+const session = await agnostic.auth.requireSession(request);
+
+await agnostic.events.publish(
+  'order.updated',
+  { orderId: 'order_123' },
+  { actor: session.actor },
+);
+```
+
+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.
+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.
+
+## Data
+
+```ts
+const orders = await agnostic.data.table('orders').records.list({
+  filter: { status: 'paid' },
+  limit: 50,
+});
+
+const created = await agnostic.data.table('orders').records.create({
+  values: {
+    customerId: 'cust_123',
+    status: 'paid',
+  },
+});
+
+await agnostic.data.table('orders').records.update(created.id, {
+  status: 'fulfilled',
+});
+
+await agnostic.data.table('orders').records.delete(created.id);
+```
+
+## Events
+
+```ts
+await agnostic.events.publish('order.fulfilled', {
+  orderId: 'order_123',
+  customerId: 'cust_123',
+});
+
+await agnostic.events.publishBatch('order.fulfilled', [
+  { payload: { orderId: 'order_123' } },
+  { payload: { orderId: 'order_124' } },
+]);
+```
+
+## Jobs
+
+```ts
+await agnostic.jobs.enqueue(
+  'send-receipt',
+  { orderId: 'order_123' },
+  { delaySeconds: 30 },
+);
+```
+
+## Gateway
+
+```ts
+const result = await agnostic.gateway.call('billing/create-invoice', {
+  orderId: 'order_123',
+});
+
+if (result.status >= 400) {
+  throw new Error('Gateway route failed');
+}
+```
+
+## Workflows
+
+```ts
+const run = await agnostic.workflows.start('send-receipt', {
+  orderId: 'order_123',
+});
+
+const finished = await agnostic.workflowRuns.wait(run.id, {
+  timeoutMs: 30_000,
+});
+```
+
+## Actor Metadata
+
+After an application backend has verified its App Auth session and business
+guardrails, it can pass actor metadata for audit context:
+
+```ts
+await agnostic.events.publish(
+  'order.updated',
+  { orderId: 'order_123' },
+  {
+    actor: {
+      type: 'app_user',
+      id: 'app_user_123',
+      scopes: ['orders:write'],
+    },
+  },
+);
+```
+
+Allowed actor types are `app_user`, `platform_user`, `runtime`, and `system`.
+Actor metadata is not authorization input for Runtime SDK capabilities.
+
+## Errors
+
+Runtime API failures throw `AgnosticRuntimeError`:
+
+```ts
+import { AgnosticRuntimeError } from '@nsp-labs/agnostic-sdk';
+
+try {
+  await agnostic.data.table('orders').records.list();
+} catch (error) {
+  if (error instanceof AgnosticRuntimeError) {
+    console.error(error.status, error.code, error.message, error.details);
+  }
+}
+```
+
+## OpenAPI Layer
+
+`src/generated/openapi.ts` is generated from `/api/docs-json` after filtering to
+`/api/v1/runtime/*` paths:
+
+```bash
+npm run sdk:gen
+```
+
+CI validates the committed generated layer with:
+
+```bash
+npm run sdk:check
+```
+
+The generated client is internal. Public code should use
+`createAgnosticRuntime` and the ergonomic namespaces above.
+
+## Versioning And Changelog
+
+`@nsp-labs/agnostic-sdk` follows semver with the Runtime SDK API contract. Breaking
+runtime endpoint or public SDK changes require a major version;
+backwards-compatible namespaces, methods, options, or response fields are minor
+changes; bug fixes and generated type refreshes without API changes are patch
+changes.
+
+Release notes are tracked in `CHANGELOG.md`. Do not publish a package version
+unless the changelog is updated and `npm run sdk:check` passes.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@nsp-labs/agnostic-sdk",
+  "version": "0.1.0",
+  "description": "Server-side Runtime SDK for Agnostic project services, workers, automations, and trusted local scripts.",
+  "license": "ISC",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "!src/**/*.js.map",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.18"
+  },
+  "keywords": [
+    "agnostic",
+    "runtime-sdk",
+    "server-side",
+    "workflow",
+    "data"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "ssh://ssh.sourcecraft.dev/newsmartpro/nsplabs-agnostic-core.git",
+    "directory": "packages/sdk-js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.17.0",
+    "tslib": "^2.3.0"
+  }
+}