autumn-add-usage-tracking

Autumn 用量跟踪

请始终查阅 docs.useautumn.com，获取代码示例和最新 API。

Autumn 会跟踪功能用量并强制执行限制。出于安全考虑，必须在后端进行检查。

---

快速参考

核心模式

check → work → track

检查响应

字段	说明
allowed	客户能否继续操作
balance	剩余单位数
included_usage	计划中包含的总用量
unlimited	不强制执行限制

功能类型

类型	行为
boolean	授予或拒绝访问
metered	根据限制跟踪用量
credit_system	多个功能共用的额度池

---

安全模型

层	用途	信任级别
前端	用户体验（显示/隐藏界面）	不可信
后端	强制执行限制	必需

---

后端实现

import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY });

// 1. Check
const { data } = await autumn.check({ customer_id, feature_id: "api_calls" });
if (!data.allowed) return { error: "Limit reached" };

// 2. Work
const result = await doWork();

// 3. Track
await autumn.track({ customer_id, feature_id: "api_calls", value: 1 });
return result;

from autumn import Autumn

autumn = Autumn('am_sk_test_xxx')

response = await autumn.check(customer_id="user_123", feature_id="api_calls")
if not response.allowed:
    raise HTTPException(403, "Limit reached")

result = await do_work()
await autumn.track(customer_id="user_123", feature_id="api_calls", value=1)

---

React 实现

import { useCustomer } from "autumn-js/react";

const { check, refetch } = useCustomer();

const handleAction = async () => {
  const { data } = await check({ featureId: "messages" });
  if (!data?.allowed) {
    showUpgradePrompt();
    return;
  }
  
  await performAction();
  await refetch();
};

---

显示用量

const { customer } = useCustomer();
const feature = customer?.features?.api_calls;

<p>{feature?.balance} / {feature?.included_usage}</p>

---

额度系统

跟踪底层的计量功能，而不是额度系统：

// Config: credits → api_calls (1), image_gen (10)

// Wrong
await autumn.track({ customer_id, feature_id: "credits", value: 10 });

// Right - Autumn deducts 10 credits automatically
await autumn.track({ customer_id, feature_id: "image_gen", value: 1 });

---

常见注意事项

1. 成功后再跟踪 - 仅在工作成功完成后跟踪
2. 必须在后端进行 - 前端检查可以被绕过
3. 额度系统 - 跟踪计量功能，而不是额度池
4. 幂等性 - 使用 idempotency_key 防止重复计数
5. 批量跟踪 - 批量操作时传入更大的 value

---

资源

• 检查文档
• 跟踪文档
• 额度系统
• LLMs.txt