类型脚本的 BEAM SDK

这次发布需要Core的 transfer-client-control/v7 合同。多段上传使用相接部分; 核心可能要求保留通过现有的SDK签名连接进行回收。工人领取普通上传 URL. 保持客户端的连接, 直至传输到达终端状态, 这样 Core 可以更新捐赠推广回收数据清理组装在升级Core和SDK消费者前排出活性转移.

安装 :

npm install @beam-network/sdk

示例

import { BeamClient, R2ProviderConfig, S3ProviderConfig } from "@beam-network/sdk";

const beam = new BeamClient({
  apiKey: "b1m_your_key"
});

const transfer = await beam.createTransfer({
  sources: [
    R2ProviderConfig.create({
      bucket: "source-bucket",
      key: "exports/report.parquet",
      account_id: "cloudflare-account-id",
      access_key_id: "r2-access-key",
      secret_access_key: "r2-secret-key"
    })
  ],
  destinations: [
    S3ProviderConfig.create({
      bucket: "destination-bucket",
      key: "imports/report.parquet",
      region: "us-east-1",
      access_key_id: "aws-access-key",
      secret_access_key: "aws-secret-key"
    })
  ],
  name: "r2-to-s3-report"
});

const status = await beam.waitForTransfer(transfer.transfer_id);
console.log(status.status);
await beam.close();

主要内容 createTransfer API具有提供者意识并严格输入S3,R2,S3相容,Hippius,Hugging Face和Box配置.

证书

来源和目的地证书不得仅限于特定的IP地址或网络. 当存储拒绝访问时, waitForTransfer 拒绝方式 BeamStorageAccessError (单位:千美元)code 实值 source_access_denied 或者说 destination_access_denied) (中文(简体) ).

信用和密钥出错

拒绝的生命周期请求 LifecycleRequestError (单位:千美元)status, (中文(简体) ), code, (中文(简体) ), detail) (中文(简体) ). 信用、帐单、密钥和许可拒绝使用这些子类:

InsufficientCreditsError (402美元) (中文(简体) ), insufficient_credits: creditsRequired 财务报告和审定财务报表 creditsAvailable (数目,或 null 当未知时)和 reason (单位:千美元)pool_exhausted, (中文(简体) ), key_cap_exhausted, (中文(简体) ), key_budget_blocked,或 null) (中文(简体) ).
BillingAccountNotLinkedError (402美元) (中文(简体) ), billing_account_not_linked:API密钥没有帐号.
ApiKeyInvalidError (401或403号), api_key_invalid: API 密钥未知,已过期,被撤销或已禁用.
PermissionRequiredError (403美元), permission_required: permission 命名密钥需要的许可.

可选 onWarning 召回收到附在生命周期答复后的建议,例如 credits_low 当贷方余额达到或低于低门槛值时(detail.remaining, (中文(简体) ), detail.low_threshold) (中文(简体) ). 每个不同的警告信息每个客户发送一次.

计费父母

billingParent 命名一个传输的计费操作, 如启动它的工作流程运行; Beam 记录该操作下的传输收费. createTransfer, (中文(简体) ), prepareProviderTransfer, (中文(简体) ), resumeProviderTransfer, (中文(简体) ), createRawTransfer 财务报告和审定财务报表 prepareTransfer 接受这一点。计费父为 1到 256个字母,数字和 . _ : @ / + = -;客户端在发送请求前拒绝任何其他值.

已签名的 URL 寿命

createTransfer, (中文(简体) ), prepareProviderTransfer 财务报告和审定财务报表 resumeProviderTransfer 签名传输 URL expiresIn 秒数。无 expiresIn,寿命为每100个 MB 交付一个小时加一秒(源字节×目的地),最多7天,因为 signedUrlLifetimeSeconds(deliveredBytes) 返回。发送的源 URL transfer.prepare 在知道大小之前签名 expiresIn 或一小时.

S3 兼容供应商

使用 S3CompatibleProviderConfig s3 符合自定义的供应商端点,如Wasabi, MinIO, Backblaze B2 S3 API, DigitalOcean Spaces,,, 等, Calmway对象存储器,以及自行托管的S3兼容系统.

