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";

const client = new Client({ token: "..." });

const me = await client.getMe();
console.log(`${me.username}: ${me.balance} STK`);

const events = await client.getEvents();
for (const event of events) {
  console.log(`[${event.type}] ${event.data}`);
}

Gateway (real-time events)

import { Client, Gateway } from "stackcoin";
import type { TransferCompletedEvent, RequestAcceptedEvent } from "stackcoin";

const gateway = new Gateway({ token: "..." });

gateway.on("transfer.completed", (event) => {
  const e = event as TransferCompletedEvent;
  console.log(`Transfer of ${e.data.amount} STK from #${e.data.from_id} to #${e.data.to_id}`);
});

gateway.on("request.accepted", (event) => {
  const e = event as RequestAcceptedEvent;
  console.log(`Request #${e.data.request_id} accepted`);
});

await gateway.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";
import type { TransferCompletedEvent } from "stackcoin";

const client = new Client({ token: "..." });

const gateway = new Gateway({
  token: "...",
  client,
  lastEventId: savedCursor,
  onEventId: (id) => saveCursor(id),
});

gateway.on("transfer.completed", (event) => {
  const e = event as TransferCompletedEvent;
  // ...
});

await gateway.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.