@hanzo/plans

中文文档
1.10.3发布于 2026/11/15Apache-2.0TypeScriptES Module近 30 天下载 7756

Canonical Hanzo plan and pricing definitions — single source of truth

原始使用文档
文档目录13 节
  1. Install
  2. Usage
  3. Entitlements — the canonical vocabulary (keystone)
  4. tenant_id — multi-tenant catalogs
  5. The data contract: entitlements → price_ref → license featu…
  6. Schema
  7. Subscription plans ( subscription.json )
  8. The ladder
  9. Usage tiers ( usage )
  10. Bundles
  11. Agent runtime ( seats.json )
  12. Contributing
  13. License

plans

@hanzo/plans

Canonical plan + pricing definitions for the Hanzo platform. Single source of truth, consumed by every product surface that renders a price tag or gates a feature.

Install

npm install @hanzo/plans

Usage

import {
  subscriptionPlans, // free / go / pro-3x / dev-5x / max-15x / ultra / ultimate / unlimited / team / enterprise
  dnsPlans,          // dns-free / dns-pro / dns-enterprise
  cloudPlans,        // starter / builder / dev / pro / turbo / ...
  blockchainPlans,
  gpuTiers,
  regions,
  seats,
  storage,
  tools,
  pricingPolicy,
} from '@hanzo/plans'

console.log(subscriptionPlans.find((p) => p.id === 'max-15x'))
// → { id: 'max-15x', replaces: ['max-10x'], name: 'Max', priceMonthly: 95, priceAnnual: null, ... }

Or import a single JSON file:

import subscription from '@hanzo/plans/subscription.json'
import dns from '@hanzo/plans/dns.json'

Entitlements — the canonical vocabulary (keystone)

Entitlements used to be defined three times: plan features were display strings, plan limits were ad-hoc machine keys, commerce duplicated them, and licensing needed its own machine keys for the engine. This package now defines the one machine-readable entitlement vocabulary, here, once.

  • entitlements.schema.json — JSON-Schema (draft 2020-12) of the namespaced vocabulary. Every key is namespace.key with a fixed type + x-unit, across nine namespaces: ai.*, cloud.*, licensing.*, world.*, dns.*, rpc.*, data.*, tools.*, commerce.*. Headline keys: ai.models, ai.agents, cloud.max_vms, cloud.gpu_class, licensing.app_ids, licensing.seats. A numeric -1 means unlimited; null means unset/inherit.
  • plan.schema.json — the plan envelope. Adds tenant_id (so each reseller/org has its own catalog), the typed entitlements block, and the price_ref block. Display features and legacy limits remain optional.
  • entitlements.mjs — runtime helpers (ENTITLEMENT_KEYS, fromLegacy, toPriceRefStub, toLicenseFeatures, resolvePlan).

tenant_id — multi-tenant catalogs

Plan ids are no longer globally unique. The unique key is the pair (tenant_id, id). tenant_id defaults to "hanzo" (the first-party catalog) when omitted, so every existing record stays valid. A reseller ships its own plan rows under its own tenant_id without colliding with hanzo's pro/max/etc.

The data contract: entitlements → price_ref → license features

plan.entitlements          (machine keys; the source of truth)
   │  fromLegacy(plan)      ← derives entitlements from legacy limits/addons/payouts
   ▼
price_ref                  (pricing.hanzo.ai)
   ├─ recurring             flat subscription line (monthly/annual, per_seat)
   └─ metered[]             usage meters: { entitlement, unit, source, included }
                            resolved live vs OpenRouter / HF / Zen gateway / DO
   │  toLicenseFeatures(entitlements)
   ▼
license token `features`   (hanzoai/licensing → the proprietary engine)
                            flat []string the engine's release gate matches
                            (releases.go hasFeatures): "inference", "training",
                            "ai.premium", "licensing.app:hanzo",
                            "licensing.product:engine", "deploy.on_prem", …
  • commerce reads entitlements to populate its Entitlement (members, SSO, product ids, seats) instead of re-deriving from display strings.
  • licensing copies licensing.engine_features plus the derived capability tokens into the signed token features; the engine verifies them offline.
  • Quantitative quotas (tokens/min, seats, VMs) ride the token as structured limits, not as feature strings, keeping the engine's string-set check meaningful.
import { resolvePlan, ENTITLEMENT_KEYS, fromLegacy, toLicenseFeatures } from '@hanzo/plans'

