add-node-sdk

添加 Node.js SDK

在 Node.js / TypeScript 应用中集成 Temps 平台功能。

已通过实际发布的包验证。 旧版本的此技能引用了不存在的 @temps-sdk/node、new Temps({ apiKey, projectId })、temps.track()、new KV({ apiKey, namespace })、kv.has()、blob.get()、blob.getSignedUrl() 和 TempsError —— 这些都不存在。修改前请确认任何 API：

npm pack @temps-sdk/node-sdk@latest @temps-sdk/kv@latest @temps-sdk/blob@latest
for t in temps-sdk-*-*.tgz; do tar -xzf "$t"; echo "== $t =="; cat package/dist/index.d.ts | head -60; rm -rf package; done

三个实际存在的包

包	用途
@temps-sdk/node-sdk	完整的平台 API 客户端（生成式）+ Sentry 风格的服务端错误跟踪
@temps-sdk/kv	Vercel-KV 风格的键值存储
@temps-sdk/blob	Vercel-Blob 风格的文件存储

不存在 @temps-sdk/node。平台客户端包是 @temps-sdk/node-sdk。

npm install @temps-sdk/node-sdk   # platform API + error tracking
npm install @temps-sdk/kv         # optional: KV storage
npm install @temps-sdk/blob       # optional: blob storage

平台 API 客户端 — @temps-sdk/node-sdk

TempsClient 是基于 Temps OpenAPI 接口生成的客户端（hey-api）。使用 baseUrl 和 apiKey 构造，然后调用资源子命名空间。

import { TempsClient } from '@temps-sdk/node-sdk';

const temps = new TempsClient({
  baseUrl: process.env.TEMPS_API_URL!,   // e.g. https://app.temps.sh
  apiKey: process.env.TEMPS_API_KEY,     // create under Settings → API Keys
});

// Resource namespaces (each maps to OpenAPI operations):
// temps.projects, temps.deployments, temps.analytics, temps.sessionReplay,
// temps.domains, temps.dns, temps.backups, temps.crons, temps.email,
// temps.externalServices, temps.files, temps.funnels, temps.git, temps.monitoring,
// temps.notifications, temps.performance, temps.platform, temps.proxyLogs,
// temps.repositories, temps.settings, temps.users, temps.apiKeys, temps.auditLogs, …

const projects = await temps.projects /* .list(...) etc. */;

⚠️ 配置为 { baseUrl, apiKey }（Vercel 风格的 baseUrl），而非 { apiKey, projectId }。顶层没有 temps.track() / temps.identify() —— 分析功能位于 temps.analytics.* 下。请使用编辑器对命名空间的自动补全，或查看 package/dist/index.d.ts 和 client/sdk.gen.d.ts，以确认准确的方法名称和参数结构（它们由生成器生成，可能会变化）。

每次调用都会解析为 { data, error, request, response }（hey-api 结果结构）——使用 data 前请先检查 error。

服务端错误跟踪 — @temps-sdk/node-sdk

node SDK 以 ErrorTracking 命名空间重新导出了兼容 Sentry 的错误跟踪 API。它基于 DSN，行为与 @sentry/node 一致。

import { ErrorTracking } from '@temps-sdk/node-sdk';

ErrorTracking.init({
  dsn: process.env.SENTRY_DSN!,            // Temps DSN, from Error Tracking → DSN & Setup
  environment: process.env.NODE_ENV,
  release: process.env.GIT_SHA,
  tracesSampleRate: 1.0,
});

try {
  doRiskyThing();
} catch (err) {
  ErrorTracking.captureException(err);
}

ErrorTracking.captureMessage('Something notable happened', 'warning');
ErrorTracking.setUser({ id: 'user_123', email: '[email protected]' });
ErrorTracking.addBreadcrumb({ category: 'auth', message: 'logged in', level: 'info' });
const tx = ErrorTracking.startTransaction({ name: 'checkout', op: 'http.server' });
// … tx.startChild(...), tx.finish()

对于大多数错误跟踪工作，建议使用专用的 add-error-tracking 技能：Temps 与 Sentry 在线路协议上兼容，因此建议将官方 @sentry/node SDK 指向 Temps DSN。只有在你明确需要使用捆绑的实现（无需额外依赖）时，才使用 @temps-sdk/node-sdk 中的 ErrorTracking。

KV 存储 — @temps-sdk/kv

Vercel-KV 风格的 API。使用默认的 kv 实例（通过环境变量配置），或构造 KV / createClient。