import {
  BeamClient,
  S3CompatibleProviderConfig
} from "@beam-network/sdk";

const beam = new BeamClient({ apiKey: process.env.BEAM_API_KEY! });

await beam.prepareProviderTransfer({
  sources: [
    S3CompatibleProviderConfig.create({
      provider: "wasabi",
      bucket: "my-bucket",
      key: "input/file.bin",
      region: "us-east-1",
      endpoint_url: "https://s3.us-east-1.wasabisys.com",
      access_key_id: process.env.WASABI_ACCESS_KEY_ID!,
      secret_access_key: process.env.WASABI_SECRET_ACCESS_KEY!
    })
  ],
  destinations: [
    S3CompatibleProviderConfig.create({
      provider: "minio",
      bucket: "archive",
      key: "file.bin",
      endpoint_url: "https://minio.example.com",
      force_path_style: true,
      access_key_id: process.env.MINIO_ACCESS_KEY_ID!,
      secret_access_key: process.env.MINIO_SECRET_ACCESS_KEY!
    })
  ],
  name: "S3-compatible transfer"
});

使用 S3ProviderConfig 用于普通 AWS S3 如果首选, 并继续使用 R2ProviderConfig 用于现有的 Cloudflare R2 代码。使用 S3CompatibleProviderConfig 当供应商需要自定义 S3 兼容时终点.

拥抱相机

使用 HuggingFaceProviderConfig 将一个文件取出 Hub repo 或推入一个符号保留在此过程中: 源解决到预签名的 CDN URL 使用预签名部分 URL LFS批量端点问题.

import { BeamClient, HuggingFaceProviderConfig, S3ProviderConfig } from "@beam-network/sdk";

const beam = new BeamClient({ apiKey: process.env.BEAM_API_KEY! });

const transfer = await beam.prepareProviderTransfer({
  sources: [
    HuggingFaceProviderConfig.create({
      repo_id: "org/dataset",
      path: "data/train.parquet",
      repo_type: "dataset",
      token: process.env.HF_TOKEN!
    })
  ],
  destinations: [
    S3ProviderConfig.create({
      bucket: "archive",
      key: "datasets/train.parquet",
      access_key_id: process.env.AWS_ACCESS_KEY_ID!,
      secret_access_key: process.env.AWS_SECRET_ACCESS_KEY!
    })
  ],
  name: "Hugging Face pull"
});

// waitForTransfer commits any Hugging Face destination once the parts land.
await beam.waitForTransfer(transfer.transfer_id);

限制,所有这一切的枢纽而不是Beam的,看 HUGGINGFACE_PROVIDER.md 完整协议:

来源为大文件(LFS或Xet)内容. 只有他们得到无证书的 CDN 重定向; 一个小的正则文件被内置并正在使用以这个理由被拒绝。枢纽桶头工作也是来源,但不能他们没有暴露LFS的终点.
目的地需要前方的沙256号,因为LFS批次端点没有它就不会发布上传的 URL 。当来源本身不是枢纽文件, 设置 allow_source_rehash: true 让SDK读一次源计算它.
每个夹面目的地一个源因为Hub决定了角色大小和计划包含一个块大小.
如果你不打电话 waitForTransfer电话 finalizeHuggingFaceUploads(transferId) 自己一旦传送完成 —— 没有它, 部件会被上传, 但是没有已执行, 且文件不出现在回执中 .

方框

使用 BoxProviderConfig 将文件从 Box 中转移,以及 BoxDestinationConfig 要写输入 Box 文件夹. BOX_PROVIDER.md 描述两个协议.

框作为源

访问令牌保留在这个过程中: SDK 查找文件, 询问 Box 是否内容有重定向关闭,手 BeamCore 只包含预授权下载 URL 箱子重定向到。工人得到的URL和一个 Range 信头,永远不要.

import { BeamClient, BoxProviderConfig, R2ProviderConfig, boxFolderSources } from "@beam-network/sdk";

const beam = new BeamClient({ apiKey: process.env.BEAM_API_KEY! });