const max = subscriptionPlans.find((p) => p.id === 'max-5x')
resolvePlan(max)
// → { tenant_id: 'hanzo', id: 'max-5x', entitlements: {...}, price_ref: {...},
//     license_features: ['ai.premium','training','licensing.app:hanzo', ...] }

Schema

Subscription plans (subscription.json)

type Plan = {
  tenant_id?: string          // owning reseller/org; defaults to 'hanzo'.
                              // unique key is (tenant_id, id)
  id: string                  // 'pro', 'world-pro', 'team-max', ... (unique per tenant)
  name: string
  description: string
  priceMonthly: number | null // legacy convenience price; authoritative is price_ref
  priceAnnual: number | null  // USD per month billed annually
  category: 'personal' | 'team' | 'enterprise' | 'world'
  group?: string              // the team a per-seat plan is a seat type of ('team');
                              // one subscription holds seats of every plan in it, and
                              // minSeats / maxMembers count them together
  popular?: boolean
  contactSales?: boolean
  features: string[]          // DISPLAY strings — do not gate on these
  usage?:                     // DISPLAY usage tier, on every listed personal paid rung only
    | { multiple: number; session: number; day: number; premiumCents: number; oursCents: number }
    | { multiple: null; unlimited: true }
  limits?: {                  // DEPRECATED: back-compat source for `entitlements`
    agents?: number
    bots?: number
    teamGuests?: number
    minSeats?: number
    freeCredit?: number
    maxMembers?: number
    maxAlerts?: number
    apiRateLimit?: number
    mcpRateLimit?: number
  }
  entitlements?: Entitlements // CANONICAL machine truth (see entitlements.schema.json)
  price_ref?: PriceRef        // billing binding: { currency, recurring, metered[] }
  bundles?: string[]    // slugs of plans this plan also grants free
  includedIn?: string[] // slugs of parent plans that bundle this one
  payouts?: { idleResalePercent: number; description: string }
}

The ladder

idnamemonthyearAI included
freeFree$0—Enso Auto, 50 free requests a day
goGo$8—usage on every model
pro-3xPro$15—3x Go's
dev-5xDev$45—5x Go's
max-15xMax$95—15x Go's
ultraUltra$195—25x Go's
ultimateUltimate$495—50x Go's
unlimitedUnlimited$995—no caps
teamTeam (standard seat)$25 / member$240 / memberPro's usage, per member
team-premiumTeam Premium (premium seat)$100 / member$960 / member5x a standard seat's, per member
advisoryAdvisory (agency)$4,999—10x Pro's
dedicatedDedicated Team (agency)$9,999—10x Pro's
enterpriseEnterprisequotedquotedby contract

Usage tiers (usage)

The figures behind a plan's usage — per model class, per session and day, per model — are cloud's usage policy (hanzo-inc/cloud apps/flags PlanSeeds and apps/allowance), set by a SuperAdmin at admin.hanzo.ai, read by customers at /v1/ai/limits, and enforced there. Every listed personal paid rung restates them for display in a top-level usage block, so a UI can render the tiers in order: Go's basis (50 requests a 5-hour session, 150 a day, 500 cents of each model class) times the rung's multiple. Unlimited states no figure.

idusage
go{"multiple": 1, "session": 50, "day": 150, "premiumCents": 500, "oursCents": 500}
pro-3x{"multiple": 3, "session": 150, "day": 450, "premiumCents": 1500, "oursCents": 1500}
dev-5x{"multiple": 5, "session": 250, "day": 750, "premiumCents": 2500, "oursCents": 2500}
max-15x{"multiple": 15, "session": 750, "day": 2250, "premiumCents": 7500, "oursCents": 7500}
ultra{"multiple": 25, "session": 1250, "day": 3750, "premiumCents": 12500, "oursCents": 12500}
ultimate{"multiple": 50, "session": 2500, "day": 7500, "premiumCents": 25000, "oursCents": 25000}
unlimited{"multiple": null, "unlimited": true}

Nothing reads usage to gate or bill: cloud's policy is what a subscriber gets. No other place in a record states a figure — no requestsPer*/tokensPerMinute limit and no ai.* allowance entitlement — and test/usage.test.mjs fails a plan that does, or a usage block off the basis, out of order, or disagreeing with the rung's copy. The copy names exactly two figures from that policy, in plain words: a rung's multiple of Go, in its usage and in its 5-hour and daily windows ("25x more usage than Go"), a premium team seat's 5x a standard seat, and Free's 50 free requests a day. Every other number in a ladder line is a price, a seat range or a capacity the plan's own fields state; test/copy.test.mjs holds each to its source and refuses a usage dollar amount, a token count, a vendor name or an internal word. A rung goes on sale only with cloud figures behind its multiple.

