Integrate Praxa with TypeScript

• use @praxa/sdk with a deployment-specific Integration Gateway;
• use Node.js fetch with the public Execution Fabric API.

​

Prerequisites

• Node.js 20 or newer
• TypeScript with ESM (NodeNext or ESNext)
• either a Gateway origin and delegated OAuth token, or a personal Execution Fabric API key

​

Path A: Integration Gateway SDK

npm install @praxa/sdk@0.3.0

import { randomUUID } from "node:crypto";
import { PraxaClient } from "@praxa/sdk";

const client = new PraxaClient({
  baseUrl: process.env.PRAXA_BASE_URL!,
  accessToken: () => process.env.PRAXA_ACCESS_TOKEN!,
});

const mission = await client.createMission(
  {
    goalSpec: { task: "Prepare the weekly review" },
    resourceBudget: {
      maximumSteps: 12,
      maximumToolCalls: 8,
      maximumElapsedMs: 120_000,
      maximumParallelism: 2,
    },
  },
  randomUUID(),
);

for await (const event of client.missionEvents(mission.runId)) {
  console.log(event.id, event.event);
}

console.log(await client.getMission(mission.runId));

​

Path B: Execution Fabric

import { createHash, randomUUID } from "node:crypto";

const apiKey = process.env.PRAXA_API_KEY;
if (!apiKey) throw new Error("PRAXA_API_KEY is required");

const logicalRequestId = randomUUID();
const idempotencyKey =
  "typescript:" + createHash("sha256").update(logicalRequestId).digest("hex");

const response = await fetch("https://api.praxa.io/v1/execute", {
  method: "POST",
  headers: {
    authorization: `Bearer ${apiKey}`,
    "content-type": "application/json",
    "idempotency-key": idempotencyKey,
  },
  body: JSON.stringify({
    apiVersion: "v1",
    requestId: idempotencyKey,
    mode: "task",
    task: { input: "Summarize the incident and propose the next safe action." },
    idempotencyKey,
  }),
});

if (!response.ok) {
  throw new Error(`Praxa admission failed with HTTP ${response.status}`);
}

const run = await response.json();
console.log(run.run_id, run.status);

​

Add a terminal readback

const terminal = new Set(["completed", "failed", "cancelled"]);
let current = run;

while (!terminal.has(current.status)) {
  await new Promise((resolve) => setTimeout(resolve, 1_000));
  const read = await fetch(
    `https://api.praxa.io/v1/runs/${encodeURIComponent(current.run_id)}`,
    {
      headers: { authorization: `Bearer ${apiKey}` },
      cache: "no-store",
    },
  );
  if (!read.ok) throw new Error(`Run read failed with HTTP ${read.status}`);
  current = await read.json();
}

​

Test with native fakes

• exact URL, method, header, and body;
• one stable key for repeated logical input;
• no token in returned values or logs;
• 401, 403, 409, 429, and network errors remain distinguishable;
• polling stops only at a public terminal state.

node --test

​

Troubleshooting

​

Best practices

• Reuse one configured SDK or HTTP client per process.
• Keep all credentials in the server runtime.
• Use AbortSignal and an overall deadline.
• Redact authorization and customer payloads from telemetry.
• Bound concurrency and respect 429 responses.
• Reconcile every ambiguous mutation through exact replay or readback.

​

Optimize for production

• Reuse one configured HTTP or SDK client per process and bound concurrent upstream work.
• Prefer durable admission plus asynchronous readback over holding application requests open.
• Cache only non-sensitive, tenant-scoped reads within their documented freshness window.
• Measure p50/p95 latency, admission-to-terminal time, retries, conflicts, and connection reuse before tuning.

​

Cleanup and next steps

1. Revoke the disposable Praxa key and require a later request to fail.
2. Remove synthetic application records and any temporary environment files.
3. Cancel or archive unresolved test runs according to the application policy.
4. Retain only redacted request, run, and verification identifiers needed for the test record.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?