@stacksona/sdk

TypeScript and JavaScript client for Stacksona Gate.

Install

npm install @stacksona/sdk

Requires Node.js 18 or newer.

Usage

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('order-1042', {
  tool_name: 'issue_refund',
  payload: { amount: 250, currency: 'usd' },
});

if (decision.status === 'allow') {
  await issueRefund({ amount: 250, currency: 'usd' });
}

if (decision.status === 'pending_review') {
  const reviewed = await gate.pollDecision({ thread_id: decision.thread_id });

  if (reviewed.status === 'approved') {
    await issueRefund({ amount: 250, currency: 'usd' });
  }
}

Use the thread_id returned by Gate when polling a review.

Methods

• resolveTools(tools)
• logEvent(taskId, event)
• requestDecision(taskId, request)
• getDecision(query)
• listDecisions(query)
• pollDecision(query, options)
• requestDecisionAndPoll(taskId, request, options)
• submitRevision(taskId, threadId, revision)
• validateApprovalToken(input)
• runGatedAction(taskId, request, action, options)

Tool contracts

const { tools, unregistered } = await gate.resolveTools([
  'issue_refund',
  'send_email',
]);

Gate returns each registered tool's input_schema. Validate generated arguments against that schema before execution.

Requested changes

A review can return changes_requested. Submit the revised call to the same thread:

await gate.submitRevision('order-1042', threadId, {
  tool_name: 'issue_refund',
  subject: 'Refund request',
  request_payload: { amount: 100, currency: 'usd' },
});

Signed approvals

validateApprovalToken() consumes a signed approval token. Always check the returned valid value.

runGatedAction() can require token validation before executing an approved call:

await gate.runGatedAction(taskId, request, execute, {
  validateSignedApprovalToken: true,
});

Documentation

https://docs.stacksona.com