import { kv } from '@temps-sdk/kv';
// or: import { KV, createClient } from '@temps-sdk/kv';

// Default instance reads TEMPS_API_URL, TEMPS_TOKEN, TEMPS_PROJECT_ID from env.
await kv.set('user:123', { name: 'John' });
await kv.set('session:abc', { userId: '123' }, { ex: 3600 });  // expire in 3600s
const user = await kv.get<{ name: string }>('user:123');        // typed get; null if missing
await kv.incr('counter');
await kv.expire('user:123', 600);
const ttl = await kv.ttl('user:123');                            // seconds; -2 missing, -1 no-expiry
const removed = await kv.del('user:123', 'session:abc');         // count deleted
const matches = await kv.keys('user:*');                         // pattern match

显式创建客户端（不使用基于环境变量的配置时）：

import { KV } from '@temps-sdk/kv';

const store = new KV({
  apiUrl: process.env.TEMPS_API_URL,
  token: process.env.TEMPS_TOKEN,    // API key or deployment token
  projectId: 42,                     // number; required with API keys, inferred from deployment tokens
});

SetOptions（Redis 风格）：{ ex?: number /* sec */, px?: number /* ms */, nx?: boolean, xx?: boolean }。

⚠️ 配置字段为 token（API 密钥或部署令牌）+ projectId: number，而非 apiKey / namespace。不存在 kv.has()、kv.list({prefix})、getWithMetadata 或 { ttl } 这一 set 选项 —— 请使用 { ex } / { px }。KV 错误会抛出 KVError。

Blob 存储 — @temps-sdk/blob

Vercel-Blob 风格的 API。使用默认的 blob 实例，或构造 BlobClient / createClient。

import { blob } from '@temps-sdk/blob';
// or: import { BlobClient, createClient } from '@temps-sdk/blob';

// Upload (returns BlobInfo: { url, pathname, contentType, size, ... })
const info = await blob.put('avatars/user-123.png', imageBuffer, {
  contentType: 'image/png',
  addRandomSuffix: false,   // default true — set false to keep the exact pathname
});

// Download (returns a fetch Response — stream or buffer it yourself)
const res = await blob.download(info.url);
const bytes = Buffer.from(await res.arrayBuffer());

// Metadata
const meta = await blob.head(info.url);

// List with pagination
const { blobs, cursor, hasMore } = await blob.list({ prefix: 'avatars/', limit: 100 });

// Copy and delete
await blob.copy(info.url, 'avatars/backup.png');
await blob.del(info.url);            // also accepts string[] of urls/pathnames

显式创建客户端：

import { BlobClient } from '@temps-sdk/blob';

const store = new BlobClient({
  apiUrl: process.env.TEMPS_API_URL,
  token: process.env.TEMPS_TOKEN,
  projectId: 42,
});

PutOptions：{ contentType?, addRandomSuffix? (default true), cacheControl?, contentEncoding?, contentDisposition? }。

⚠️ 方法为 put / del / head / list / download / copy。不存在 blob.get()、blob.getStream()、blob.getSignedUrl() 或 blob.createUploadUrl() —— 要读取内容，请调用 download(url) 并读取返回的 Response。Blob 错误会抛出 BlobError。

环境变量

变量	使用方	说明
TEMPS_API_URL	node-sdk（baseUrl）、kv、blob	Temps API 的基础 URL，例如 https://app.temps.sh
TEMPS_API_KEY	node-sdk TempsClient	在 Settings → API Keys 下创建
TEMPS_TOKEN	kv、blob	API 密钥或部署令牌
TEMPS_PROJECT_ID	kv、blob	数字项目 ID；使用 API 密钥时必填，使用部署令牌时会自动推断
SENTRY_DSN	node-sdk ErrorTracking	在 Error Tracking → DSN & Setup 中获取 Temps DSN

在 Temps 部署中，将 KV/Blob 服务关联到项目时，系统可能会自动注入这些变量——硬编码之前，请检查项目的环境变量。

最佳实践

1. 切勿硬编码密钥/令牌——从环境变量中读取。
2. 使用 data 之前，先检查 TempsClient 调用的 error（hey-api 结果结构）。
3. 围绕存储调用捕获 KVError / BlobError。
4. 在启动时调用一次 ErrorTracking.init()，并确保在可能抛出异常的代码运行之前完成。
5. 从生成的 .d.ts 中确认方法名称——平台客户端接口由 OpenAPI 生成，并会随 API 演进。