@bsv/message-box-客户端

补丁候选人 2.6.1 更新打包的第一当事方运行时间或开发依赖范围。 此只使用元数据补丁保存了公共API,对等范围,有线格式和默认. 不需要额外的消费者或数据迁移;早期的迁移指南仍然适用.

BSV 可选加密的加密存储和转发消息 应用。 该软件包支持浏览器和Node.js消费者,HTTP投票, 现场验证的 WebSockets, 覆盖主机发现, 对等支付, 表示式和解适配器、权限、引文和推码注册.

安装

npm install @bsv/message-box-client @bsv/sdk

@bsv/sdk 是一个必要的同伴依赖。 该软件包支持Node.js 22和 更新并发布模块正确的无害环境管理和通用JS切入点.

基本讯息

import { MessageBoxClient } from '@bsv/message-box-client'
import { WalletClient } from '@bsv/sdk'

const wallet = new WalletClient()
const messages = new MessageBoxClient({
  walletClient: wallet,
  host: 'https://message-box-us-1.bsvb.tech'
})

const recipient = '025706528f0f6894b2ba505007267ccff1133e004452a1f6b72ac716f246216366'

await messages.sendMessage({
  recipient,
  messageBox: 'general_inbox',
  body: { text: 'Hello' }
})

const pending = await messages.listMessages({
  messageBox: 'general_inbox'
})

await messages.acknowledgeMessage({
  messageIds: pending.map(message => message.messageId)
})

TerraTestNet 客户端选择孤立的覆盖网络并提供 明确部署 TTN 消息框 :

const ttnMessages = new MessageBoxClient({
  walletClient: wallet,
  host: 'https://messagebox.ttn.example',
  networkPreset: 'teratestnet'
})

在专用 TTN 消息盒服务完成之前, 需要明确的主机 已经部署。 这阻止了TTN客户端默默地使用测试网服务.

listMessages() 保留其历史获取的全部行为 限定服务器页面 。 酌情限制总客户端内存 :

const firstTwoPages = await messages.listMessages({
  messageBox: 'general_inbox',
  pageSize: 250,
  maxPages: 2
})

const nextThousand = await messages.listMessages({
  messageBox: 'general_inbox',
  offset: 1000,
  limit: 1000
})

客户端使用AuthFetch来进行BRC-105的挑战. 它故意不添加 由于 BRC- 100 钱包, 第二个信件盒特定成本审批机制 权限已经制约了付款授权.

UMD 捆绑包括 SDK 2. 5.0 支持可选 x-bsv-payment-known-txids 响应头; 模块消费者可以通过 使用 SDK 2. 5.0 或以后使用. SDK 扩展让收件人已经发布广告 已验证的支付祖先, 这样兼容的钱包可以从支付中删除 贝夫。 这不是一个标准化的BRC-105标题。 现有兼容的 SDK 端口 继续支持,删除页眉的服务保留现有付款 行为 不需要消费者迁移.

明确 init() 是可选的。 启动钱包身份的公用方法 需要时:

await messages.init()

客户端诊断,包括出错,默认被禁用. 设定 enableLogging: true 只有当固定生命周期事件对信任者有用时 本地操作员。 诊断者故意省略信息机构和身份证, 身份密钥、 主机和查询参数、 钱包例外、 和解 文物、交易、付款数额、设备代号以及服务器响应 对象。 应用程序应在 它们需要将固定客户端事件与应用程序请求连接; 不 将钱包或信件数据重新引入控制台日志 .

通过钱包协议默认启用加密 。 普通文字是一个 明确的互操作性选择 :

await messages.sendMessage({
  recipient,
  messageBox: 'public_payloads',
  body: 'This payload is intentionally plaintext.',
  skipEncryption: true
})

服务器认证和路由密码文本,但不持有钱包 解密它所需的密钥.

实时消息

await messages.listenForLiveMessages({
  messageBox: 'general_inbox',
  onMessage: message => {
    console.log(message.sender, message.body)
  }
})

await messages.sendLiveMessage({
  recipient,
  messageBox: 'general_inbox',
  body: 'Live when possible, store-and-forward when needed.'
})

