Raypx

@raypx/billing 定义了免费版和专业版的套餐限额，提供用量检查函数，用于在 RPC 层和中间件中实施配额控制。

计划层级

层级	说明
`free`	免费版
`pro`	专业版

import type { PlanTier } from "@raypx/billing"

type PlanTier = "free" | "pro"

限额定义

限额项	免费版	专业版
每月 AI Token 数	25,000	250,000
每月 AI 请求次数	100	2,000
最大文档数量	25	2,000
单文件最大大小	2 MB	25 MB

PlanLimits 类型

interface PlanLimits {
  monthlyAiTokens: number    // 每月 AI Token 配额
  monthlyAiRequests: number  // 每月 AI 请求配额
  maxDocuments: number       // 最大文档数
  maxFileSizeBytes: number   // 单文件最大字节数
}

核心函数

getPlanLimits()

获取指定计划的限额配置。

import { getPlanLimits } from "@raypx/billing"

const limits = getPlanLimits("free")
// { monthlyAiTokens: 25000, monthlyAiRequests: 100, maxDocuments: 25, maxFileSizeBytes: 2097152 }

resolvePlanTier()

安全地将字符串解析为计划层级，无效值默认返回 "free"。

import { resolvePlanTier } from "@raypx/billing"

resolvePlanTier("pro")    // "pro"
resolvePlanTier("free")   // "free"
resolvePlanTier("invalid") // "free"
resolvePlanTier(null)     // "free"

getDefaultUsageSnapshot()

获取初始化的用量快照，所有计数器归零。

import { getDefaultUsageSnapshot } from "@raypx/billing"

const snapshot = getDefaultUsageSnapshot()
// { aiTokens: 0, aiRequests: 0, documents: 0 }

canUseAi()

检查用户是否可以在当前用量下使用 AI 功能。

import { canUseAi } from "@raypx/billing"

const result = canUseAi(
  { aiTokens: 24000, aiRequests: 99, documents: 5 },
  "free",
  500, // 请求使用的 Token 数
)

if (!result.allowed) {
  // result.reason: "monthly_ai_tokens" | "monthly_ai_requests"
}

检查顺序：

请求次数是否超出月度限额
Token 总量是否超出月度限额

canUploadDocument()

检查用户是否可以上传新文档。

import { canUploadDocument } from "@raypx/billing"

const result = canUploadDocument(
  { aiTokens: 1000, aiRequests: 10, documents: 24 },
  "free",
  1024 * 1024, // 文件大小 1MB
)

if (!result.allowed) {
  // result.reason: "max_documents" | "max_file_size"
}

检查顺序：

文档数量是否超出上限
单文件大小是否超出上限

UsageAllowanceResult

所有用量检查函数返回统一的结果类型：

interface UsageAllowanceResult {
  allowed: boolean
  reason?: "monthly_ai_tokens" | "monthly_ai_requests" | "max_documents" | "max_file_size"
}

在 RPC 中的使用

通常在 protectedProcedure 的中间件或 handler 中调用用量检查：

import { canUseAi } from "@raypx/billing"

const chatHandler = protectedProcedure.handler(async ({ context, input }) => {
  const result = canUseAi(userSnapshot, user.plan, estimatedTokens)
  if (!result.allowed) {
    throw new Error(`Usage limit exceeded: ${result.reason}`)
  }
  // ... 执行 AI 请求
})

类型导出

import type {
  PlanTier,
  PlanLimits,
  UsageSnapshot,
  UsageAllowanceResult,
} from "@raypx/billing"

@raypx/billing

On this page