Platform guide

Stacksona for Node and TypeScript

Q: What statuses should my workflow allow?

Execute the gated action only on allow or approved. Stop, retry, notify, or route to fallback for every other state.

Use @stacksona/sdk inside custom agents, backend services, workers, API routes, and sidecars.

Native SDKPackage: @stacksona/sdkVersion: 0.2.0

Use the SDK inside custom agents, backend services, workers, API routes, and bridge services for platforms that do not have a native Stacksona package.

Use your own Gate URL and agent key

STACKSONA_GATE_URL is the Gate endpoint from your Stacksona workspace or deployment. STACKSONA_API_KEY is the sg_ agent key for the agent making requests.

Fast path: request approval from code

1
Install.
npm install @stacksona/sdk
2
Create the client.
Use your Gate URL and API key from environment variables.
3
Request a decision before the tool executes.
Only run the risky function when Stacksona returns allow or a later approved decision.

import { StacksonaGateClient } from '@stacksona/sdk';

const gate = new StacksonaGateClient({
  baseUrl: process.env.STACKSONA_GATE_URL!,
  apiKey: process.env.STACKSONA_API_KEY!
});

const decision = await gate.requestDecision('task_123', {
  workflow_name: 'Support Agent',
  task_label: 'Approve customer email',
  tool_name: 'send_email',
  subject: 'Send reply to customer@example.com',
  preview: 'Agent drafted a customer-facing support reply.',
  risk_level: 'medium'
});

if (decision.status === 'allow' || decision.status === 'approved') {
  await sendEmail();
}

Use it for

Custom agents

Wrap risky tool functions before they execute.

Backend services

Require approval before production writes, refunds, deletes, or external messages.

Platform sidecars

Expose a small HTTP approval bridge to Python frameworks, enterprise builders, and no-code tools.

Run a gated action

Use a gated wrapper when you want the approval check and action execution near each other in code.

await gate.runGatedAction('task_123', {
  workflow_name: 'Billing Agent',
  task_label: 'Refund approval',
  tool_name: 'issue_refund',
  subject: 'Issue refund for invoice INV-1042',
  risk_level: 'high'
}, async () => {
  return issueRefund({ invoiceId: 'INV-1042', amount: 12900 });
});

Branch behavior

Status	What your code should do
`allow`	Execute immediately.
`pending_review`	Return pending to the caller, poll, or resume through a callback.
`approved`	Execute after review.
`reject` or `rejected`	Do not execute.

Integration FAQ

Can I use Stacksona with Node and TypeScript today?

Yes. Use the documented native package when one exists. Otherwise, use the REST API, HTTP module, webhook action, or a small Node sidecar with @stacksona/sdk.

Where should Stacksona sit in a Node and TypeScript workflow?

Place Stacksona immediately before the action that sends, updates, deletes, refunds, posts, deploys, or calls a production API.

What statuses should my workflow allow?

Execute the gated action only on allow or approved. Stop, retry, notify, or route to fallback for every other state.