stigg-entitlements

Stigg のエンタイトルメント — 機能を制限し、使用量を報告する

このスキルでは、実行時の処理を扱います。リクエスト時のエンタイトルメントの確認、使用量の報告、Stigg に一時的に接続できない場合でもチェックの信頼性を保つ方法です。

始める前に

上位の stigg スキルに従い、まず検索してください。 SDK の初期化シグネチャやエンタイトルメントメソッド名は変更されるため、作成を始める前に、該当する SDK／REST のページ（Mintlify Stigg docs MCP）を開いてください。

最も重要な 2 つのルール

ルール 1 — 生イベントと計算済み使用量の違いは、誰が数えるかではなくスループットです

Stigg は 2 つの経路で使用量データを受け取ります。見た目は似ていますが、スケーリングの特性は異なります。

命名に関する注意： GraphQL ミューテーション／Node SDK メソッドは、reportEvent（生イベント）と reportUsage／reportUsageBulk（計算済み）です。直接 REST を呼び出す場合、同じ操作には POST /api/v1/events と POST /api/v1/usage を使用します。このスキルで使われる略称「events.report」／「usage.report」は、特定の SDK 名前空間ではなく、概念上の操作を指します。

経路	内容	スケーリングモデル	選択する場面
生イベント — reportEvent（Node SDK／GraphQL）／POST /api/v1/events	ディメンション付きの個別イベントをストリーミング送信します。Stigg がサーバー側でフィルタリングと集計を行います。	非同期、高スループット。 本番環境のボリュームを想定して設計されています。バッファリングと重複排除を行います。制限： 1 イベントあたり 1 MB、1 バッチあたり 1,000 イベント、ピーク時は毎秒 1,000 イベント。	本番環境の使用量報告では、これをデフォルトとして使用します。リクエストごとの加算、AI トークンの差し引き、大規模な課金対象イベントに適しています。
計算済み使用量 — reportUsage／reportUsageBulk（Node SDK／GraphQL）／POST /api/v1/usage	アプリでローカル集計し、差分または設定値を Stigg に送信します。	同期、計測型。 意図的にスループットを低くしています。reportUsageBulk は 1 回の呼び出しで最大 100 件の測定値を受け付けます。	まれな一括更新：「顧客のシート数は現在 5」（設定値）、または「シート数を 2 増やす」（差分）。バックフィル。定期的なインフラのポーリング。

よくある誤解： 「イベント」＝消費量に関するもの、「使用量」＝エンタイトルメントに関するもの、という考え方です。違います。 違いは運用上のものです。どちらの経路も、メータリングと課金に利用できます。データの内容ではなく、スループット／レイテンシの要件に応じて選択してください。

ルール 2 — 常にフォールバックを用意する

エンタイトルメントのチェックは、アプリのクリティカルパス上にあります。Stigg の SDK はローカルでキャッシュし、永続キャッシュにも対応しています。本番環境に移行する前に、キャッシュとフォールバックの両方を設定してください。 references/fallback.md を参照してください。

ゲーティング — 3 種類のエンタイトルメント

機能タイプ	メソッド（フロントエンド／バックエンド SDK）	戻り値
ブール値	getBooleanEntitlement({ featureId })	{ hasAccess, accessDeniedReason? }
設定値	getNumericEntitlement({ featureId })／getEnumEntitlement({ featureId })	設定された値
従量制	getMeteredEntitlement({ featureId, options: { requestedUsage } })	{ hasAccess, currentUsage, usageLimit, ... }

対象とする SDK のページで、実際のメソッド名を再確認してください。名前は変更されることがあります（例：バックエンド SDK では、統一された汎用チェックとして getEntitlement も公開されています）。

詳しいゲーティングのパターン — バックエンド／フロントエンドの初期化、リソースごとのゲーティング、レスポンスの形式、アンチパターンについては、references/gating.md を参照してください。

フロントエンド（ブラウザー）のゲーティング

import Stigg from '@stigg/js-client-sdk';

// initialize() is SYNCHRONOUS — it returns the client.
// To wait for the client to finish loading, await waitForInitialization().
const stiggClient = Stigg.initialize({
  apiKey: 'client-...',          // publishable key, not server key
  customerId: 'customer-123',
});
await stiggClient.waitForInitialization();

const ent = stiggClient.getMeteredEntitlement({
  featureId: 'api_calls',
  options: { requestedUsage: 1 },
});

if (ent.hasAccess) {
  // allow
} else {
  // show paywall / upgrade prompt
}

React では、<StiggProvider> でラップし、React SDK が公開するフックを使用してください。

バックエンドのゲーティング

import Stigg from '@stigg/node-server-sdk';

const stigg = await Stigg.initialize({ apiKey: process.env.STIGG_SERVER_API_KEY! });

const ent = await stigg.getMeteredEntitlement({
  customerId: 'customer-123',
  featureId: 'api_calls',
  options: { requestedUsage: 1 },
});

if (!ent.hasAccess) throw new HttpError(402, 'Upgrade required');

生 REST では、これに相当するのは GET /api/v1/customers/{id}/entitlements です。（GraphQL クエリは getEntitlementsState です。）クエリパラメーターについては、REST API リファレンスを参照してください。

使用量の報告 — 経路を選択する

イベントスキーマの全フィールドテーブル、ディメンション設計のガイダンス、クラウド取り込み経路（S3／Pub/Sub）、GraphQL と直接 REST の対応表については、references/usage-reporting.md を参照してください。

デフォルト — 生イベント（events.report / reportEvent）

// Backend Node SDK
await stigg.reportEvent({
  events: [{
    customerId: 'customer-123',
    eventName: 'api.request',
    idempotencyKey: 'req-abc-1234',          // required
    dimensions: { region: 'us-east-1', endpoint: '/search' },
    // timestamp is optional; server time is used if omitted
  }],
});

