SPAPS SDK (TypeScript)

spaps-sdk is the typed TypeScript client for SPAPS-compatible APIs. It wraps common API surfaces in namespaces (auth, payments, issueReporting, entitlements, and others), re-exports many spaps-types contracts, and ships helper utilities for permission checks, feature gates, WebSocket auth, and webhook verification.

Verified public release: spaps-sdk 2.0.2, with Node.js 14 or newer. The documented exports were checked against that release artifact. The upstream 2.0.3-dev.0 checkout is development source, not a published release.

Install

npm install spaps-sdk@2.0.2
npm ls spaps-sdk

Alternative package managers:

pnpm add spaps-sdk@2.0.2
yarn add spaps-sdk@2.0.2

Client Setup And Key Modes

The SDK supports:

• publishableKey for browser-safe usage.
• secretKey for server-side calls; protected operations still require user authority.
• legacy apiKey for compatibility.

Constructor values override environment variables.

import { SPAPSClient, createBrowserClient, createServerClient } from 'spaps-sdk'
 
// Generic constructor
const spaps = new SPAPSClient({
  apiUrl: 'https://api.sweetpotato.dev',
  publishableKey: 'spaps_pub_example'
})
 
// Browser helper
const browserClient = createBrowserClient('spaps_pub_example', {
  apiUrl: 'https://api.sweetpotato.dev'
})
 
// Server helper
const serverClient = createServerClient('spaps_sec_example', {
  apiUrl: 'https://api.sweetpotato.dev'
})

Relevant env vars:

• SPAPS_API_URL
• NEXT_PUBLIC_SPAPS_API_URL
• SPAPS_API_KEY
• NEXT_PUBLIC_SPAPS_API_KEY

Namespace Surface

Permission And Role Helpers

These local helpers support UI decisions. They do not grant server roles or replace SPAPS authorization checks:

• isAdminAccount
• getUserRole
• hasPermission
• canAccessAdmin
• PermissionChecker
• createPermissionChecker

import { createPermissionChecker, canAccessAdmin, isAdminAccount } from 'spaps-sdk'
 
const checker = createPermissionChecker(['admin@example.com'])
const role = checker.getRole('staff@example.com')
const access = canAccessAdmin({ id: 'u1', email: 'admin@example.com' })
const isAdmin = isAdminAccount('admin@example.com')
 
console.log(role, access.allowed, isAdmin)

RoleHierarchy And FeatureEvaluator

RoleHierarchy gives deterministic role comparisons. FeatureEvaluator applies three layers in order:

1. System kill switch entitlement key
2. Resource-scoped block entitlement key
3. Minimum role check

import { FeatureEvaluator, RoleHierarchy } from 'spaps-sdk'
 
const hierarchy = new RoleHierarchy({
  guest: 0,
  user: 10,
  accountant: 20,
  admin: 30
})
 
const evaluator = new FeatureEvaluator(hierarchy)
evaluator.registerFeature('billing_export', {
  killSwitchKey: 'kill:billing_export',
  resourceBlockKey: 'block:billing_export',
  resourceBlockType: 'company',
  minimumRole: 'accountant'
})

WebSocketAuthHelper

WebSocketAuthHelper manages authenticated WebSocket connections with token refresh and reconnect handling.

Notable behaviors from packages/sdk/src/websocket-auth-helper.ts:

• Prefers a short-lived, single-use connect ticket in ?ticket=...; never puts the long-lived access token in the URL. Without a ticket, the bearer token travels in the Sec-WebSocket-Protocol handshake header.
• Refreshes tokens before expiry (buffer-based).
• Reconnects on auth close codes 4001 and 4003.
• Uses exponential backoff for network retries.
• Optional ping interval for stale connection detection.

Use realtimeUrl and requestConnectTicket only with an operator-approved realtime deployment that provides matching ticket issuance and consumption. Supply getAccessToken and refreshAccessToken from your application’s session handling.

SPAPS’s HTTP POST /api/realtime/ws-ticket requires a server-held secret key and the current user’s token. It does not accept a publishable browser key, and its existence does not establish an available hosted WebSocket endpoint.

import { WebSocketAuthHelper } from 'spaps-sdk'
 
const ws = new WebSocketAuthHelper({
  url: realtimeUrl,
  getAccessToken,
  refreshAccessToken,
  getConnectTicket: requestConnectTicket,
  onMessage: data => console.log(data)
})
 
await ws.connect()

Issue Reporting Helpers

The issueReporting namespace exposes:

• getStatus
• list
• get
• create
• update
• reply
• createVoiceToken

scope is currently restricted to "mine" in the stock SPAPS API path; wider scopes are rejected by the SDK guard.

Entitlements Helpers

The entitlements namespace includes:

• list(params?)
• check(key, userId?)
• listByResource(resourceType, resourceId?)

Scope behavior:

• Publishable-key contexts require user JWT and are user-scoped.
• Secret-key contexts can query broader resource scopes.
• Non-user resource scopes in publishable contexts are blocked server-side.

Webhook Verification Helper

Use verifyCryptoWebhookSignature for crypto webhook signature validation.

import { verifyCryptoWebhookSignature } from 'spaps-sdk'
 
verifyCryptoWebhookSignature({
  body: requestBody,
  signature: request.headers['x-spaps-signature'] as string,
  // Resolve the provider-specific signing secret from your server-side secret store.
  // SPAPS does not define one universal webhook-secret environment variable.
  secret: await loadWebhookSecret('crypto-provider')
})

Never expose this secret through a browser bundle or a NEXT_PUBLIC_*/VITE_* variable. The hosted server’s provider map is CRYPTO_WEBHOOK_SECRETS; downstream consumers may use a different secret-store key.

Validate Your Integration

Check npm ls spaps-sdk and retain your lockfile. Typecheck your application’s SDK calls, then exercise sign-in, one protected request, and an entitlement denial against your hosted staging application. A package installation does not prove hosted credentials or application permissions.