sendLiveMessage() 使用认证的 WebSocket 并返回到 HTTP 当套接字无法使用或不承认已发送时, 发送路由 . 相冲突的 WebSocket 身份指针是配置错误, 而不是不可用 套接字,所以它仍然扔. 它能捕捉和验证同一个不可改变的接收器,信息箱,身体, 消息ID、许可和支付上限授权 sendMessage() 在此之前 打开或加入套接字。 房间的名字是精确的,没有控制线 而非对客户端或服务器进行静默修饰. 打电话 disconnectWebSocket() 当一个长寿的客户端关闭.

现场插座自己做什么

套接字时保留了已丢弃的套接字 。 iO重新连接它,和你的房间 一旦新的连接认证结果——成员——再次加入 属于加入的服务器侧套接字, 因此需要替换 自己来 服务器强制断开就是一个Socket. IO不会重试,所以 客户端重建套接字本身: 立即第一次, 然后加倍 从一秒起至三十二分,直到套接字保持 认证.

加入速度已加快:最多16个等待服务器在套接字上的回答,其余部分 答案一到就出去 或5秒后没有答案 服务器掉入 a 正在使用超过32个签名信件的套接字, 因此客户端多于 有32个箱子马上送出每个参赛者 从未保留它的插座.

一个房间从请求时起 算在目前的套接字上, 在服务器回复之前,直到服务器拒绝 joinFailed 还是你 离开它. getJoinedRooms() 和现场状态 rooms 两者都意味着.

来电者有两件事:

• 投票对于正确性是必需的,而不是作为倒计时. 实时消息 仅到达服务发送过程所持有的套接字,以及 a 付费信息从来没有被推动过。 继续打电话 listMessages()这是 也是将收款人付款内部化的唯一途径.
• getJoinedRooms() 它不是一个杠杆. 它会回房间的 加入当前套接字, 请求而不是拒绝。 改变 返回的集不会取消复会——呼叫 leaveRoom(),释放 房间,无论套接字是否打开.

知道插座在做什么吗

const stop = messages.onLiveStatus(({ state, rooms, reason }) => {
  // 'connecting' | 'live' | 'reconnecting' | 'closed'
  poller.setInterval(state === 'live' ? 60_000 : 5_000)
})

收听者被立即调用一次 以当前状态和每个 之后的过渡; onLiveStatus 返回删除它的函数,并且 messages.liveStatus 在不签名的情况下读取相同的值.

reconnecting 表示某物会还原套接字——Socket. IO自己的重试, 或重建客户端 已经安排. closed 意味着什么 disconnectWebSocket(),一滴滴下来 managerOptions.reconnection: false,或一个 重建失败。 下一个需要插座的电话仍然会建一个.

rooms 列出上文定义的当前套接字上加入的房间,并且 除非状态为空 live。服务器拒绝的房间被删除 新报告。 投球的听众会被记录下来,不会停止 别人.

状态描述此套接字 。 这不是送货的保证:继续投票 listMessages() 随其所说.

套接字选项

socketOptions 将转至下层 AuthSocketClient 当活的 设置了套接字 。 用它来选择 Socket 。 部署时会进行IO运输 前置基础设施不携带发动机。 IO HTTP投票:

const messages = new MessageBoxClient({
  walletClient: wallet,
  host: 'https://messagebox.example',
  socketOptions: { managerOptions: { transports: ['websocket'] } }
})

await messages.listenForLiveMessages({
  messageBox: 'general_inbox',
  onMessage: message => {
    console.log(message.sender, message.body)
  }
})

它也携带 requestedCertificates, (中文(简体) ), sessionManager, (中文(简体) ), maxPendingAuthMessages,以及 onError。 。 。 .

该类型不包括四个字段. wallet 财务报告和审定财务报表 originator 属于 客户端,它总是使用自己的值. managerOptions.autoConnect 实值 排除,因为套接字在创建时会连接 AuthSocketClient 以后无法启动,所以不能自动连接 连接; 如果传递为 false。 。 。 .

managerOptions.retries 也排除: AuthSocket 不发送原始 袜子。 IO承认消息重试需要,所以允许重试 将屏蔽随后的认证和应用程序信息。 构造器 拒绝非零重试。 连接重连接设置, 如 reconnection 财务报告和审定财务报表 reconnectionAttempts 继续支持.