// Every file under a folder ("0" is the root folder). For one file, pass
// BoxProviderConfig.create({ file_id: "1234567890", token }) instead.
const sources = await boxFolderSources({ folder_id: "9876543210", token: process.env.BOX_ACCESS_TOKEN! });

const transfer = await beam.prepareProviderTransfer({
  sources,
  destinations: [
    R2ProviderConfig.create({
      bucket: "archive",
      key: "box-export/",
      account_id: process.env.R2_ACCOUNT_ID!,
      access_key_id: process.env.R2_ACCESS_KEY_ID!,
      secret_access_key: process.env.R2_SECRET_ACCESS_KEY!
    })
  ],
  name: "Box pull"
});

每个文件在一个版本读取. 正在准备源代码 Box 当前的文件版本为 version_id 源元数据中 file_id, (中文(简体) ), sha1, (中文(简体) ), name 财务报告和审定财务报表 Box 项目 box_etag。每次下载 URL 传输解析、重新签名包括路线和完整性审计,请框提供该版本.
每个文件每几分钟一个盒子呼叫一次不是每个块一个. 每个块读相同的下载链接 Range。SDK解决一次链接,分享它块和同时签字人,仅在不到11分钟时解决新问题 (单位:千美元)BOX_DOWNLOAD_URL_MIN_REUSE_SECONDS保留。按文件版本在内存中缓存链接和SHA -256的标志, 从来没有标志本身, 多达1 024个.
下载链接持续约15分钟. 航道要求14分钟所以BeamCore问 sDK 在较长的传输过程中重新签名, 并且重新签名会解决一个新的链接同一个版本.
SDK从不刷新符号. 它解决了每个下载链接,所以它必须只要转移路线需要,则有效。拒绝的代币涨价 BoxApiError 与 status 401和消息"Box访问符已过期或无效".
文件夹. boxFolderSources 重现为子文件夹, 遵循 Box 标记呼叫,并设置每个源的 path 到文件夹内的文件路径,所以目的地密钥结束于 / 收到文件夹的版式。 0字节文件为跳过单个文件以其 Box 名称命名, 除非您设置 path。。。 .
复问. 一个429和一个202的文档箱仍在处理中, 之后正在重审 Retry-After,最多5次尝试;中止 prepareProviderSource是因为 signal 停下来单单出现其他故障 BoxApiError 命名状态和 Box 错误代码.
文件大小 . Box的自由计划封顶文件为250 MB;更大的文件需要付费计划.

框作为目的地

A 类 BoxDestinationConfig 通过 Box 上传将每个源作为一个文件写入 Box 文件夹届会。工人将部分直接上传到会话中,并带有文件扫描的上传符号 SDK 薄荷; BeamCore 用单独的控制符来验证和承担会话. 这个用户的符号在此过程中停留 : token_provider 返回每个 Box 调用它需要它,而SDK 从来没有发送到BeamCore.

import { BeamClient, BoxDestinationConfig, BoxProviderConfig } from "@beam-network/sdk";

const beam = new BeamClient({ apiKey: process.env.BEAM_API_KEY! });

const transfer = await beam.createTransfer({
  sources: [BoxProviderConfig.create({ file_id: "1234567890", token: process.env.BOX_ACCESS_TOKEN! })],
  destinations: [
    BoxDestinationConfig.create({
      folder_id: "9876543210",
      token_provider: async () => boxOAuth.currentAccessToken(),
      // Or revoke_token: async (token) => ..., to revoke minted tokens yourself.
      client_id: process.env.BOX_CLIENT_ID!,
      client_secret: process.env.BOX_CLIENT_SECRET!
    })
  ],
  name: "Box to Box"
});

// Keep the client open until the transfer is terminal: BeamCore asks it to renew, revoke,
// finalize and abandon the Box session.
await beam.waitForTransfer(transfer.transfer_id);
await beam.close();

