typescript-sdk

name: typescript-sdk description: Use the @contextvm/sdk TypeScript SDK effectively. Reference for core interfaces, signers, relay handlers, transports, encryption, logging, and SDK patterns. Use when implementing SDK components, extending interfaces, configuring transports, or debugging SDK usage.

ContextVM TypeScript SDK

Reference guide for using @contextvm/sdk effectively.

Installation

npm install @contextvm/sdk
# or
bun add @contextvm/sdk

Core Imports

// Transports
import { NostrClientTransport, NostrServerTransport } from '@contextvm/sdk'

// Signers
import { PrivateKeySigner } from '@contextvm/sdk'

// Relay Handlers
import { ApplesauceRelayPool } from '@contextvm/sdk'

// Components
import { NostrMCPProxy, NostrMCPGateway } from '@contextvm/sdk'

// Core types and utilities
import {
  EncryptionMode,
  CTXVM_MESSAGES_KIND,
  SERVER_ANNOUNCEMENT_KIND,
  createLogger,
} from '@contextvm/sdk'

Core Interfaces

NostrSigner

Abstracts cryptographic signing:

interface NostrSigner {
  getPublicKey(): Promise<string>
  signEvent(event: EventTemplate): Promise<NostrEvent>
  nip44?: {
    encrypt(pubkey: string, plaintext: string): Promise<string>
    decrypt(pubkey: string, ciphertext: string): Promise<string>
  }
}

Implement for custom key management (hardware wallets, browser extensions, etc.).

RelayHandler

Manages relay connections:

interface RelayHandler {
  connect(): Promise<void>
  disconnect(relayUrls?: string[]): Promise<void>
  publish(event: NostrEvent): Promise<void>
  subscribe(
    filters: Filter[],
    onEvent: (event: NostrEvent) => void,
    onEose?: () => void
  ): Promise<void>
  unsubscribe(): void
}

Must be non-blocking - subscribe() returns immediately.

Signers

PrivateKeySigner

Default signer using raw private key:

const signer = new PrivateKeySigner('32-byte-hex-private-key')
const pubkey = await signer.getPublicKey()

Security: Never hardcode keys. Use environment variables.

Custom Signers

Implement NostrSigner for:

• Browser extensions (NIP-07)
• Hardware wallets
• Remote signing services
• Secure enclaves

See references/custom-signers.md for examples.

Relay Handlers

ApplesauceRelayPool (Recommended)

Production-grade relay management:

const pool = new ApplesauceRelayPool(['wss://relay.contextvm.org', 'wss://cvm.otherstuff.ai'])

Features:

• Automatic reconnection
• Connection monitoring
• RxJS-based observables
• Persistent subscriptions

SimpleRelayPool (Deprecated)

Basic relay management:

const pool = new SimpleRelayPool(relayUrls)

Use ApplesauceRelayPool for new projects.

For NostrClientTransport, relayHandler can be omitted when the client should resolve operational relays dynamically. The resolution order is:

1. explicit operational relays from relayHandler
2. relay hints embedded in nprofile
3. CEP-17 relay-list discovery via discoveryRelayUrls
4. SDK bootstrap discovery relays when discoveryRelayUrls is omitted

This makes client configuration simpler when the server already publishes kind:10002 metadata.

Encryption Modes

enum EncryptionMode {
  OPTIONAL = 'optional', // Use if supported (default)
  REQUIRED = 'required', // Fail if not supported
  DISABLED = 'disabled', // Never encrypt
}

Logging

import { createLogger } from '@contextvm/sdk/core'

const logger = createLogger('my-module')

logger.info('event.name', {
  module: 'my-module',
  txId: 'abc-123',
  durationMs: 245,
})

Configure via environment:

• LOG_LEVEL=debug|info|warn|error
• LOG_DESTINATION=stderr|stdout|file
• LOG_FILE=/path/to/file
• LOG_ENABLED=true|false

Constants

SDK Patterns

See references/patterns.md for:

• Error handling
• Retry strategies
• Connection lifecycle
• Resource cleanup

API Reference

• references/interfaces.md - Complete interface definitions
• references/constants.md - All exported constants
• references/logging.md - Logging best practices