typescript-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ContextVM TypeScript SDK

Reference guide for using

@contextvm/sdk

effectively.

高效使用

@contextvm/sdk

的参考指南。

Installation

安装

bash

npm install @contextvm/sdk

bash

npm install @contextvm/sdk

or

bun add @contextvm/sdk

undefined

bun add @contextvm/sdk

undefined

Core Imports

核心导入

typescript

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

typescript

// 传输层
import { NostrClientTransport, NostrServerTransport } from "@contextvm/sdk";

// 签名器
import { PrivateKeySigner } from "@contextvm/sdk";

// 中继处理器
import { ApplesauceRelayPool } from "@contextvm/sdk";

// 组件
import { NostrMCPProxy, NostrMCPGateway } from "@contextvm/sdk";

// 核心类型与工具
import {
  EncryptionMode,
  CTXVM_MESSAGES_KIND,
  SERVER_ANNOUNCEMENT_KIND,
  createLogger,
} from "@contextvm/sdk";

Core Interfaces

核心接口

NostrSigner

Abstracts cryptographic signing:

typescript

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.).

抽象加密签名功能：

typescript

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

可针对自定义密钥管理场景实现该接口（如硬件钱包、浏览器扩展等）。

RelayHandler

Manages relay connections:

typescript

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.

管理中继连接：

typescript

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

必须是非阻塞的 -

subscribe()

需立即返回。

Signers

签名器

PrivateKeySigner

Default signer using raw private key:

typescript

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

Security: Never hardcode keys. Use environment variables.

使用原始私钥的默认签名器：

typescript

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

安全提示：切勿硬编码密钥，请使用环境变量。

Custom Signers

自定义签名器

Implement

NostrSigner

for:

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

See

references/custom-signers.md

for examples.

针对以下场景实现

NostrSigner

接口：

浏览器扩展（NIP-07）
硬件钱包
远程签名服务
安全飞地

示例请参见

references/custom-signers.md

。

Relay Handlers

中继处理器

ApplesauceRelayPool (Recommended)

ApplesauceRelayPool（推荐）

Production-grade relay management:

typescript

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

Features:

Automatic reconnection
Connection monitoring
RxJS-based observables
Persistent subscriptions

生产级中继管理工具：

typescript

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

特性：

自动重连
连接监控
基于RxJS的可观察对象
持久化订阅

SimpleRelayPool (Deprecated)

SimpleRelayPool（已废弃）

Basic relay management:

typescript

const pool = new SimpleRelayPool(relayUrls);

Use

ApplesauceRelayPool

for new projects.

基础中继管理工具：

typescript

const pool = new SimpleRelayPool(relayUrls);

新项目请使用

ApplesauceRelayPool

。

Encryption Modes

加密模式

typescript

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

typescript

enum EncryptionMode {
  OPTIONAL = "optional", // 支持则使用（默认）
  REQUIRED = "required", // 不支持则报错
  DISABLED = "disabled", // 从不加密
}

Logging

日志

typescript

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
```

typescript

import { createLogger } from "@contextvm/sdk/core";

const logger = createLogger("my-module");

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

通过环境变量配置：

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

Constants

常量

Constant	Value	Description
`CTXVM_MESSAGES_KIND`	25910	Ephemeral messages
`SERVER_ANNOUNCEMENT_KIND`	11316	Server metadata
`TOOLS_LIST_KIND`	11317	Tools announcement
`RESOURCES_LIST_KIND`	11318	Resources announcement
`GIFT_WRAP_KIND`	1059	Encrypted messages

常量名称	值	描述
`CTXVM_MESSAGES_KIND`	25910	临时消息
`SERVER_ANNOUNCEMENT_KIND`	11316	服务器元数据
`TOOLS_LIST_KIND`	11317	工具公告
`RESOURCES_LIST_KIND`	11318	资源公告
`GIFT_WRAP_KIND`	1059	加密消息

SDK Patterns

SDK模式

See

references/patterns.md

for:

Error handling
Retry strategies
Connection lifecycle
Resource cleanup

请参见

references/patterns.md

了解：

错误处理
重试策略
连接生命周期
资源清理

API Reference

API参考

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

```
references/interfaces.md
```
- 完整接口定义
```
references/constants.md
```
- 所有导出常量
```
references/logging.md
```
- 日志最佳实践