> ## Documentation Index > Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt > Use this file to discover all available pages before exploring further. # SDKs > クライアントライブラリとフレームワーク連携 ## SDKs & ライブラリ Waffo Pancake は TypeScript と Next.js の公式 SDK、および直接 API アクセスを提供しています。 ### 統合レベルの選択 **最速** — ドロップインのコンポーネント、Hooks、Server Actions。チェックアウト UI、Webhook ルーティング、購入者セルフサービスを内蔵。 `npm install @waffo/pancake-nextjs` **柔軟** — 自動署名、型付きレスポンス、Webhook 検証を備えた完全な API カバレッジ。あらゆる Node.js フレームワークで使用可能。 `npm install @waffo/pancake-ts` **完全制御** — 書き込みは REST エンドポイント、読み取りは GraphQL。署名と検証を自前で実装。任意の言語。 **Next.js プロジェクト**：`@waffo/pancake-nextjs` から始めましょう — `@waffo/pancake-ts` をラップし、React コンポーネントと Server Actions を追加します。高度なユースケースでは、TypeScript SDK や生の API 呼び出しにいつでも切り替えられます。 *** ## TypeScript SDK npm 上の公式 TypeScript SDK ### インストール ```bash theme={"system"} npm install @waffo/pancake-ts ``` ### 特徴 * ランタイム依存ゼロ、ESM + CJS、Node >= 20 * リクエスト署名の自動化と決定的冪等キー * 完全な TypeScript 型定義（15 enum、40+ インターフェース） * 組み込み公開鍵による Webhook 署名検証（テスト/本番） ### クイックスタート ```typescript theme={"system"} import { WaffoPancake } from "@waffo/pancake-ts"; const client = new WaffoPancake({ merchantId: process.env.WAFFO_MERCHANT_ID!, privateKey: process.env.WAFFO_PRIVATE_KEY!, }); // ストアを作成 const { store } = await client.stores.create({ name: "My Store" }); // 単発商品を作成 const { product } = await client.onetimeProducts.create({ storeId: store.id, name: "E-Book: TypeScript Handbook", prices: { USD: { amount: "29.00", taxIncluded: false, taxCategory: "digital_goods" }, }, }); // チェックアウトセッションを作成 const session = await client.checkout.createSession({ productId: product.id, currency: "USD", }); // => 消費者を session.checkoutUrl にリダイレクト ``` ### 設定 | パラメータ | 型 | 必須 | 説明 | | ------------ | -------------- | --- | -------------------------------- | | `merchantId` | `string` | はい | マーチャント ID | | `privateKey` | `string` | はい | RSA 秘密鍵（PEM、base64、生データ — 自動正規化） | | `baseUrl` | `string` | いいえ | API ベース URL（デフォルト：本番環境） | | `fetch` | `typeof fetch` | いいえ | カスタム fetch 実装 | ### 利用可能なリソース | ネームスペース | メソッド | 説明 | | ---------------------------------- | -------------------------------------------------- | ----------------------- | | `client.stores` | `create()` `update()` `delete()` | ストア管理 | | `client.onetimeProducts` | `create()` `update()` `publish()` `updateStatus()` | 単発商品 CRUD | | `client.subscriptionProducts` | `create()` `update()` `publish()` `updateStatus()` | サブスクリプション商品 CRUD | | `client.subscriptionProductGroups` | `create()` `update()` `delete()` `publish()` | 商品グループ（共有トライアル） | | `client.orders` | `cancelSubscription()` | 注文管理 | | `client.checkout` | `createSession()` | チェックアウトセッション作成 | | `client.graphql` | `query()` | 型付き GraphQL クエリ | | `client.auth` | `issueSessionToken()` | チェックアウト用の購入者セッショントークン発行 | | `client.webhooks` | `verify()` | Webhook 署名検証 | ### チェックアウトモード SDK は、購入者の身元を把握しているかどうかに基づいて2つのチェックアウトモードをサポートしています： | モード | メソッド | 購入者ID | フォーム | ユースケース | | -------- | --------------------------------- | --------- | ------ | --------------- | | **認証済み** | `checkout.authenticated.create()` | マーチャントが提供 | 事前入力済み | ユーザーアカウントのあるサイト | | **匿名** | `checkout.anonymous.create()` | 提供なし | 空 | テンプレートストア、共有リンク | \*\*購入者を把握している場合は、必ず認証済みチェックアウトを使用してください。\*\*認証済みチェックアウトは、注文をあなたが提供する `buyerIdentity` に紐付けます — マーチャントが管理する安定した識別子です。これがない場合： * **トライアル悪用**：購入者がメールアドレスを変更するだけで無制限に無料トライアルを取得可能 * **注文の紐付け解除**：異なるメールは異なるユーザーとして扱われる * **セルフサービス不可**：購入者はカスタマーポータルで注文管理ができない #### 認証済みチェックアウト（推奨） ```typescript theme={"system"} const result = await client.checkout.authenticated.create({ productId: "PROD_xxx", currency: "USD", buyerIdentity: "userIdInYourSystem", }); // Redirect: res.redirect(result.checkoutUrl) or window.location.href = result.checkoutUrl ``` `buyerIdentity` は注文帰属とトライアル追跡にのみ使用され、チェックアウトページには表示されません。チェックアウトフォームのメール欄を事前入力するには、`buyerEmail` を明示的に渡してください。 動的価格設定とトライアル制御： ```typescript theme={"system"} const result = await client.checkout.authenticated.create({ productId: "PROD_xxx", currency: "USD", buyerIdentity: "userIdInYourSystem", buyerEmail: "customer@example.com", priceSnapshot: { amount: "19.99", taxCategory: "digital_goods" }, withTrial: true, billingDetail: { country: "US", isBusiness: false }, successUrl: "https://example.com/thank-you", }); ``` #### 匿名チェックアウト ```typescript theme={"system"} const result = await client.checkout.anonymous.create({ productId: "PROD_xxx", currency: "USD", }); // priceSnapshot と withTrial もサポート ``` ### Webhook 検証 ```typescript theme={"system"} import { verifyWebhook, WebhookEventType } from "@waffo/pancake-ts"; // Express（生の body を使用 — パース済み JSON は署名検証を壊す） app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => { try { const event = verifyWebhook( req.body.toString("utf-8"), req.headers["x-waffo-signature"] as string, ); res.status(200).send("OK"); switch (event.eventType) { case WebhookEventType.OrderCompleted: // 注文完了を処理 break; case WebhookEventType.SubscriptionActivated: // サブスクリプション有効化を処理 break; } } catch { res.status(401).send("Invalid signature"); } }); // Next.js App Router export async function POST(request: Request) { const body = await request.text(); const sig = request.headers.get("x-waffo-signature"); try { const event = verifyWebhook(body, sig); // イベントを処理 ... return new Response("OK"); } catch { return new Response("Invalid signature", { status: 401 }); } } ``` ### エラーハンドリング ```typescript theme={"system"} import { WaffoPancakeError } from "@waffo/pancake-ts"; try { await client.stores.create({ name: "" }); } catch (err) { if (err instanceof WaffoPancakeError) { console.log(err.status); // 400 console.log(err.errors); // [{ message: "...", layer: "store" }, ...] } } ``` *** ## Next.js SDK 公式 Next.js SDK — コンポーネント、Hooks、Server Actions ### インストール ```bash theme={"system"} npm install @waffo/pancake-nextjs ``` ピア依存として `@waffo/pancake-ts` が必要です。Next.js 14+ App Router で動作します。 ### クライアントエクスポート | エクスポート | タイプ | 説明 | | ---------------------------- | -------- | -------------------------------- | | `CheckoutButton` | コンポーネント | 3モードのチェックアウトボタン（リンク / 匿名 / 認証済み） | | `WaffoPancakeProvider` | コンポーネント | 自動トークンライフサイクル付きの購入者セルフサービスコンテキスト | | `useCheckout()` | Hook | プログラムによるチェックアウト制御 | | `useBuyer()` | Hook | 購入者セルフサービスアクション（キャンセル、返金、再開、クエリ） | | `useBuyerOrders()` | Hook | 購入者の注文を取得 | | `useBuyerPayments()` | Hook | 購入者の支払い記録を取得 | | `useBuyerRefundTickets()` | Hook | 購入者の返金チケットを取得 | | `useMerchantOrders()` | Hook | マーチャントダッシュボードの注文 | | `useMerchantSales()` | Hook | マーチャントの売上概要 | | `useMerchantSubscriptions()` | Hook | マーチャントのサブスクリプション概要 | | `Webhook` | ルートハンドラー | 自動署名検証とイベントディスパッチ | ### サーバーエクスポート (`@waffo/pancake-nextjs/server`) | エクスポート | 説明 | | ----------------------------------- | --------------------------------- | | `createCheckoutAction(config)` | Server Action: チェックアウトセッション作成 | | `createBuyerTokenAction(config)` | Server Action: 購入者セッショントークン発行 | | `createBuyerSessionAction(config)` | Server Action: 購入者セルフサービス操作 | | `createMerchantQueryAction(config)` | Server Action: マーチャント GraphQL クエリ | ### クイック例 ```typescript theme={"system"} // app/lib/actions.ts "use server"; import { createCheckoutAction, createBuyerTokenAction } from "@waffo/pancake-nextjs/server"; const config = { merchantId: process.env.WAFFO_MERCHANT_ID!, privateKey: process.env.WAFFO_PRIVATE_KEY!, }; export const checkoutAction = createCheckoutAction(config); export const issueBuyerToken = createBuyerTokenAction(config); ``` ```tsx theme={"system"} // app/components/BuyButton.tsx "use client"; import { CheckoutButton } from "@waffo/pancake-nextjs"; import { checkoutAction } from "@/app/lib/actions"; export function BuyButton({ productId }: { productId: string }) { return ( Subscribe Now ); } ``` ### Webhook ルートハンドラー ```typescript theme={"system"} // app/api/webhooks/waffo/route.ts import { Webhook } from "@waffo/pancake-nextjs"; export const POST = Webhook({ onOrderCompleted: async (event) => { // デジタル商品を配信 }, onSubscriptionActivated: async (event) => { // アクセスをプロビジョニング }, onSubscriptionCanceled: async (event) => { // アクセスを取り消し }, }); ``` ステップバイステップの Next.js 統合ガイド。 *** ## 直接 API アクセス REST および GraphQL API を直接利用することもできます。API Key 認証は SDK が自動処理するため、手動でヘッダーを設定する必要はありません。 ```typescript theme={"system"} // 商品を作成 const { product } = await client.onetimeProducts.create({ storeId: "your-store-uuid", name: "My Product", prices: { USD: { amount: "29.00", taxIncluded: false, taxCategory: "saas" }, }, }); // GraphQL でデータをクエリ const data = await client.graphql.query<{ stores: Array<{ id: string; name: string; status: string }> }>( `{ stores { id name status } }` ); ``` *** ## SDK ロードマップ | 言語 | ステータス | | ------------------------ | ------------------------------------------------------------------------------------- | | **Node.js / TypeScript** | 公開済み — [`@waffo/pancake-ts`](https://www.npmjs.com/package/@waffo/pancake-ts) | | **Next.js** | 公開済み — [`@waffo/pancake-nextjs`](https://www.npmjs.com/package/@waffo/pancake-nextjs) | | **Python** | 計画中 | | **Go** | 計画中 | | **PHP** | 計画中 | *** ## フレームワークガイド Next.js と Server Actions で構築。 プログラムでチェックアウトフローを作成。 定期課金の実装。 リアルタイムのイベント通知を受信。 *** ## API リファレンス エンドポイントの完全なドキュメント： REST および GraphQL API の完全なドキュメント。