@bounded-sh/server

Server SDK for the Bounded API. It provides explicit, isolated Solana-keypair clients for backend applications; no signer is loaded from ambient process state.

Installation

npm install @bounded-sh/server

Or using yarn:

yarn add @bounded-sh/server

Features

• Server-side authentication using Solana keypairs (SIWS)
• In-memory session management (no cookies or local storage required)
• Support for all Tarobase data operations (get, getMany, set, query)
• Real-time subscriptions
• Transaction signing and execution
• TypeScript support

Basic Usage

import { init, createWalletClient } from '@bounded-sh/server';

async function main() {
  // Initialize endpoints/app config only. Server signing identity is explicit.
  await init({ appId: 'your-app-id' });

  // Create a wallet-scoped client from an explicit secret key.
  const wallet = await createWalletClient({ keypair: process.env.SERVER_WALLET_KEYPAIR! });
  console.log(`Using wallet: ${wallet.address}`);

  // Set data
  await wallet.set('todos/123', {
    text: 'Buy milk', 
    completed: false, 
    created: new Date().toISOString() 
  });

  // Get data
  const todo = await wallet.get('todos/123');
  console.log('Retrieved todo:', todo);
}

main().catch(console.error);

Advanced Usage

Loading a Keypair from a Secret Key File

import { init, createWalletClient } from '@bounded-sh/server';
import * as fs from 'fs';

// Load keypair from file
const secretKeyString = fs.readFileSync('/path/to/keypair.json', 'utf8');

// Initialize and create a wallet-scoped client
await init({ appId: 'your-app-id' });
const wallet = await createWalletClient({ keypair: secretKeyString });

Signing And Transactions

import { init, createWalletClient } from '@bounded-sh/server';

await init({
  appId: 'your-app-id',
  rpcUrl: process.env.SOLANA_MAINNET_RPC_URL
});

const wallet = await createWalletClient({ keypair: process.env.SERVER_WALLET_KEYPAIR! });

// Sign a message
const signature = await wallet.signMessage("Hello, world!");

// Submit a transaction you built explicitly with @solana/web3.js
// const signature = await wallet.signAndSubmitTransaction(transaction);

Subscriptions

import { init, createWalletClient } from '@bounded-sh/server';

// Initialize and create an explicit wallet client
await init({ appId: 'your-app-id' });
const wallet = await createWalletClient({ keypair: process.env.SERVER_WALLET_KEYPAIR! });

// Subscribe to changes
const unsubscribeFunc = await wallet.subscribe('todos', (data) => {
  console.log('Todos updated:', data);
});

// Later, unsubscribe when done
await unsubscribeFunc();

API Reference

Configuration and Initialization

function init(config: Partial<ClientConfig>): Promise<void>;
function getConfig(): Promise<ClientConfig>;
function getWebhookKeysUrl(): string | undefined;

Authentication

function createWalletClient(options: { keypair: string }): Promise<WalletClient>;
function getAuthProvider(): Promise<AuthProvider>; // always rejects; no process-global provider
function getIdToken(): Promise<string | null>; // always rejects; no process-global session

Data Operations

const wallet = await createWalletClient({ keypair });
const idToken = await wallet.getIdToken(); // refreshed bearer token for direct Bounded API calls
await wallet.get(path);
await wallet.getMany(paths);
await wallet.set(path, data);
await wallet.setMany(many);
await wallet.setFile(path, file);
await wallet.getFiles(path);
await wallet.runQuery(absolutePath, queryName, queryArgs);
await wallet.runQueryMany(many);

Subscriptions

const unsubscribe = await wallet.subscribe(path, callback);
await unsubscribe();

Solana Keypair Provider

class SolanaKeypairProvider implements AuthProvider {
  constructor(rpcUrl: string | null, keypair: Keypair);

  login(): Promise<User | null>;
  logout(): Promise<void>;
  signMessage(message: string): Promise<string>;
  restoreSession(): Promise<User | null>;
  getNativeMethods(): Promise<any>;
}

signAndSubmitTransaction requires an explicit provider rpcUrl; a missing RPC fails closed.

Types

interface ClientConfig {
  authMethod?: string;
  wsApiUrl: string;
  apiUrl: string;
  appId: string;
  authApiUrl: string;
  chain: string;
  rpcUrl: string;
  skipBackendInit: boolean;
  useSessionStorage: boolean;
}

interface User {
  address: string;
  provider: AuthProvider;
}

interface SetOptions {
  shouldSubmitTx?: boolean;
}

interface GetManyResult {
  path: string;
  data: any | null;
  error?: {
    code: 'NOT_FOUND' | 'UNAUTHORIZED' | 'INVALID_PATH';
    message: string;
  };
}

interface TransactionResult {
  transactionSignature?: string;
  signedTransaction?: any;
  blockNumber: number;
  gasUsed: string;
  data: any;
}

Contributing

Please see the main repository for contribution guidelines.

Key Differences from the Web SDK

This server-side SDK differs from the web SDK in several important ways:

1. Authentication Method: Uses explicit Solana keys instead of browser wallets
2. Storage Strategy: Uses in-memory storage instead of localStorage/sessionStorage
3. Environment: Optimized for Node.js/backend environments rather than browsers
4. Session Management: Does not rely on browser-specific APIs
5. Dependencies: Excludes browser-specific libraries

Part of the Bounded SDK Family

This package is part of a family of modular SDKs:

• @bounded-sh/core: Core functionality shared between all SDKs
• @bounded-sh/client: Browser and React Native SDK
• @bounded-sh/server: Server-side SDK for backend applications