stackcoin-typescript

TypeScript library for the StackCoin API. Provides a typed REST client and a WebSocket gateway for real-time events.

Install

npm install stackcoin

Requires Node 21+. Types are generated from the StackCoin OpenAPI spec via openapi-typescript.

Quick start

import{Client}from"stackcoin";constclient=newClient({token: "..."});constme=awaitclient.getMe();console.log(`${me.username}: ${me.balance} STK`);constevents=awaitclient.getEvents();for(consteventofevents){console.log(`[${event.type}] ${event.data}`);}

Gateway (real-time events)

import{Client,Gateway}from"stackcoin";importtype{TransferCompletedEvent,RequestAcceptedEvent}from"stackcoin";constgateway=newGateway({token: "..."});gateway.on("transfer.completed",(event)=>{conste=eventasTransferCompletedEvent;console.log(`Transfer of ${e.data.amount} STK from #${e.data.from_id} to #${e.data.to_id}`);});gateway.on("request.accepted",(event)=>{conste=eventasRequestAcceptedEvent;console.log(`Request #${e.data.request_id} accepted`);});awaitgateway.connect();

Catching up on missed events

If your bot persists its cursor position and reconnects with a lastEventId, the server replays up to 100 missed events. If more than 100 were missed, the join is rejected -- pass a client so the Gateway can automatically catch up via the REST API. Without a client, a TooManyMissedEventsError is raised.

import{Client,Gateway}from"stackcoin";importtype{TransferCompletedEvent}from"stackcoin";constclient=newClient({token: "..."});constgateway=newGateway({token: "...",
client,lastEventId: savedCursor,onEventId: (id)=>saveCursor(id),});gateway.on("transfer.completed",(event)=>{conste=eventasTransferCompletedEvent;// ...});awaitgateway.connect();

Examples

• examples/basic-usage.ts -- REST client basics (balance, users, transactions)
• examples/gateway.ts -- WebSocket gateway with live event handlers

Testing

Tests for this library live in the main StackCoin/StackCoin repository as end-to-end tests that boot a real StackCoin server:

cd /path/to/StackCoin/test/e2e/ts
pnpm install
pnpm test

The E2E suite covers the REST client (Client) and WebSocket gateway (Gateway) against a live server. Tests are run with vitest and include transfers, payment requests, event pagination, idempotency, and real-time event delivery over WebSocket.

Development

Types are generated from the StackCoin OpenAPI spec using openapi-typescript:

just generate

This regenerates src/schema.d.ts from openapi.json.