JavaScript / TypeScript
フレームワークを問わずサーバーで使う SDK。
@nulogic/cozeni-sdk はフレームワークを問わずサーバーで使う SDK です。お客様の権利を確かめる createCustomerClient と、商品を管理する createManagementClient の2つのクライアントを提供します。Next.js のサイトに組み込むときは、Next.js のページを読んでください。
インストール
npm install @nulogic/cozeni-sdk@0.8.0pnpm add @nulogic/cozeni-sdk@0.8.0yarn add @nulogic/cozeni-sdk@0.8.0bun add @nulogic/cozeni-sdk@0.8.0nub add @nulogic/cozeni-sdk@0.8.0aube add @nulogic/cozeni-sdk@0.8.0最小のコード例
お客様が商品を持っているかを確かめる例です。Web 標準の Request と Response を使います。
import { createCustomerClient, enterRedirectResponse } from "@nulogic/cozeni-sdk";
const customer = createCustomerClient({ environment: "production" });
export async function GET(request: Request) {
const productId = "prd_...";
const result = await customer.checkEntitlement({
productId,
cookieHeader: request.headers.get("cookie") ?? undefined,
});
if (result.entitled) return new Response("限定の内容");
// 障害は購入していないことと区別し、再入場へ送らない
if (result.reason === "unavailable")
return new Response("時間をおいて再度お試しください", { status: 503 });
// enter_url があれば、メールアドレスの入力画面へ送る
return (
enterRedirectResponse(result, productId) ??
new Response("購入を確認できませんでした", { status: 403 })
);
}
サンドボックス
接続先をサンドボックスにするには、environment に "sandbox" を渡します。
const customer = createCustomerClient({ environment: "sandbox" });
const cozeni = createManagementClient({
apiKey: process.env.COZENI_API_KEY!,
environment: "sandbox",
});
サンドボックスのキーは environment: "sandbox" と組にします。キーを取り違えると、API が認証エラー(HTTP 401)を返します。
接続先
関数は環境変数を読みません。接続先は次のどちらかで指定します。
environment:"production"か"sandbox"です。apiOrigin:接続先のオリジンを直接指定します。通常は使わず、environmentを使ってください。
どちらも省略すると、本番に接続します。両方を指定したときに apiOrigin が environment のオリジンと一致しなければ、作成時に invalid_input を投げます。
主な関数
購入者のクライアント
createCustomerClient(options) で作ります。キーは要りません。
| オプション | 型 | 意味 |
|---|---|---|
environment |
"production" | "sandbox" |
接続先です。省略すると本番です。 |
apiOrigin |
string |
接続先のオリジンです。environment と併用するときは一致させます。 |
fetch |
typeof fetch |
fetch の差し替えです。テストに使います。 |
timeoutMs |
number |
通信の待ち時間です。既定は10000(10秒)、範囲は1から120000です。 |
| メソッド | 引数 | 戻り値 |
|---|---|---|
checkEntitlement |
{ productId, cookieHeader? } |
Entitlement(下表) |
exchangeHandoff |
code |
{ token } |
createPortalLink |
{ cookieHeader?, creatorId? }(省略可) |
{ url } |
各メソッドは非同期です。戻り値は Promise なので、await で結果を受け取ります。
checkEntitlement の戻り値は次のとおりです。通信の失敗では例外を投げず、unavailable を返します。
| 戻り値 | 意味 |
|---|---|
{ entitled: true } |
権利があります。 |
{ entitled: false, reason: "no_grant" } |
購入していない、または商品が見つかりません。 |
{ entitled: false, reason: "revoked" } |
権利が取り消されました。 |
{ entitled: false, reason: "no_session" } |
購入者として入場していません。 |
{ entitled: false, reason: "unavailable" } |
Cozeni に問い合わせられませんでした。購入していないものとして扱わないでください。 |
no_grant、revoked、no_session には、入場画面への URL を表す enterUrl が付くことがあります。unavailable には付きません。
exchangeHandoff は cozeni_code の値を60秒以内に1回だけ交換します。得た token は customerCookie で Cookie にします。
createPortalLink は購入者ポータルへの URL を発行します。URL のコードは60秒で失効し、1回しか使えません。ページの描画時に発行せず、お客様がボタンを押したときに発行してください。お客様がこのサイトで入場していない(cozeni_customer の Cookie が無い)ときは、Cozeni に問い合わせずに CozeniError(code が no_session)を投げます。
管理のクライアント
createManagementClient(options) で作ります。apiKey は必須です。空の値や空白を含む値では、作成時に invalid_input を投げます。キーはサーバーの環境変数に置き、ブラウザに渡さないでください。
| オプション | 型 | 意味 |
|---|---|---|
apiKey |
string |
API キーです。必須です。 |
environment |
"production" | "sandbox" |
接続先です。省略すると本番です。 |
apiOrigin |
string |
接続先のオリジンです。 |
fetch |
typeof fetch |
fetch の差し替えです。 |
timeoutMs |
number |
通信の待ち時間です。既定は10000(10秒)、範囲は1から120000です。 |
| メソッド | 引数 | 戻り値と説明 |
|---|---|---|
account.get() |
なし | アカウントの情報と、販売状態(sales)を返します。 |
products.list(input?) |
{ limit?, cursor? } |
商品の一覧を { items, next_cursor } で返します。limit の既定は20、最大は100です。 |
products.get(id) |
商品ID | 商品1件を返します。 |
products.create(input, settings) |
商品の入力、{ idempotencyKey } |
商品を作成し、商品1件を返します。idempotencyKey は必須です。同じ操作を再送するときは、同じ値を使います。 |
products.update(id, input) |
商品ID、{ name?, price_jpy?, access_url?, metadata?, description? } |
商品を変更し、更新後の商品1件を返します。 |
products.putImage(id, file) |
商品ID、Blob |
商品画像を1枚設定します。JPEG、PNG、WebP のいずれかで、5MB までです。既存の画像は差し替わります。更新後の商品1件を返します。 |
products.deleteImage(id) |
商品ID | 商品画像を外し、更新後の商品1件を返します。画像が無くても成功します。 |
checkoutLinks.get(productId) |
商品ID | 購入リンクを取得します。未発行なら発行しません。 |
checkoutLinks.ensure(productId) |
商品ID | 購入リンクを取得します。未発行なら発行します。 |
createCheckout({ productId, email }) |
商品ID、メールアドレス | 機能フラグの購入画面を作り、{ checkoutId, url, expiresAt } を返します。URL はログイン中の本人にだけ渡し、30分で失効します。 |
getCustomerState({ email }) |
メールアドレス | 付いている機能フラグをすべて返します。 |
hasFeatureFlag({ email, productId }) |
メールアドレス、商品ID | 特定の商品の機能フラグを確かめ、{ granted, metadata } を返します。無ければ { granted: false, metadata: {} } です。 |
管理のクライアントの各メソッドも非同期で、戻り値は Promise です。商品や購入リンクの項目は、API リファレンス の応答と同じです。
products.create と products.update の description は商品の説明(Markdown)です。前後の空白を除いて4000コードポイントまで指定できます。
商品を作って購入リンクを受け取る例です。
import { randomUUID } from "node:crypto";
import { createManagementClient } from "@nulogic/cozeni-sdk";
const cozeni = createManagementClient({
apiKey: process.env.COZENI_API_KEY!,
environment: "production",
});
// 冪等キー。応答を受け取れずに再送するときは、同じ値を使う
const idempotencyKey = randomUUID();
const product = await cozeni.products.create(
{ name: "限定ハンドブック", price_jpy: 1000, access_url: "https://example.com/members" },
{ idempotencyKey },
);
// 購入リンクを取得する。未発行なら発行する
const link = await cozeni.checkoutLinks.ensure(product.id);
console.log(product.id, link.url);
price_jpy は円をそのまま整数で渡します。機能フラグの商品を作るときは、access_url の代わりに access_type: "feature" と設定値の metadata を渡します。
機能フラグの関数の詳しい使い方は 購入者の状態 を見てください。
Cookie とリダイレクトのヘルパー
| 関数 | 戻り値 |
|---|---|
trustedSiteUrl(siteOrigin, path) |
siteOrigin を基準に path を解決した URL です。別のオリジンになる場合やユーザー名・パスワードを含む場合は、CozeniError(invalid_input)を投げます。 |
enterRedirectUrl(result, productId) |
入場画面への URL。使えないときは undefined です。 |
enterRedirectResponse(result, productId) |
303 の Response。使えないときは undefined です。HTML を返すページの入口で使います。 |
customerCookie(token, siteOrigin) |
購入者の Cookie を設定する Set-Cookie の値です。 |
clearCustomerCookie(siteOrigin) |
購入者の Cookie を消す Set-Cookie の値です。 |
enterRedirectResponse は HTML を返すページの入口で使ってください。JSON を返す API では、リダイレクトせずに enterUrl を本文に含めます。
result と productId の組は checkEntitlement を呼んだときの値と一致させてください。一致しない enterUrl は採用されません。
エラー
API の呼び出しが失敗すると、CozeniError を投げます。checkEntitlement は例外を投げず、unavailable を返します。
| プロパティ | 内容 |
|---|---|
code |
エラーのコードです。例:invalid_input、rate_limited、unavailable、timeout、already_purchased、no_session。 |
status |
HTTP のステータスです。通信の失敗では 0 です。 |
requestId |
問い合わせのための ID です。無いこともあります。 |
retryAfterSeconds |
rate_limited のときの待つ秒数です。 |
CozeniError はキーやお客様のコード、応答の本文を保持しません。詳しいエラーの一覧は エラー と レート制限 を見てください。