managerOptions.reconnection: false 读取并尊重: 而不是等待永远不会到来的重试. 没有重建 在那种环境下,它独自存在. 下一个 initializeConnection(), (中文(简体) ), joinRoom(), (中文(简体) ), listenForLiveMessages() 或者说 sendLiveMessage() 新建一个 套接字并恢复房间和订阅,所以客户端发送 在它的下一次发送中恢复了,但一个只订阅,然后等待永远 已经 启用重新连接, 除非主机正在驱动重新连接 自己来.

socketOptions 应用 只连接到活套接字路径 —— 说 initializeConnection(), (中文(简体) ), listenForLiveMessages(),以及 sendLiveMessage()它不影响 sendMessage(), (中文(简体) ), listMessages(),或 acknowledgeMessage(),用于 认证的HTTP.

选择东道主和获得公共服务

明确配置的主机必须使用 HTTPS, 循环运行除外 ()localhost, (中文(简体) ), *.localhost, (中文(简体) ), 127.0.0.0/8,或 [::1]) (中文(简体) ). 一定是绝对的 URL 没有周围的空白、 证书、 查询、 片段或控制 字符键。 支持路由前缀 :

const messages = new MessageBoxClient({
  walletClient: wallet,
  host: 'https://messaging.example.com/api'
})

每个消息盒 HTTP 响应必须是 BRC-103 成功的结果 认证。 客户端拒绝 AuthFetch 的普通- HTTP 兼容性 退后,需要一个可读曲线验证服务器身份,并保留第一个 该客户的每个来源的认证身份权威. 对于持久的独立信任,按基准 URL 标出预期服务器身份:

const messages = new MessageBoxClient({
  walletClient: wallet,
  host: 'https://messaging.example.com/api',
  serverIdentityKeysByHost: {
    'https://messaging.example.com': '02…'
  }
})

Pins 是每个 URL 源头, 因此同一源头的两个路由前缀不能命名 不同身份 不同身份 不同身份 不同的上覆主机可能以不同方式认证 身份证明 服务器密钥的更改需要创建一个新客户端并更新, 独立验证的指针;在一个实例中从未被默默接受.

重叠广告是不信任的网络输入. 发现目的地 必须使用公开的 HTTPS 地址; 回回、 私有、 链接本地、 保留、 和 只有在文件主机中才能提出要求。 如果无效 广告存在,使用配置的主机。 每次退回的交易, 输出索引 犬类 PushDrop 信封 广告身份 签名是 与所要求的身份进行约束和独立核查。 抬头 因此,供应商提供候选人,而不是线路管理局.

消息盒是一个公共协议服务. 应保留兼容服务器 默认情况下可访问带有无证书通配符的浏览器 CORS, 包括 不透明 Origin: null 移动网络视图等呼叫器. 运算符可以选择使用 精确来源的允许列表或禁用浏览器 CORS。 CSP 规范送达的文件 而不是API的授权。 BRC-103 认证,接受方所有权, 权限、支付、配额和信件加密仍然是安全 边框.

权限和发送引用

await messages.setMessageBoxPermission({
  messageBox: 'notifications',
  sender: recipient,
  recipientFee: 10
})

const quote = await messages.getMessageBoxQuote({
  recipient,
  messageBox: 'notifications'
})

许可费使用这些值:

• -1: 已封锁
• 0: 允许不收取收款人费用
• 正整数: 需要的 stoshi 量

设定 checkPermissions: true 打开 sendMessage() 当客户端引用时 ,并在发送前构建所需付款。 相互认证 信件框对自己的价格是权威的,而钱包仍然是 最后支出授权。 申请可增加一个独立的上限 maximumPayment; 客户端在请求钱包前拒绝一个更大的引用 动作 :

await messages.sendMessage({
  recipient,
  messageBox: 'notifications',
  body: { title: 'Bounded-cost alert' },
  checkPermissions: true,
  maximumPayment: 25
})

引用行必须精确绑定每个被请求的收件人和消息箱名称 一次 一次吗 收费是受限整数、受阻和状态字段必须商定, 和总算必须留在安全整数域。 付款前 发送时,客户端独立解析钱包的原子BEEF和 要求每个送出和接收输出保留其请求的脚本, 金额和汇款指数。 自定义钱包响应从不被视为 付款证据仅仅因为它返回交易字节.