放置. 文件夹中同名文件收到新版本; 否则 sDK 创建了空占位符,如果传输失败,它将再次删除该占位符 . file_name 为单一源命名文件;没有它,每个文件就以其命名来源.
尺寸. 通过新版上传会话上传到20个米B以上的源大小框选择部分( 8、 16 或 32 MiB ); 较小的部分是用单个表单上传;空表由SDK直接写入. 传输无法混合前两种类型,或会话源框给出不同的部分大小: 将其分割为单独转让(BoxDestinationError 与 code box_mixed_upload_kinds 或者说 box_part_size_mismatch) (中文(简体) ).
值得信赖的文摘. 方框要求完整文件的SHA-1进行一个会话. SDK读取它来自Box源的版本,或者来自S3或R2对象的全对象SHA-1校验和. 没有它,BeamCore的源文摘传读取源并供应. 传球仅读取可直接读取的 HTTPS 出处: S3 和 R2 预先签名的 URL 符合条件; Hugging Face and Box 下载,它重新定向,而plain-HTTP URL则不进行. 会话来源没有可信的SHA-1,BeamCore不能消化的,在写出任何内容之前被拒绝 (单位:千美元)box_trusted_digest_required) (中文(简体) ). 通行证从不读取已准备好的源 URL: BeamCore 请客户端为它签署一个获得整个源(sign_source),对 expiresIn 并固定在ETAG和版本记录在准备, 当通行证开始当 URL 即将过期时, 将再次生效 .
一个人. A Box 目的地是它唯一的目的地和另一个客户端无法恢复.
托肯丝. worker_credentials (1至16,默认 1) 每个会话的符号会转到工人,一个控制符贝姆科雷。当BeamCore最终确定或放弃文件,当传输为终端或客户端关闭。关闭客户端时, Box 传输会放弃它 .
限制. Box 符号不能局限于字节范围:任何工人符号都可以写入会话的任何范围。框保留区域的第一个写入和列表会话部件 sha1: null,因此,BeamCore将每个列表部分通过ID Box返回的部分验证将那部分的身份证和整个档案贴上 Digest 犯罪,和在承诺封存之后中止会话。完成SDK检查后, 使用用户的符号,文件的当前版本以及自计划保留承诺的内容.

对于低等原始传输配置, 使用 createRawTransfer;生命周期运输仍然通过NATS.

流程和有效载荷大小

提供者转让的使用 transfer-client-control/v7。每个回复都带有运行时间和运输时代;准备和每个路由流消息都带有UUID路由生成。 S3,R2和S3相容的目的地保留了直接多段上传部分/列表部分/HEAD处理. Hippius和Hugging Face 目的地每块取一个平地PUT,所以它们没有携带多块组表。一个盒子目标发送一个 box_session beamCore 将每组恢复 describe_group。。。 .

客户端默认同时签入64条线路,并发出1,024个路线逻辑批次. 编码信件包请求目标 4 MiB 物理批次 maxPayloadBytes (8 MiB 默认; 仍然支持明确的正覆盖). 分解器为活的认证符和稳定的请求身份保留了控制-信封头室,因此最终编码的请求仍然位于所配置的守护下. 寿命周期控制在最后30秒符号寿命和重试前刷新了缓存的 SDK auth auth_token_expired 以同样的请求身份和有效载荷作出答复,但是一种新鲜的标志,在大型路线流中保留核心请求-冲突保护。 4 MiB目标上方但配置后卫范围内的单一路由单独发布;大于配置后限的单一路由在发布前失败,错误中两个大小都存在. 多段创建和中止请求使用单独的 multipartControlConcurrency 默认限制为2,支持明显的正上方,S3兼容控制请求最多可构成5次短暂提供者故障的尝试. 这使得URL签名的吞吐量独立于供应商控制-平面压力.

需要持久回收核算的呼叫者可提供 onMultipartGroupReadySDK在创建多段上传和流出该组已签名的路由之前引用它。其有效载荷仅包含转让、来源、目的地、对象钥匙、上传、大小、部分计算和过期身份;它从未包括证书、请求信头或已签名的URL。被拒绝的回调中止新创建的上传并失败准备关闭 .

resumeProviderTransfer 需要保存完整的回调有效载荷 multipartGroups它验证每个传输/源/目的地/对象/大小/部分坐标,然后使用与上传ID创建相同的路由-流执行. 在新提供者上传或路由发布前,丢失、复制或更改身份失败。如果一个进程在记录上传身份前已死亡,则将其视为不确定的清理,而不是发明替换. 这个 onPrepared 在恢复期间,在线路流出之前,还进行回调.

