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

実際に存在する3つのパッケージ

パッケージ	用途
@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 は、Sentry 互換のエラートラッキング API を ErrorTracking 名前空間として再エクスポートします。これは DSN ベースで、@sentry/node と同様の API です。

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 のワイヤー形式と互換性があるため、Temps DSN を指定した公式の @sentry/node SDK を使う方法が推奨されます。追加の依存関係を避け、同梱の実装を使いたい場合に限り、@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 とともに更新されます。