外出收受者是被卡通压缩的公钥. 信息箱名称, 调用者提供的信息ID,序列化的身体是准确的和有界限的 对象和请求记录必须只包含普通数据。 客户 在第一次同步运行前捕捉完整的发送权威, 所以后来的呼叫者突变不能改变接收者,信息框,身体,旗帜, 或支付上限。 服务器发送结果仅在接收时被接受 和消息ID匹配. 许可和装置响应也被视为不可信的协议输入: 记录、警棍身份钥匙、费用、时间戳、面具、平台 值、标识符和页码参数必须与其设定的公式相匹配.

同伴付款

import { PeerPayClient } from '@bsv/message-box-client'

const payments = new PeerPayClient({ walletClient: wallet })

await payments.sendPayment({
  recipient,
  amount: 50_000
})

const incoming = await payments.listIncomingPayments()
for (const payment of incoming) {
  await payments.acceptPayment(payment)
}

PeerPayClient 使用 BRC- 29 钱包付款衍生和同一认证 信息箱传输. 它还支持现场递送、付款申请、, 答复、注销和明确拒绝/退款流动. 它的 SDK 对等方接受两种历史 number[] 二进制钱包线 Uint8Array 交易结果,而支付信息保留一个便携式 JSON 字节阵列代表. 收据与待发信件相容 其打入的数组字节已被序列化为相接的数字键 . 同样的兼容合同包括支付信息费、批发货物、, 代币结算、实时信息回落和普通汇款运输. 在多接收发送中,引用的服务器发送费适用于每个发送 允许收件人。 客户对照 maximumPayment 并将其放入批次的单一服务器汇款输出中. 错误的、稀有的或外向的字节记录在钱包前被拒绝 内部化和源电文仍然可供重试或回收. 收到的付款额上限为1 000个信件,并验证其名称 发送密钥、 交易字节、 衍生元数据、 正整数、, 输出索引和消息ID。 活回调应用相同的验证. acceptPayment 财务报告和审定财务报表 rejectPayment 仅使用呼叫者的消息ID, 重新装入 认证的收件箱, 需要一个独特的匹配, 并为所有人使用新记录 钱包、确认和退款决定. 付款要求清单和实时回调同样需要条条 身体/信封身份匹配、有界字段、未到期请求和 肯定的32字节HMAC证明. 重放一个发件人的请求ID失败 关闭。 执行和拒绝调用只使用选中信件 ID, 重新装入 经认证的收件箱,拒绝由同一人同时处理该ID 客户实例。 答复全文为: sender 财务报告和审定财务报表 messageId; 总是绑住两者 requestId 财务报告和审定财务报表 sender 页:1 原始请求接收者.

托肯定居点

PeerTokenClient 路由符和请求通过信件框 将特定标牌交易工作委托给已注册的交易 TokenSettlementAdapter 执行:

import { PeerTokenClient } from '@bsv/message-box-client'

const tokens = new PeerTokenClient({
  walletClient: wallet,
  adapters: [myTokenAdapter]
})

文库不假定符号标准线条格式. 适配器拥有 特定标准的构建、接受、终止和接收数据 协议,而客户端执行共同权限边界: 犬类对等键,有界限的交易/消息字段,犬类正数 整数、 精确适配器动作裁定和请求不变 协议/资产/山地。 收视率上限为1000个记录. acceptToken() 仅使用所提供信件ID, 重新装入认证 收件箱,需要一个独特的新匹配,并仅在适配器后确认 返回文字 accept 行动。 接受确认后停止确认 保存是可恢复的,不会将结果变成真实的错误字符串. Token请求采用相同的有界限的认证信封模型。 生活与生活 列出的请求需要条条形体/信封发送者匹配, 未过期 和32字节的HMAC证明 完成和减少 操作通过消息ID重新装入收件箱,只使用独有的新请求; 实现还需要选定来源的协议和资产与之相匹配. 正在发送的请求、取消和回复列表验证并绑定所有 钱包或运输工作之前的普通字段。 一个客户拒绝 同步完成/ 解密同一同物请求信件的处理 .

RemittanceAdapter 将信件盒显示为 SDK 汇款通讯 层.

HTTP和WebSocket合同

客户端使用这些认证的 HTTP 路由 :

