stigg-entitlements

Stigg 权益——启用功能并报告用量

本技能涵盖运行时方面：在请求时检查权益、报告用量，以及在 Stigg 短暂无法访问时确保检查可靠。

开始之前

根据总览 stigg 技能：先搜索。 SDK 初始化签名和权益方法名称会不断变化——编写之前，请先打开相关的 SDK / REST 页面（Mintlify Stigg 文档 MCP）。

两条最重要的规则

规则 1——原始事件与计算用量的区别取决于吞吐量，而不是由谁计数

Stigg 通过两种途径接收用量数据。它们看起来相似，但扩展特性不同。

命名说明： GraphQL mutation / 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 MB；每批 1,000 个事件；峰值每秒 1,000 个事件。	生产环境报告用量时的默认选择。适用于按请求递增、AI 令牌扣减以及大规模计费事件。
计算用量——reportUsage / reportUsageBulk（Node SDK / GraphQL）/ POST /api/v1/usage	你的应用在本地聚合数据，然后将增量或设定值推送到 Stigg。	**同步，偏测量型。**吞吐量有意设置得较低。reportUsageBulk 每次调用最多接受 100 项测量数据。	少量、批量更新：“客户现在有 5 个席位”（设定值），或“增加 2 个席位”（增量）。回填数据。定期轮询基础设施。

常见误解：“events”指消耗类数据，“usage”指权益类数据。**并非如此。**两者的区别在于操作方式。这两种途径都可以驱动计量和计费。应根据吞吐量 / 延迟预算来选择，而不是根据数据代表的内容来选择。

规则 2——始终准备回退方案

权益检查位于应用的关键路径上。Stigg 的 SDK 会在本地缓存，并支持持久化缓存；**投入生产之前，请同时配置缓存和回退方案。**参阅 references/fallback.md。

权益门控——三种权益形态

功能类型	方法（前端 / 后端 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 提供的 Hooks。

后端门控

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 已经会缓存，让它处理即可。不要在应用中重复缓存。
在关键路径中对 events.report 逐次调用 await	缓冲／批量处理并异步刷新。事件路径就是为此设计的。
配置值足以满足需求时仍使用原始事件	配置功能（数值／枚举）更易于建模，也不需要摄取事件。