Apostra TypeScript SDK
对公共V3 HTTP API的类型化调用。要求Node.js 22.18或更高版本。
npm install @apostra/sdk
先从 SDK快速入门.
它包括账户发现，活动启动预览和确认，以及
交付报告。这个 可运行synthetic-seller
例子
在SDK源代码签出中。默认情况下，它预览并只确认一个
启动时 APOSTRA_CONFIRM_LAUNCH=true 是故意设定的。
import { Apostra } from '@apostra/sdk'
const api = new Apostra()
const status = await api.getStatus()
客户端读取 APOSTRA_API_KEY， APOSTRA_ACCOUNT_ID 和
APOSTRA_BASE_URL 默认情况下。显式构造函数选项覆盖这些
值。使用 accessToken 获取现有REST/M2M承载令牌，或
tokenProvider 用于应用程序管理的获取和刷新。供应完全
一个凭证来源。 m2mTokenProvider 获取并缓存服务器端
使用已发布的M2M端点的客户端凭证令牌；刷新60
并共享并发刷新。不要放API密钥或
浏览器包、url、示例或日志中的客户端秘密。没有
明确的凭证和否 APOSTRA_API_KEY， Node.js客户端使用登录
那 apostra login 为基URL存储，如果有的话；SDK从来没有
打开浏览器，只写入登录文件（刷新令牌）。这个
包不重放401响应。M2M令牌刷新有一个
默认30秒截止日期；通过 timeoutMs 来推翻它。
import { Apostra, m2mTokenProvider } from '@apostra/sdk'
const api = new Apostra({
tokenProvider: m2mTokenProvider({
clientId: process.env.APOSTRA_CLIENT_ID!,
clientSecret: process.env.APOSTRA_CLIENT_SECRET!,
scope: 'interchange:read',
}),
})
方法接受生成的连线输入并返回信封的输入 data.
每个生成的方法也有 WithResponse 变体，例如
getStatusWithResponse． 它返回 { data, requestId, headers, status } 用于
呼叫成功，使支持工具得以保留 x-request-id 和响应
没有通过连接操作名调度的头文件。
ApostraError 公开 status， code， recovery， retryAfter， retryable，
的类型 error, requestId． 抓 RateLimitError， ValidationError，
或另一个类型化子类，而不是解析异常字符串。默认的
异常字符串排除响应文本。静态类型不能替代服务器
模式、长度、条件要求或权限的验证。
读取调用接受 { accountId, signal, timeoutMs };写调用需要这些
选项，以包含呼叫者拥有的 { idempotencyKey }． SDK将其发送为
Idempotency-Key，永远不会创建或取代它。帐户选择用途
X-SCOPE3-CUSTOMER-ID;它必须与凭据解析的帐户匹配。
取消停止等待HTTP；它不会撤消服务器的工作。请求
有一个30秒的超时，不遵循重定向，并重试瞬态网络，
429和5xx失败两次默认情况下，全抖动退。集
maxRetries: 0 选择退出。自动读取重试。只使用
生成写方法所需的调用者拥有的相同的幂等键。
SDK永远不会创建或替换该密钥。服务器 retry_after 是最小值
重试延迟。
const { data, requestId, headers } = await api.getStatusWithResponse()
const correlationId = headers.get('x-request-id')
一、 202 提出了 InFlightReceiptError 而不是返回一个完整的值。
使用 settle 重放相同的键操作，直到完成；它的荣誉
收据的 Retry-After、截止日期及取消信号：
const key = 'preview-123'
const result = await settle(
(signal) => api.saveAsk(input, { idempotencyKey: key, signal }),
{ timeoutMs: 30_000 },
)
paginate 和 poll 以输入回调为例。保留原有查询参数；
修订和密钥；提供操作的游标/状态访问器。没有助手
假设POST在没有调用者拥有的键的情况下可以安全地重试，或者每个调用者都可以安全地重试
列表具有相同的游标。
轮询将其信号传递给 read(signal);分页将其传递给
read(cursor, signal)． 将该信号转发到SDK调用以取消
底层HTTP请求。超时包括凭据、HTTP和响应体
消费;注入的获取/提供程序必须配合取消
停止自己的工作。取消仍然会阻止SDK等待。
进口 verifyWebhook 仅从服务器端 @apostra/sdk/webhooks 子路径。它
验证保留重复的V3 webhook头，原始体，五分钟
传递窗口，以及在解析JSON之前的旋转键映射。提供每一个原料
发生的 signature， timestamp, deliveryId;不要平复
头或日志秘密。网络安全的 @apostra/sdk root不加载Node
密码学。
openHandoff(url, opener?) 接受API返回的实际HTTPS URL。
如果没有打开器，它只返回URL。一些UI操作当前返回
只有参数。URL构建、登录、等待/恢复和字节上传
除非未来的公共合同对其进行定义，否则不受支持。
getHandoff(result) 将支持的人类行为结果缩小到 kind，
url， expiresAt 和 resume 说明或退货 null． 通过,
键入的值 openHandoff(handoff, opener?);没有开瓶器
返回提供的HTTPS URL。打开或关闭浏览器则不是
完成:跟 resume 并在继续之前读取受影响的对象。
SDK从不构造URL或嵌入登录流。
uploadCreativeAsset 公开当前键入的人工任务和回退URL。
@apostra/sdk/metadata 导出生成的操作名称、路径、安全性和
命令行发现的参数说明。SDK没有终端，浏览器，
配置文件存储或MCP依赖项。从 @apostra/sdk/models.