Past what a plan includes, a holder keeps going on prepaid credit they bought; no rung mints credit. The personal ladder is sold by the month only; a standard team seat's year is $240, $20 a month per member, and a premium seat's $960, $80 a month.

A team mixes seat types: team and team-premium name the group team, so one subscription holds standard and premium seats together and the team is counted across both — from 2 members in all (one of each is a team; one alone is not) to 100.

The agency retainers are hanzo.agency's, sold by card on pay.hanzo.ai: category agency keeps them off the app's ladder and org gate, they bill monthly with no annual price (Advisory's quarter minimum is a contract term, not a field), and they carry 10x Pro's AI usage (cloud's agency rows) because the retainer pays for people.

Pro is pro-3x because pro names a compute size in plans.json. pro-3x declares "replaces": ["pro-2x"] and max-15x "replaces": ["max-10x"]: every reader that resolves a stored id (findPlan, the goja routes, commerce, cloud's usage policy) serves the old slug's holder as the renamed rung, and the subscription keeps the price it was bought at. The rungs commerce retired (dev, max-5x, max-20x, max-50x) stay in the catalog with "status": "archived", so their holders resolve to what they bought; max ($99) still answers as max-5x. A status other than active keeps a plan off every list and checkout (listedPlans). No plan is "private" today: Unlimited is listed and sold like every other rung. ultimate is a new rung and replaces nothing, so max-50x stays archived and resolves as itself.

Bundles

Several Hanzo platform tiers grant free access to a Hanzo World tier without a second charge:

Platform planBundles
max-5x / max-20xworld-pro
team / enterpriseworld-team

A subscription created against a parent plan should mint zero-priced child subscriptions for every entry in bundles. Hanzo Commerce does this automatically in its CreateBillingSubscription handler.

Agent runtime (seats.json)

Agent compute is billed by the hour, not by the seat:

Rate
runtime.agentHourUSD$0.08 / hour

One rate covers all agent runtime — agentic coding, chat inference sessions, and a bot running resident. Hours are metered on top of the subscription.

What a tier includes is a capacity, on the tier: limits.agents and limits.bots (canonically ai.agents / ai.bots). Free may run 1 agent, dev 10, every Max rung 10 plus its own bots (1, 3, 5 and 10 up the rungs), enterprise unlimited (-1). Those cap how many may exist; they are not an allowance of hours, so a consumer needs both halves and must not read one as the other.

0 means the tier may run none of that kind and is a real, enforceable answer; a missing key means nobody has said yet, and must not be read as zero.

Contributing

hanzoai/plans is the only canonical source. Every consumer (commerce, pricing, console, cloud, hanzo.ai marketing) reads this package — never their own copy. PRs against this repo cascade out via npm publish + downstream image rebuilds.

License

Apache 2.0 — see LICENSE. The data itself is customer-facing pricing; the licence covers the JavaScript bindings.

版本与发布记录

@hanzo/plans 共发布 47 个版本,首次发布于 2026/06/08;过去 12 个月发布了 47 个版本。

版本发布日期距今
1.10.3latest2026/11/152 天前
1.10.22026/11/152 天前
1.10.12026/11/134 天前
1.10.02026/11/107 天前
1.9.12026/11/089 天前
1.9.02026/10/2325 天前

关于 @hanzo/plans 的常见问题

@hanzo/plans 是什么?

Canonical Hanzo plan and pricing definitions — single source of truth

如何安装 @hanzo/plans?

在项目目录运行 npm install @hanzo/plans,或使用 pnpm add / yarn add / bun add。

@hanzo/plans 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hanzo/plans 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hanzo/plans 可以商用吗?

@hanzo/plans 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hanzo/plans 的下载量有多少?

根据 npm 官方下载统计,@hanzo/plans 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,756 次,日均约 259 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hanzo/plans 还在维护吗?

最新版本 1.10.3 发布于 2026/11/15(2 天前);至今共发布 47 个版本,其中过去 12 个月发布了 47 个;首次发布于 2026/06/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。