注意：

• idempotencyKey は必須です。 (timestamp, customerId, resourceId, eventName, idempotencyKey) が同一のイベントは重複排除されます。
• ディメンションは任意のキーと値を指定できます。 できるだけ事前に追加してください。バックフィルを行わずに、将来のフィルタリングや集計が可能になります。
• イベントごとの最大ペイロードサイズ：1 MB。
• プロダクトで複数のサブスクリプション（ワークスペース、プロジェクトなど）を許可する場合、resourceId は必須です。

セット／差分 — 計算済み使用量（usage.report / reportUsage）

import { UsageUpdateBehavior } from '@stigg/node-server-sdk';

// "Customer now has 5 seats" — Set behavior
await stigg.reportUsage({
  customerId: 'customer-123',
  featureId: 'seats',
  value: 5,
  updateBehavior: UsageUpdateBehavior.SET,
});

// "+2 seats" — Delta behavior (default)
await stigg.reportUsage({
  customerId: 'customer-123',
  featureId: 'seats',
  value: 2,
  // updateBehavior defaults to DELTA
});

アプリが正確な値（シート数、設定済みクォータなど）を保持していて、Stigg にイベントごとの集計をさせたくない場合に使用してください。

一括処理版（reportUsageBulk）は、呼び出しあたり最大 100 件の測定値に対応しています。レート制限にご注意ください。

キャッシュとフォールバック — 本番環境では必須

Stigg SDK は有効なエンタイトルメントをローカルにキャッシュするため、リクエストごとにネットワークを往復して確認する必要がありません。本番環境に移行する前に、キャッシュとフォールバックの両方を設定してください。

• ローカルのインメモリキャッシュ — すべての SDK でデフォルトです。ポーリング（フロントエンド）またはリアルタイム更新（バックエンド）によって更新されます。
• 永続キャッシュ — プロセスとともにインメモリキャッシュが消失するサーバーレス環境や大規模なフリート向けです。persistent-cache-service を介して Redis に保存されます。Node SDK と Sidecar でサポートされています。
• Sidecar — API の前段に配置する、独立したプロセスまたはデプロイメントです。低レイテンシー、オフラインモード、グローバルフォールバックを提供します。
• フォールバックルール — グローバルおよびエンタイトルメントごとに設定できます。エンタイトルメントのデータがない場合、または Stigg に接続できない場合、SDK は設定済みのフォールバック（許可／拒否）を返します。ログに記録できるよう、マーカーも付与されます。
• 障害発生中の使用状況 — エンタイトルメントの確認はキャッシュを使って引き続き動作します。使用状況のレポートはインメモリ（または永続キャッシュ）にバッファーされ、再接続時に送信されます。

詳しいガイダンス：references/fallback.md。

プロモーションエンタイトルメント

顧客ごとのエンタイトルメントのオーバーライドです。サブスクリプションに属さず、顧客に直接付与します。顧客ごとのランタイム上の処理であり、カタログのモデリングではないため、このスキルが付与、取り消し、読み取りまでを一貫して担当します。

• ユースケース： 一時的な上限の引き上げ（「スクリプトが API クォータを使い切ってしまいました。期間終了まで追加で 1k をお使いください」）、特定の顧客へのプレミアム機能の先行提供、エンタープライズ向けの個別対応、好意による特別措置。
• プランやアドオンのエンタイトルメントに加算されます（寛大なエンタイトルメントのルールが適用されます）。
• 期間を限定（1 か月／1 年／無期限）するか、手動で取り消すまで有効にできます。
• 付与はミューテーションです。grantPromotionalEntitlements（GraphQL）、同等の SDK メソッド、または MCP で利用できます。customerId、featureId、オーバーライド値、期間を渡してください。
• 取り消しには revokePromotionalEntitlement を使用します。

モデリング対象（存在する機能）は stigg-pricing-modeling で定義します。プロモーションエンタイトルメントは、特定の顧客について、それらの機能の設定をオーバーライドするだけです。

このスキルを使用しない場合

• 機能／プラン／アドオンのモデリング → stigg-pricing-modeling。
• サブスクリプションのプロビジョニング／キャンセル／移行 → stigg-subscriptions。
• ランタイムでのクレジット残高の付与 → stigg-credits。
• 顧客のプロダクトに適した料金モデルの選定 → stigg-pricing-expert。

よくある間違い

間違い	修正方法
「標準的に聞こえる」から usage.report を選ぶ	分割の基準はスループットです。本番環境で大量に処理する場合は、デフォルトで events.report を使用してください。
イベントで idempotencyKey を省略する	必須です。指定しないと、拒否されたり、重複してカウントされたりします。
ブラウザーから使用状況を報告する	使用状況の報告はバックエンド側で行います。パブリッシュ可能キーは読み取り専用です。
キャッシュを任意のものとして扱う	本番環境では、キャッシュとフォールバックの両方が契約の一部です。どちらも設定してください。
フォールバックルールを定義しない	Stigg に一時的に接続できず、キャッシュも空の場合、SDK は返す値がありません。妥当なデフォルト（通常はログを記録して許可）を選んでください。
API リクエストごとに Stigg を同期的に呼び出す	SDK はすでにキャッシュを行います。SDK に任せてください。アプリ側で二重にキャッシュしないでください。
ホットパスで events.report を呼び出すたびに await する	バッファリング／バッチ処理を行い、非同期でフラッシュしてください。イベント経路はそのために設計されています。
設定値で済むのに、生のイベントを使う	設定機能（数値型／列挙型）はモデル化がより簡単で、イベントの取り込みも不要です。