TypeScript SDK

Status: The SDK is source-available in the Praxa repository and its durable-task methods work with the production partner-preview gateway. It is not published to npm. Webhook methods are active for admitted personal tenants. Exact approval remains pending its production canary. Cancellation final-state behavior has passed separate production canaries for the pre-dispatch and provider-in-flight branches.

@nexislabs/ai-platform is a runtime-neutral client for the served Praxa Execution Fabric v1 task boundary. It uses Fetch and ReadableStream and has no Expo, React, React Native, Supabase, provider, database, or tool-execution dependency. The public client surface is task-only. POST /v1/execute accepts mode: "task"; mode: "turn" returns 400 invalid_request, and /v1/chat is not routed. Candidate turn schemas in the source repository are offline contracts, not public client methods.

Install status

The package is not published to npm. In-repo consumers resolve it through the Praxa monorepo’s TypeScript path alias. External consumers must wait for an official package release or vendor the reviewed source package deliberately. The source package is ESM-only, version-locked at 0.1.0, and requires Node.js 20 or later.

Construct the client

import { AiPlatformClient } from "@nexislabs/ai-platform";

const client = new AiPlatformClient({
  baseUrl: "https://api.praxa.io",
  accessToken: () => process.env.PRAXA_API_KEY ?? null,
});

baseUrl must be HTTPS, except for loopback development hosts. accessToken may be a string or a function that returns the current token. The client resolves it for every request. You may inject a Fetch implementation when the runtime does not provide one.

Start and follow a task

const run = await client.execute({
  apiVersion: "v1",
  requestId: crypto.randomUUID(),
  mode: "task",
  task: {
    input: "Summarize the incident and propose the next safe action.",
  },
  idempotencyKey: crypto.randomUUID(),
});

for await (const event of client.streamRunEvents(run.run_id)) {
  console.log(event.sequence, event.type);
}

The execute request is strict. It accepts only apiVersion, requestId, mode, task.input, and optional idempotencyKey. Agent selection, context, tools, policy, delivery, mode: "turn", and unknown fields fail validation. Use getRun() when polling fits your application:

const current = await client.getRun(run.run_id);
console.log(current.status);

Cancel a task

const current = await client.cancelRun(run.run_id);
console.log(current.status);

cancelRun() sends the exact body {}. It accepts no reason or options object. Cancellation is cooperative, so the returned run may still be running. Continue reading the run or event stream until a terminal status appears.

Decide an exact approval after activation

Activation status: Source-ready, with compatible Worker code deployed. Required production database activation and authenticated approval canaries remain pending.

An exact recorded browser action can expose pendingApproval and emit approval.required only when Praxa can bind the displayed summary to the stored action digest. Render the supplied summary unchanged and return the same digest:

if (event.type === "approval.required") {
  renderApproval(event.summary, {
    onApprove: () => client.approveRun(event.run_id, event.action_digest),
    onDeny: () => client.denyRun(event.run_id, event.action_digest),
  });
}

Both methods return the updated run. Missing, stale, unsupported, foreign, or mismatched approvals fail closed.

Read usage

const usage = await client.getUsage({
  from: "2026-08-01T00:00:00.000Z",
  to: "2026-08-02T00:00:00.000Z",
  groupBy: "hour",
});

Usage is tenant-scoped evidence. It is not invoice or reservation authority.

Manage webhooks

Status: Production partner preview for admitted personal tenants. A live delivery canary verified the HMAC against the exact raw request body.

const created = await client.createWebhookEndpoint({
  url: "https://example.com/hooks/praxa",
  event_types: ["run.completed", "run.failed"],
  description: "Production run events",
});

const endpoints = await client.listWebhookEndpoints();
const deliveries = await client.listWebhookDeliveries({
  endpointId: created.endpoint.id,
  status: "dead_letter",
  limit: 50,
});

The source client also provides updateWebhookEndpoint(), deleteWebhookEndpoint(), and replayWebhookDelivery(). Reads require runs:read. Create, update, delete, and replay require both runs:read and runs:write at the authoritative backend. The signing secret is returned only when an endpoint is created.

Public client methods

Method	Purpose
`execute()`	Admit one strict durable task.
`getRun()`	Read a tenant-owned run projection.
`streamRunEvents()`	Consume or resume a durable run’s SSE feed.
`approveRun()`	After activation, approve the exact pending action digest.
`denyRun()`	After activation, deny the exact pending action digest.
`cancelRun()`	Send the exact `{}` cancellation request.
`getUsage()`	Read tenant-scoped usage evidence.
`listWebhookEndpoints()`	List endpoint metadata.
`createWebhookEndpoint()`	Create an endpoint and receive its secret once.
`updateWebhookEndpoint()`	Update an endpoint.
`deleteWebhookEndpoint()`	Disable an endpoint.
`listWebhookDeliveries()`	List delivery attempts.
`replayWebhookDelivery()`	Replay an eligible dead-letter delivery.

Stream guarantees

streamRunEvents() verifies that every event belongs to the requested run, that every numeric SSE id equals the payload sequence, and that sequences increase. The stream must end with run.completed, run.failed, or run.cancelled. EOF before a terminal event throws. Continue with Streaming events for reconnection and Errors and retries for retry behavior.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

TypeScript SDK

Install status

Construct the client

Start and follow a task

Cancel a task

Decide an exact approval after activation

Read usage

Manage webhooks

Public client methods

Stream guarantees

​Install status

​Construct the client

​Start and follow a task

​Cancel a task

​Decide an exact approval after activation

​Read usage

​Manage webhooks

​Public client methods

​Stream guarantees

Install status

Construct the client

Start and follow a task

Cancel a task

Decide an exact approval after activation

Read usage

Manage webhooks

Public client methods

Stream guarantees