相应的 OpenAPI 源代码为 specs/messaging/message-box-http.yaml。 。 。 . 现场交付使用认证的Socket. IO事件和身份所属房间.

公共出口

• MessageBoxClient
• PeerPayClient
• PeerTokenClient
• RemittanceAdapter
• TokenSettlementAdapter 及其辅助类型
• 信件、付款、令牌、设备、许可、引文和批发类型
• 标准信息框名称常数

发展

从寄存器根 :

pnpm --filter @bsv/message-box-client typecheck
pnpm --filter @bsv/message-box-client lint
pnpm --filter @bsv/message-box-client test
pnpm --filter @bsv/message-box-client test:coverage
pnpm --filter @bsv/message-box-client pack:check
pnpm --filter @bsv/message-box-client test:browser

单元套房具有确定性,不与部署的服务部门联系. test:integration 因为它需要配置钱包, 信件盒、数据库、 WebSocket 和上覆服务:

MESSAGE_BOX_RUN_INTEGRATION=true \
MESSAGE_BOX_INTEGRATION_HOST=http://127.0.0.1:8080 \
MESSAGE_BOX_WALLET_ORIGINATOR=localhost \
pnpm --filter @bsv/message-box-client test:integration

目标 *.bsvb.tech 需要额外明确 MESSAGE_BOX_ALLOW_PRODUCTION_INTEGRATION=true 承认,因为 套件组创建并承认真实的信息 .

所发行的柏球包含已编译的无害环境管理/共同JS JavaScript,匹配 声明和源图, UMD 浏览器捆绑, 此 README 执照 它不发布 TypeScript 源,测试,覆盖,编辑文件, 或包裹管理锁.

许可证

TS 堆放第一当事方材料 打开 BSV 许可证版本 6。 。 。 . UMD 捆绑包含单独许可的 SDK 材料; 保留 第三次议会 NoTICES.md 财务报告和审定财务报表 属性/ 与捆绑.

付款接受和确认令

acknowledgeNotification 检查原始通知信封,内部化 与配置的发端人一起支付现收款人,并承认 仅在钱包返回后 accepted: true一份无通知的通知 可以立即确认付款。 失败、信封不完整和付款没有钱包支付产出 继续排队。 其布尔返回合同不变: false 能够 即不付款或保留未付款.

收到的付款信封接受最多32个BEEF原子,最多101个 支付产出,匹配现有的100个接收批次加交付费 产出合同。 客户端独立快照这些字段, 这样有效 大型交易不因较小的通用JSON图限而被拒绝; 稀有数组、存取器、非字节值和超大小字段仍然失败 钱包工作前关闭 .

acceptPayment 还要求在承认前接受肯定钱包; 验证和内部化失败拒绝而不是返回真相 错误字符串。 接受监护后未确认的,可以收回 而不改变成功的结果. 对于应退还的数额, rejectPayment 先内部化,送退款, 然后承认 内部化失败既不能退款,也不能退款 承认; 退款失败会留下已排队的消息 。 现有 小额付款政策不变.

这是最初订购的补救 问题503。 。 。 . 它不提供耐用退款日记账或一次性交货。 调和 重试前不确定的退款结果, 因为发送可能已完成 在失去反应之前 留存付款封和结果报告 结束 listMessages编号 :listMessagesLite、篮子插入政策,以及可续订 退款语义仍然开放。 使用原始信封进行通知付款 ; 明确承认不是接受付款的证据.

支付和象征性要求的履行也不能提供跨程序或 与当前协议的交叉碰撞即时和解。 如果解决 成功但回复失败或丢失,请求仍然排队,并且 自动重试可以支付两次. 不可重试不确定的实现,直到 钱包和对等点已对齐。 坚持每个经认证的请求ID和 发件人和每次尝试或完成的结算交易ID. 在完成或重试之前, 拒绝已经相关的交易ID 不同的请求,并拒绝不同的交易编号,以用于请求 结果没有调和。 应用相同的持久关联 服务进程; 内相序列化不是跨进程重放 保护.

SDK4 热补丁对等要求

SDK4 对等替代开始于 @bsv/sdk ^4.0.1,恢复数字 钱包结果和遗留线条相容性。 现有的SDK2/3替代品和 下限不变。 SDK4 用户应安装 4. 0.1 个热补丁; 不 需要应用程序-wallet线或数据迁移.