---
title: JavaScript / TypeScript
description: フレームワークを問わずサーバーで使う SDK。
---

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

## インストール

```package-install
npm i @nulogic/cozeni-sdk@0.8.0
```

:::tip
[CLI](/integrate/cli) の `init` を使うと、SDK を依存に入れることと、AI エージェント向けの手順書を置くことを一度にできます。
:::

## 最小のコード例

お客様が商品を持っているかを確かめる例です。Web 標準の `Request` と `Response` を使います。

:::caution
この例は権利を確かめる部分だけです。お客様が入場画面から戻ってきたときの、`cozeni_code` の交換と Cookie の設定（[購入者のクライアント](#購入者のクライアント) の `exchangeHandoff`）が別に要ります。交換をしないと Cookie ができず、お客様は入場画面へ送り返され続けます。両方を含む [完成例](https://github.com/nulogic-jp/cozeni-sdk/blob/main/examples/javascript-server/web-handler.mjs) を見てください。Next.js では `cozeniProxy` が交換します。
:::

```ts
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"` を渡します。

```ts
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 リファレンス](/api-reference) の応答と同じです。

`products.create` と `products.update` の `description` は商品の説明（Markdown）です。前後の空白を除いて4000コードポイントまで指定できます。

商品を作って購入リンクを受け取る例です。

```ts
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` を渡します。

機能フラグの関数の詳しい使い方は [購入者の状態](/integrate/customer-state) を見てください。

### 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` はキーやお客様のコード、応答の本文を保持しません。詳しいエラーの一覧は [エラー](/api-reference/errors) と [レート制限](/api-reference/rate-limits) を見てください。

## 次に読むページ

**[Next.js](/integrate/sdk/nextjs)**

Next.js（App Router）で使うヘルパーを説明します。

**[購入者の状態](/integrate/customer-state)**

機能フラグの照会と、結果のキャッシュの仕方を説明します。

**[サンドボックス](/integrate/sandbox)**

テスト購入と、本番への切り替えを説明します。

**[CLI の概要](/integrate/cli)**

商品の作成と購入リンクの取得を、コードを書かずに行います。
