Next.js
Next.js(App Router)用のヘルパー。
@nulogic/cozeni-sdk/next は Next.js(App Router)で購入者限定ページを守るためのヘルパーです。Next.js 15 と 16 に対応します。お客様が戻ってきたときのコードの交換、ページの認可、入場画面へのリダイレクトを行います。
インストール
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.0next は peer dependency です。対応するバージョンは ^15.0.0 || ^16.0.0 です。
最小のコード例
proxy と、保護するページの例です。Route Handler、Server Action、購入者ポータルへのボタンまで含む完成例は、SDK の導入例(examples/nextjs)にあります。
Next.js 16 では proxy.ts に書きます。Next.js 15 では middleware.ts に export { cozeniProxy as middleware } from "@nulogic/cozeni-sdk/next"; と書きます。
export { cozeniProxy as proxy } from "@nulogic/cozeni-sdk/next";
export const config = {
matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
import { AccessDenied, requireEntitlement } from "@nulogic/cozeni-sdk/next";
export const dynamic = "force-dynamic";
export default async function Page() {
try {
// 権利が無ければ入場画面へ redirect する
await requireEntitlement("prd_...");
} catch (error) {
// redirect() の例外は握りつぶさず、投げ直す
if (!(error instanceof AccessDenied)) throw error;
return <p>表示できません</p>;
}
return <p>限定の内容</p>;
}
サンドボックス
サンドボックスに接続するには、サーバーの環境変数に COZENI_ENVIRONMENT=sandbox を設定します。ローカルでは .env.local に書きます。.env.local は Git に含めないでください。
COZENI_SITE_ORIGIN=http://localhost:3000
COZENI_ENVIRONMENT=sandbox
サンドボックスで機能フラグを使うときは、COZENI_API_KEY にも同じ環境のキーを設定します。環境変数の一覧は下の「主な関数」の「環境変数」を見てください。
主な関数
ハンドオフ
お客様が Cozeni から戻ったときに、cozeni_code を交換して Cookie を設定します。
| 関数 | 使う場所 | 振る舞い |
|---|---|---|
cozeniProxy(request) |
proxy.ts の proxy、または middleware.ts |
cozeni_code 付きの GET でコードを交換し、cozeni_customer を設定します。コードを除いた同じ URL へ 303 で戻します。 |
handleCozeniHandoff(request, options?) |
既存の proxy、middleware の中 | コードの交換だけを行います。戻り値が undefined でなければ、その Response を返します。 |
clearCozeniHandoff(request, response) |
既存の proxy、middleware の中 | 直前のハンドオフの結果を示す Cookie を消し、Response を返します。 |
cozeniProxy と handleCozeniHandoff は非同期で、Response または undefined を返します。handleCozeniHandoff の options は次の項目を指定できます。すべて省略できます。
| オプション | 意味 |
|---|---|
apiOrigin |
API のオリジンです。省略すると環境変数から決まります。 |
siteOrigin |
戻り先のサイトのオリジンです。省略すると COZENI_SITE_ORIGIN を使います。 |
fetch |
fetch の差し替えです。テストに使います。 |
timeoutMs |
通信の待ち時間です。既定は5000(5秒)、範囲は1から120000です。 |
cozeniProxy はオプションを受け取りません。
ハンドオフの結果は cozeni_handoff という Cookie で次のリクエストに伝えます。値は ok、invalid_code、unavailable のいずれかで、有効期間は60秒です。
既存の認証や middleware がある場合は、cozeniProxy で置き換えないでください。handleCozeniHandoff と clearCozeniHandoff を、既存の処理に組み込みます。
ページの認可
| 関数 | 使う場所 | 振る舞い |
|---|---|---|
requireEntitlement(productId, options?) |
ページだけ | 権利があれば何も返さず完了します。権利が無く、入場画面の URL があれば redirect します。ハンドオフの直後、判定できないとき、URL が無いときは AccessDenied を投げます。 |
AccessDenied |
requireEntitlement の catch |
拒否の理由(reason)と、判定結果(entitlement)を持ちます。 |
entitlement(productId, options?) |
Route Handler、Server Action | Promise<Entitlement> を返します。redirect はしません。 |
nextEntitlement(options) |
API の接続先を直接指定するとき | options.apiOrigin と options.productId は必須です。Cookie から購入者を読み、Promise<Entitlement> を返します。接続先の設定不備や通信の失敗では unavailable を返します。 |
denialStatus(reason) |
拒否理由からステータスだけを得たいとき | no_session は 401、unavailable は 503、no_grant と revoked は 403 を返します。 |
denialResponse(result, productId) |
Route Handler | 拒否の JSON を返します。no_session は 401、unavailable は 503、そのほかは 403 です。入場画面の URL は enter_url として本文に含みます。 |
Entitlement の形は JavaScript / TypeScript と同じです。entitlement と商品IDを渡す形の requireEntitlement の options は、fetch と timeoutMs を指定できます。待ち時間の既定は10000(10秒)、範囲は1から120000です。nextEntitlement の options にも同じ2項目を指定できます。
requireEntitlement の戻り値は Promise<void> です。入場画面へ送るときは redirect の例外を投げます。try の中では AccessDenied だけを捕まえ、それ以外の例外(redirect を含む)は投げ直してください。
Server Action では Response を返さず、entitlement の理由を通常の戻り値として返します。
購入者ポータル
| 関数 | 使う場所 | 振る舞い |
|---|---|---|
portalRedirect(creatorId, options?) |
Route Handler の GET |
購入者ポータルへのリンクを発行して、302 で送ります。お客様がこのサイトで入場していないときは、コード無しのポータルへ送ります。 |
portalRedirect は Promise<Response> を返します。options は fetch と timeoutMs で、待ち時間の既定は5000(5秒)、範囲は1から120000です。リンクの発行に失敗したときは 503 を返します。COZENI_API_ORIGIN で本番・サンドボックス以外の接続先を指定している場合、未入場のお客様を送るポータルのオリジンを決められないため、302 ではなく 401 を返します。
import { portalRedirect } from "@nulogic/cozeni-sdk/next";
export const dynamic = "force-dynamic";
// ボタンが押されたときに、購入者ポータルへのリンクを発行して 302 で送る
export function GET() {
return portalRedirect("cre_...");
}
ボタンは <a href="/portal">購入した商品</a> の形で置きます。
creatorId は npx cozeni whoami --json の data.creator_id です。秘密ではありません。ボタンは <a> で置き、<Link> は使わないでください。リンクは60秒で切れ、1回しか使えません。<Link> は表示時に先読みしてリンクを作るため、お客様が押す前にリンクが使い切られたり切れたりします。
機能フラグ
機能フラグの関数はサーバーの環境変数 COZENI_API_KEY を使います。COZENI_ENVIRONMENT で接続先を選びます。
| 関数 | 振る舞い |
|---|---|
createCheckout({ productId, email }) |
ログイン中のユーザーのメールアドレスで、機能フラグの購入画面を作ります。URL は本人にだけ渡し、30分で失効します。 |
getCustomerState({ email }) |
付いている機能フラグをすべて返します。 |
hasFeatureFlag({ email, productId }) |
特定の商品の機能フラグを確かめます。無ければ { granted: false, metadata: {} } を返します。 |
購入画面は Server Action か Route Handler で作り、お客様をそのまま購入画面へ送ります。
"use server";
import { createCheckout } from "@nulogic/cozeni-sdk/next";
import { redirect } from "next/navigation";
export async function upgrade() {
// getLoginUser はアプリのログインの処理に置き換える(メールアドレスは本人確認済みのもの)
const user = await getLoginUser();
const checkout = await createCheckout({ productId: "prd_...", email: user.email });
// checkout.expiresAt(作成から30分)を過ぎたら作り直す
redirect(checkout.url);
}
戻り値は { checkoutId, url, expiresAt } です。お客様がすでに購入済みのときは、CozeniError(code が already_purchased)を投げます。
機能の API では呼ばれるたびにサーバーで権利を確かめます。
import { hasFeatureFlag } from "@nulogic/cozeni-sdk/next";
export async function POST(request: Request) {
// getLoginUser はアプリのログインの処理に置き換える
const user = await getLoginUser(request);
const { granted, metadata } = await hasFeatureFlag({
email: user.email,
productId: "prd_...",
});
if (!granted) return Response.json({ error: "upgrade_required" }, { status: 403 });
// metadata は商品に設定した値。例:{ daily_messages: 500 }
// ここから先が機能の本体
}
付いている機能フラグをすべて取るときは、getCustomerState を使います。
import { getCustomerState } from "@nulogic/cozeni-sdk/next";
const state = await getCustomerState({ email: user.email });
// => { customerId: string | null, featureFlags: [{ productId, benefitId, grantedAt, metadata }] }
SDK の戻り値の名前は camelCase です(customerId、featureFlags)。API の応答(customer_id、feature_flags)とは書き方が違います。照会に失敗したとき(認証、レート制限、通信など)は、CozeniError を投げます。
キーの発行、結果のキャッシュ、購入直後の再照会については、購入者の状態 と 機能フラグ を見てください。
環境変数
| 変数 | 必要な場面 | 意味 |
|---|---|---|
COZENI_SITE_ORIGIN |
購入者限定ページ(ハンドオフ) | サイトのオリジンです。パスを含まない形で書きます。例:https://example.com |
COZENI_ENVIRONMENT |
サンドボックスのとき | production か sandbox です。省略すると本番です。 |
COZENI_API_KEY |
機能フラグを使うとき | API キーです。サーバーだけに置きます。 |
COZENI_API_ORIGIN |
Cozeni 自体をローカルで動かす開発用 | API のオリジンを直接指定します。通常は省略し、COZENI_ENVIRONMENT で環境を選びます。 |
環境変数から接続先を決めるとき、COZENI_API_ORIGIN と COZENI_ENVIRONMENT を両方指定する場合は、その環境の API オリジンと一致させてください。一致しなければ API に問い合わせず、権利の確認では unavailable、ハンドオフやポータルへの送り出しでは 503 を返します。機能フラグの関数は CozeniError(invalid_input)を投げます。
COZENI_API_KEY が空のとき、または NEXT_PUBLIC_COZENI_API_KEY が設定されているときは、機能フラグの関数は失敗します。NEXT_PUBLIC_ で始まる変数にはキーを入れないでください。