コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

JavaScript / TypeScript

フレームワークを問わずサーバーで使う SDK。

@nulogic/cozeni-sdk はフレームワークを問わずサーバーで使う SDK です。お客様の権利を確かめる createCustomerClient と、商品を管理する createManagementClient の2つのクライアントを提供します。Next.js のサイトに組み込むときは、Next.js のページを読んでください。

インストール

npm install @nulogic/cozeni-sdk@0.8.0
pnpm add @nulogic/cozeni-sdk@0.8.0
yarn add @nulogic/cozeni-sdk@0.8.0
bun add @nulogic/cozeni-sdk@0.8.0
nub add @nulogic/cozeni-sdk@0.8.0
aube 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 を渡します。

機能フラグの関数の詳しい使い方は 購入者の状態 を見てください。

関数 戻り値
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 はキーやお客様のコード、応答の本文を保持しません。詳しいエラーの一覧は エラー と レート制限 を見てください。

次に読むページ

このページは役に立ちましたか?