Live package

@stacksona/sdk

TypeScript and JavaScript SDK for Stacksona Gate approvals, audit events, polling, signed token validation, revision events, and gated action execution.

Fast path: install and gate an action

1
Install.
npm install @stacksona/sdk
2
Create a client.
Read STACKSONA_GATE_URL and STACKSONA_API_KEY from environment variables.
3
Call Stacksona before execution.
Run the action only when the returned status is allow or approved.

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.

Package

Field	Value
Name	`@stacksona/sdk`
Version documented	`0.2.0`
Runtime	Node.js 18 or later
Main export	`StacksonaGateClient`
Use when	You control a Node.js or TypeScript agent, backend, worker, or sidecar.

bash

npm install @stacksona/sdk

Environment

bash

STACKSONA_GATE_URL=https://{gate-id}.stacksona.cloud
STACKSONA_API_KEY=sg_your_api_key

Run a gated action

const { decision, executed, result } = await gate.runGatedAction(
  {
    taskId: 'task-refund-8821',
    workflowName: 'Customer Support',
    taskLabel: 'Refund request for order #8821',
    toolName: 'issue_refund',
    subject: 'Issue refund of $500 to customer cus_99',
    riskLevel: 'high',
    summary: ['Customer requested refund', 'Order has no tracking movement'],
    payload: { amount: 500, currency: 'usd', customer_id: 'cus_99' },
  },
  async () => issueRefund({ amount: 500, currency: 'usd', customerId: 'cus_99' }),
  { validateSignedApprovalToken: true },
);

if (!executed) {
  console.log(`Action did not run: ${decision.status}`);
}

Main methods

Method	Purpose
`logEvent(input)`	Send task, workflow, or agent timeline context to Stacksona Gate.
`logRevision(input)`	Send a revision event to a pending review thread after reviewer feedback.
`requestDecision(input)`	Ask Gate to allow, reject, or create a review thread for a gated action.
`getDecision(query)`	Fetch decision status by `thread_id` or `task_id`.
`pollDecision(query, options)`	Poll until a pending decision becomes approved or rejected.
`requestDecisionAndPoll(input, options)`	Create a decision request and wait automatically when review is required.
`validateApprovalToken(input)`	Validate a signed one-time approval token before execution.
`runGatedAction(input, action, options)`	Execute the supplied function only after Gate allows or approves it.

Revision events

Use revisions when a reviewer asks the agent to modify a pending request instead of opening a new thread.

await gate.logRevision({
  taskId: 'task-refund-8821',
  threadId: 'THR-XXXXXXXX',
  revisionId: 'rev-002',
  workflowName: 'Customer Support',
  taskLabel: 'Refund request for order #8821',
  toolName: 'issue_refund',
  subject: 'Approve conditional refund for customer cus_99',
  preview: 'Refund releases only after return-label scan.',
  riskLevel: 'high',
  summary: ['Reviewer requested a conditional refund'],
  requestPayload: {
    amount: 500,
    currency: 'usd',
    release_condition: 'return_label_scanned',
  },
});