@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.

npm install @nsp-labs/agnostic-sdk

Context

Inside managed runtime, context is resolved automatically:

AGNOSTIC_API_URL=
AGNOSTIC_PROJECT_ID=
AGNOSTIC_ENVIRONMENT=
AGNOSTIC_RUNTIME_TOKEN=

Local scripts can pass the same context explicitly:

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.

The current public runtime surface includes auth, context, data, workflows, and workflowRuns.

App Auth

Use agnostic.auth.requireSession(request) in an application backend to verify the incoming App Auth session through the runtime helper:

const session = await agnostic.auth.requireSession(request);

await agnostic.data.table('orders').records.update(
  'order_123',
  { values: { status: 'fulfilled' } },
  { 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

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);

Workflows

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:

await agnostic.workflows.start(
  'send-receipt',
  { 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:

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:

npm run sdk:gen

CI validates the committed generated layer with:

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.