创建并恢复接受所有权 signal中止它停止初始路径、多段创建以及恢复签名/重放;它不会取消转移或中止替换所有者的上传。回收租地,签地,和背景的回放/回放由所有者身份按键:被栅栏关闭的拥有者从不回放,放出,或停止注册同一转让的替代所有者的签地,替换者总是得到自己的恢复. 用户取消仍在使用 cancelTransfer 并核实提供者清理. prepareProviderSource 对元数据请求接受相同的信号.

流式ID来源于传输,所选择的流,和不可改变的计划身份,每个被订购的批号ID包括它的路由坐标校验和. 需要手动多目的地附件 delivery_index 在每一个路线。生命周期突变以相同的请求身份重试了三次短暂性故障。无法回收的提供者设置或路由故障 BeamProviderTransferError,其 errors, (中文(简体) ), transferCancelled,以及 multipartCleanupComplete 字段保留原始提供者、取消和清理结果. waitForTransfer 订阅API-key自有,最多一次的终端信号,在第一个状态读取之前,通过权威状态调和每个信号;订阅失败会降为同样焦躁的15至30秒状态回落. 打电话 close() 当客户端不再需要时;它也会关闭杰出的终端服务员.

完成前期间 integrity_check 阶段,运行时间可能包括 integrity_audit_challenge 处于状态。 TypeScript 客户端标记精确的只读源和最终目的地 transfer.integrity_audit_grants. S3兼容源和目的地赠款使用已准备好的源ETag和运行时核实的最后对象ETag作为 If-Match 条件。提交失败在下一次状态调查中重试, 并显示为 URL 安全 integrity_audit_submission_error ; 如果检查无法在截止日期前完成,则转移将附有警告.

Hippius 使用 Canical 非多相 signed_url 路线(PUT到计划中的最初路线和收回的路线) <final>/<plan_nonce>/chunk-NNNNNN 因此,其清单是空的,无法从供应商流中获取集团级总部最后核查结果.

NATS 需要这个守护, 因为经纪人拒绝超过它配置的信息 max_payload。这一限制仅适用于生命周期/控制元数据;传输文件字节不通过NATS流动.

重新启动恢复

客户每次主动转帐都保留一份内存回收租约和一个 runtime.hello 监视器每个活性硬体。租借在路由-流开始前安装,每个转接的锁会与回放相接. 多段恢复保留了现有的上传ID和紧凑的组态,然后只重新签名已到期的路由并执行控制. 每个 resumeProviderTransfer 援引通过明确转让代号重新准备现有转让,并附有新的请求和路由生成,而运输在该援引范围内重复使用同一请求。然后从目前的提供者配置中重新添加路由恢复签名,而不创建重复多段上传. 运行时时代更改无效已缓存的 auth, 联合 one transfer.resume,并在新生代下重新生成路径;只有当运行时报告路径丢失或过期时,只有运输时代才会改变。提供者证书和签名输入只保留在内存,并在终端状态下发布;或 close()低级 attachSignedUrls 需求 routeGenerationId,计划指纹/核对和 recoveryFactory; 签名的 URL 从未被分录到磁盘中。前景取消,期限到期,以及运行时状态损失回复,保留了背景租赁并保留了多段上传.

混合端点签名

证书适配器可以使用 signDestinationUrl 独立 signDestinationRoute,使用相同的提供者配置和多段签名符。只指定目标签名不需要合成源描述符,也不读取源数据. 可选 contentMd5 将工人计算的校验和绑定在供应商的上传上,而不单独进行源校验和扫描.

signSourceReadRange 财务报告和审定财务报表 signSourceObject (一个得到整个来源,没有) Range接受 ifMatch 财务报告和审定财务报表 versionId 用于冷冻S3兼容源. 重放返回的标题不变。 ETag条件签名,版本包含在签名请求中. 不支持的非S3 证书模式拒绝这些条件, 而不是放弃这些条件; 一个 Box 源仅使用 versionId,在准备时记录的文件版本。这些帮助者支持R2,Hippius S3和Hugging Face存储桶所使用的现有的S3相容配置; 枢纽寄存器令牌是一种不同的提供者模式.

