@alguna/ sdk (英语)

官方类型SDK 阿尔古纳 API: 基于用法 账单、订阅、发票和付款。 从0.3升级? 读取 误入歧途。 。 。 .

安装

npm install @alguna/sdk

SDK需要20或以后的节点.js, 或者另一个与全局运行的时间 fetch 财务报告和审定财务报表 crypto.randomUUID()比如德诺、邦克或克洛德弗莱尔工人 仅在服务器上使用: API 密钥是一个秘密 .

客户端

在仪表板下创建 API 密钥 设置 – 连接 – 开发者 – API 密钥。 。 。 . 钥匙看起来像 <key_id>.<key_secret>。 。 。 .

import { Alguna } from "@alguna/sdk";

// With no options, the client reads the key from ALGUNA_API_KEY.
const alguna = new Alguna();

const sandbox = new Alguna({
  apiKey: process.env.ALGUNA_SANDBOX_API_KEY, // a string, or a function called on every request
  apiVersion: "2026-04-01", // default: the version this SDK release targets
  baseUrl: "https://api.sandbox.alguna.io", // default: https://api.alguna.io
  headers: { "X-Trace-Id": "abc" }, // sent on every request
  fetch: globalThis.fetch, // your own fetch, for example to add tracing
  logging: { level: "debug", silent: false }, // silent by default
});

new Alguna() 丢出一个 AlgunaError 当它找不到钥匙时:没有 process.env (工人,德诺),通过 apiKey笔 apiVersion 保持您的整合 当您升级软件包时, 一个 API 版本 。 SDK发送 User-Agent: alguna-ts/<version> 在运行时间允许的情况下( 不在浏览器中); a User-Agent 内 headers 替换它. console.log(alguna) 财务报告和审定财务报表 JSON.stringify(alguna) 从不打印 API 密钥.

请求

客户端每个 API 资源有一个字段(alguna.customers, (中文(简体) ), alguna.subscriptions, (中文(简体) ), alguna.invoices, (中文(简体) ), alguna.wallets)和每次操作的一种方法。 请求和 响应类型从软件包根导出(CreateCustomerRequest, (中文(简体) ), InvoiceResponse)和在 AlgunaApi 名称空间.

import { Alguna } from "@alguna/sdk";

const alguna = new Alguna();

const customer = await alguna.customers.create({
  name: "Acme Corp",
  currency: "USD",
  contacts: [{ email: "[email protected]", is_primary: true }],
});

const invoice = await alguna.invoices.create({
  customer_id: customer.id,
  currency: "USD",
  line_items: [{ description: "Onboarding", unit_price: "500.00", quantity: "1" }],
});

// A hosted customer portal session, where the customer can pay. It is valid for 1 hour.
const session = await alguna.portal.createSession({ customer_id: customer.id });
console.log(invoice.id, session.url);

每一种方法都以每个请求选项作为其最后的论点: idempotencyKey (写作), timeoutInSeconds, (中文(简体) ), maxRetries, (中文(简体) ), headers 财务报告和审定财务报表 abortSignal。 。 。 . invoices.generatePdf, (中文(简体) ), quotes.getPdf 财务报告和审定财务报表 subscriptions.downloadPdf 返回 a BinaryResponse: 读取用 arrayBuffer(), (中文(简体) ), blob() 或者说 stream()。 。 。 .

对于SDK尚未覆盖的终点, alguna.fetch(path, init, options) 发送原始 请使用客户端的认证、信头、超时、“同上”键和重试。 它回来了 平原地区 Response不论地位如何 当你通过 init、方法、标题和正文 来自 init 只是,不是从一个 Request 你通过作为 path. 溪流体,例如: 机构名称 Request,在第一次尝试之前读入内存,以便重试可以发送 又来了.

倾斜

列表方法返回 a Page数字 : data 持有当前页面的项目,以及 response 整个身体,与 pagination。 。 。 .

import { Alguna } from "@alguna/sdk";

const alguna = new Alguna();

const page = await alguna.customers.list({ limit: 50 });
console.log(page.data.length, page.response.pagination); // { per_page, total_pages }

// The SDK gets the next page when you need it.
for await (const customer of await alguna.customers.list({ limit: 100 })) {
  console.log(customer.id);
}

API发送最多操作 limit 最大每页(今天每个列表100个). 第一页的重复停止,项目少于 limit,或当 limit 规模更大。 当最后一页完全满后, SDK 还会再提出一个请求 返回空页。 手接一页,使用 page.hasNextPage() 财务报告和审定财务报表 page.getNextPage()。 。 。 .

失职和重审

每一个请求,如果不是一个GET 发送 Idempotency-Key: 专辑 idempotencyKey,或一个 UUID v4是SDK为呼叫而作. 每次重试都发出相同的键,所以 API 返回第一个结果, 并且不再写 。 自己把钥匙交出来 重复给自己打电话, 例如在重启后:

import { Alguna } from "@alguna/sdk";

const alguna = new Alguna();

await alguna.customers.create(
  { name: "Acme Corp", currency: "USD" },
  { idempotencyKey: "signup-1234" },
);

例外情况是 events.ingest, (中文(简体) ), credits.track 财务报告和审定财务报表 credits.check: 它们没有自动 键,因为API通过请求机构来识别他们的工作. 它可以删除重复的事件 unique_id, (中文(简体) ), 财务报告和审定财务报表 credits.track 同一人的功劳 unique_ids. 每一次呼叫都有新的钥匙 将身份替换为 credits.track,所以一个电话再次发出,例如通过排队,会 抽两次功劳 SDK在没有钥匙的情况下重复这些通话. 您通过的一个密钥被发送到 每一个尝试. credits.check 与 reserve 需要您的密钥, 因为密钥识别 别动.

失败的尝试默认要重审两次( 总共3次) :

• 状态为 408, (中文(简体) ), 429, (中文(简体) ), 502, (中文(简体) ), 503 或者说 504· ;
• 状态为 409 带有 Retry-After 头曰. API 仅在请求时发送此选项 相同的密钥仍在运行。 A 类 409 无 Retry-After 真正的冲突 未再审;
• 未收到任何回复:连接被拒绝、重新设置或关闭,或尝试超时. 工人、 Deno 和浏览器没有说明为什么连接失败, 所以有 TLS 错误 复试也. 这很安全:每个经重审的请求都是GET,带有"同上"的Key,或者是 以上例外情况之一.

SDK 在您中断呼叫后不重试 abortSignal在尝试之间 等待 1 s, 然后是 2 s, 随机的焦点为 10% 。 当反应有 Retry-After (秒或一个HTTP日期),它等待了那么长时间,最多60 s. 设定 maxRetries 编辑 客户端或一通电话; 0 关闭复试.

超时

60 s. s. set 之后的每次尝试时间 timeout (以毫秒计) timeoutInSeconds 一个电话。 计时尝试被重审,所以一个电话可以接 3×超时加等. 为了限制整个通话 通过一个 abortSignal: 当 中止, SDK 丢弃 AbortError。 。 。 .

import { Alguna } from "@alguna/sdk";

const alguna = new Alguna({ timeout: 10_000 });

// Each attempt may take 5 s; the call, with its retries, at most 20 s.
const customer = await alguna.customers.get("cus_123", {
  timeoutInSeconds: 5,
  abortSignal: AbortSignal.timeout(20_000),
});
console.log(customer.name);

错误

SDK 抛出的每一个错误 AlgunaError数字 :

import { Alguna, AlgunaError, NotFoundError, RateLimitError } from "@alguna/sdk";

const alguna = new Alguna();

try {
  await alguna.customers.get("nope");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(error.message, error.statusCode, error.requestId);
  } else if (error instanceof RateLimitError) {
    console.log("retry in", error.headers["retry-after"], "seconds");
  } else if (error instanceof AlgunaError) {
    console.log(error.cause); // the underlying error, when there is one
  } else {
    throw error;
  }
}

答复错误 message, (中文(简体) ), statusCode, (中文(简体) ), requestId, (中文(简体) ), code (当身体有 一个, body 财务报告和审定财务报表 headers (小写). message 是尸体的吗 detail,否则 title, (中文(简体) ), 其它类型 message,否则 HTTP 状态文本。 连接失败没有 statusCode; 其编号 cause 保存原始错误。 给我 requestId 当您联系到支援时.

网络呼号

AlgunaWebhookEvent 是每个网友组成的联盟 收缩 type 键入 data数字 :

import type { AlgunaWebhookEvent } from "@alguna/sdk";

function handle(event: AlgunaWebhookEvent) {
  switch (event.type) {
    case "payment.created":
      console.log(event.data.amount); // a decimal string
      break;
    default:
      break; // new event types can arrive before you upgrade
  }
}

SDK类型为有效载荷;它不检查Alguna是否发送了有效载荷. 阿尔古纳签下每批货 与斯维克丝. 在你相信有效载荷之前 验证一下它 svix-id, (中文(简体) ), svix-timestamp 财务报告和审定财务报表 svix-signature 与 Svix 库相对的原始请求正文 : new Webhook(secret).verify(rawBody, headers)。见 验证签名。 。 。 .

参考文献

• 脚本 SDK 指南
• API 参考
• 错误 财务报告和审定财务报表 一能性
• 支助: 支持@alguna.io,与 requestId 失败的呼叫

关于这个雷波

Alguna从一个私人寄存器中的Alguna API spec生成这个SDK. 二. 未决问题 在这里。 Alguna 端口代码更改生成器,所以此处的拉出请求不会像现在这样合并.