只有短寿命的射程/上载路线才流向工人。多段创建、核查、补全和中止仍然停留在现有的控制路径中。仅工人上传响应不是最终对象完成.

listMultipartParts, (中文(简体) ), completeMultipartUpload,以及 inspectDestinationObject 重复使用同一提供者客户端,只返回元数据。 ListParts 将每一页都行走; 完成后提交选定的提供者验证的部分。适配器必须在完成前长期保留上传并核实清单,因此重新启动回收不能从大小中推断交付.

手册 dev 需要承诺 -dev.N 版本并只发布到 npm 标签 dev;稳定标记不变.

多段控制助手( E)createMultipartUpload, (中文(简体) ), listMultipartParts, (中文(简体) ), completeMultipartUpload, (中文(简体) ), inspectDestinationObject,以及 abortMultipartUpload() 接受可选 AbortSignal ,并通过现有的供应商HTTP运输取消。通过它作为 signal 在对象参数中或作为最后一个位置参数。取消停止等待和网络活动;它不能取消已经接受的提供者操作。被中断的完成后,在重试或报告清理工作完成前,检查持久的上传/对象身份.

准备诊断

路由溪流冲出1024道,无定时器,在溪流完成后发送最后部分批次. 通过有限度的缓冲,签字重叠确认的出版;现有的编码活期限制仍然有效。只有在同一批签字人和实际到期的情况下,才在各目的地重新使用源赠款.

可选 onDiagnostics callback收到限量准备测量和源源重用计数。召回是最佳努力,可能被丢入负载,不影响转移结果. 期限可能相重叠;不将其相加为过期的移交时间。传输状态也显示输入 performance 由 Core 支持时的摘要.

可选 storage_location (单位:千美元)StorageLocation (在Go中)描述身体状况存储位置。它与用来签署供应商请求的区域是分开的. 未知时保留它; R2 等签名区域 auto 不是一个位置. 没有它, R2 或 Google Cloud 存储源或目的地会携带位置它的桶报告本身为: bucket_location 在计划中的元数据.

当得到核心支持时,诊断使用 sdk-performance/v2: 直方图, 编制里程碑、货币高水分和单独的供应商, 召回名单签名运输等直方图是非累积的, 上限为0.1、0.5、1、2、5、10、25、50、100、250, 500,1000,2500,5000,1000,30000,120000,再溢出. unmeasured 明确识别无法使用的测量数据。 CPU 包括其他同时进行的工作在 SDK 进程中; 它不是 trans- extract CPU 。详细报告可以是已禁用为 BEAM_SDK_PERFORMANCE_DETAILS=false老年人保留v1报告. 这些诊断中没有资格证明或储存补助金.

sdk.producer_wait 与出版物分开等待签字路线的措施后压。配置的限制测量表保留起始限制;有效限制测量仪显示达到的最高限值。可选 source_renewals 计数源在后几代筹备者中重建赠款。 16个KiB历史轨迹 131,072个块指数;柜台在收购后被省略或超出该约束. 它不包括单独的恢复控制签字行动.

版本	发布日期	距今
`0.12.0`latest	2026/11/07	1 天前
`0.11.4`	2026/11/01	6 天前
`0.11.3`	2026/10/31	7 天前
`0.11.2`	2026/10/31	7 天前
`0.11.1`	2026/10/31	7 天前
`0.11.0`	2026/10/26	12 天前

@beam-network/sdk

类型脚本的 BEAM SDK

证书

信用和密钥出错

计费父母

已签名的 URL 寿命

S3 兼容供应商

拥抱相机

方框

框作为源

框作为目的地

流程和有效载荷大小

重新启动恢复

混合端点签名

准备诊断

版本与发布记录

关于 @beam-network/sdk 的常见问题

@beam-network/sdk 是什么？

如何安装 @beam-network/sdk？

@beam-network/sdk 支持 TypeScript 吗？

@beam-network/sdk 支持 ESM 还是 CommonJS？

@beam-network/sdk 可以商用吗？

@beam-network/sdk 的下载量有多少？

@beam-network/sdk 还在维护吗？