@molecule/api-entitlements 1.0.0

package/dist/index.js

@@ -0,0 +1,101 @@
+/**
+ * Tier-based entitlements core for molecule.dev.
+ *
+ * Provides the typed `Tier<TLimits>` / `TierRegistry<TLimits>` shapes, a
+ * per-process plan-key cache, and Express middleware factories that gate
+ * endpoints by tier category or quantitative limit.
+ *
+ * Apps declare their own `TLimits` shape, construct a registry via
+ * `defineTiers(...)`, and bond it via `setProvider(...)` at startup. The
+ * webhook glue that maps Stripe / Apple / Google subscription events to
+ * `users.planKey` already lives in `@molecule/api-resource-user`.
+ *
+ * @example
+ * ```typescript
+ * import { defineTiers, setProvider, enforceLimit, requireCategoryAtLeast } from '@molecule/api-entitlements'
+ * import { count } from '@molecule/api-database'
+ *
+ * interface BlogLimits {
+ *   maxPosts: number
+ *   maxCommentsPerDay: number
+ * }
+ *
+ * const registry = defineTiers<BlogLimits>({
+ *   tiers: {
+ *     free: { planKey: 'free', category: 'free', name: 'Free', limits: { maxPosts: 5, maxCommentsPerDay: 50 } },
+ *     stripeMonthly: { planKey: 'stripeMonthly', category: 'pro', name: 'Pro', limits: { maxPosts: 100, maxCommentsPerDay: 1000 } },
+ *   },
+ *   defaultPlanKey: 'free',
+ *   categoryOrder: ['free', 'pro'],
+ * })
+ *
+ * setProvider(registry)
+ *
+ * // Gate the API routes — the SERVER enforces tiers, never the UI alone:
+ * router.post('/posts',
+ *   enforceLimit<BlogLimits>({
+ *     limitType: 'maxPosts',
+ *     getLimit: (limits) => limits.maxPosts,
+ *     getCurrent: (userId) => count('posts', [{ field: 'userId', operator: '=', value: userId }]),
+ *   }),
+ *   handlers.createPost,
+ * )
+ * router.get('/analytics', requireCategoryAtLeast('pro'), handlers.analytics)
+ * ```
+ *
+ * @remarks
+ * - **Enforcement is middleware on the API route** (`requireCategory`,
+ *   `requireCategoryAtLeast`, `enforceLimit`) — hiding a button in the UI is
+ *   not entitlement enforcement. The middleware reads the authenticated user
+ *   from `res.locals.session.userId`, so it must be registered AFTER the auth
+ *   middleware; unauthenticated requests get a 401.
+ * - **`enforceLimit` blocks at `current >= limit`** and responds with a
+ *   structured `LimitErrorPayload` (default 403; pass `status: 429` for
+ *   usage-style limits) that the app's limit/upgrade notice renders — don't
+ *   swallow it into a generic error page.
+ * - **It is a SOFT ceiling — `getCurrent` COUNTS, then the handler CREATES the
+ *   resource afterwards.** Under concurrency N requests can all read the same
+ *   `current < limit` and all create, so the limit can be exceeded by a few.
+ *   That is fine for plan limits (max projects / seats / collaborators — a
+ *   bounded, harmless overshoot). It is NOT enough for a HARD limit where going
+ *   over is a real loss: money / wallet balances, physical inventory (stock,
+ *   tickets, seats), or metered credits. Enforce THOSE atomically at the write
+ *   with a conditional `UPDATE ... WHERE remaining >= $n RETURNING` that affects
+ *   0 rows when it wouldn't fit (or an advisory-lock reserve for a ledger SUM) —
+ *   never a count-then-allow middleware.
+ * - **Plan keys are cached per process** (default 5-minute TTL). The
+ *   resource-user payment webhook glue invalidates on plan change; any custom
+ *   path that mutates a user's `planKey` must call
+ *   `invalidateCachedPlanKey(userId)` or the old tier lingers until TTL.
+ * - Unknown, expired, or missing plan keys resolve to the `defaultPlanKey`
+ *   tier — make the default tier's limits the safe floor.
+ * - The middleware factories are connect/Express-shaped conveniences. Other
+ *   stacks (queues, websockets, non-Express frameworks) enforce the same tiers
+ *   directly via `getProvider()` + `getCachedPlanKey(userId)`.
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] The pricing/plans surface lists every tier with its name, price, and limits
+ *   (rendered from `/api/billing/tiers`, not hardcoded).
+ * - [ ] A free-tier user who hits a quantitative limit (e.g. creates the max
+ *   allowed items, then one more) gets a visible limit/upgrade notice — never a
+ *   silent failure, a blank page, or a raw 500.
+ * - [ ] The blocked action really is blocked server-side: after a full page reload
+ *   the over-limit item was NOT created.
+ * - [ ] A higher-tier user (seed or upgrade one) can perform the same action that
+ *   was blocked on the free tier.
+ * - [ ] Tier-gated features/sections are hidden or clearly locked for tiers that
+ *   lack them, and usable for tiers that have them.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './cache.js';
+export * from './error.js';
+export * from './middleware.js';
+export * from './provider.js';
+export * from './registry.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/middleware.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Express middleware factories for tier-based entitlements.
+ *
+ * `requireCategory` and `requireCategoryAtLeast` gate endpoints by the user's
+ * tier category. `enforceLimit` checks a quantitative limit before allowing
+ * the request to proceed (e.g. "max 10 projects per user").
+ *
+ * Tier-aware windowed rate limiting (e.g. "60 requests per minute on free,
+ * 300 on pro") is intentionally not handled here — wire one
+ * `@molecule/api-rate-limit` middleware per tier and dispatch on category,
+ * or use the bonded rate-limit provider directly.
+ *
+ * @module
+ */
+import type { LimitType, Tier } from './types.js';
+/**
+ * Minimal request shape consumed by the entitlements middleware. The
+ * structural type lets Express's full `Request` flow in transparently
+ * (Express types are assignable to this) without forcing this package to
+ * take a hard dependency on `express`.
+ *
+ * The middleware never reads off `req` directly; auth context lives on
+ * `res.locals.session.userId` and is read via the response object instead.
+ * The optional `_skipReason` field exists purely so this is not an empty
+ * interface (which ESLint's `@typescript-eslint/no-empty-interface` flags).
+ */
+interface Request {
+    /** Reserved — not consumed by the middleware. */
+    readonly _skipReason?: never;
+}
+/** Minimal response shape — Express's `Response` is assignable to this. */
+interface Response {
+    status(code: number): Response;
+    json(body: unknown): Response;
+    set(field: string, value: string): Response;
+    locals: {
+        session?: {
+            userId?: string;
+        };
+    } & Record<string, unknown>;
+}
+/** Express-compatible next function. */
+type NextFunction = (err?: unknown) => void;
+/** Express-compatible request handler. */
+export type RequestHandler = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+/**
+ * Resolves the effective tier for the user attached to the request via
+ * `res.locals.session.userId`. Falls back to the registry's default tier
+ * when no user is on the request, when the user record cannot be found, or
+ * when the stored plan has expired.
+ *
+ * @param res - The response object whose `locals.session.userId` identifies the user.
+ * @returns The user's effective tier.
+ */
+export declare const getEffectiveTier: <TLimits = unknown>(res: Response) => Promise<Tier<TLimits>>;
+/**
+ * Creates middleware that allows the request only when the user's tier
+ * category is one of the listed values. Responds 401 if the request is
+ * unauthenticated, 403 with a `LimitErrorPayload`-shaped body if the user's
+ * tier is not in the list.
+ *
+ * @param allowedCategories - The tier categories that are permitted (e.g. `['pro', 'team']`).
+ * @returns An Express request handler.
+ */
+export declare const requireCategory: <TLimits = unknown>(...allowedCategories: string[]) => RequestHandler;
+/**
+ * Creates middleware that allows the request only when the user's tier
+ * rank is at least as high as the named category. Useful for "pro and above"
+ * style gates without listing every category individually.
+ *
+ * Apps must include all gated categories in `categoryOrder` when calling
+ * `defineTiers(...)`; categories absent from the order produce `null` ranks
+ * and therefore fail the check.
+ *
+ * @param minCategory - The minimum acceptable category.
+ * @returns An Express request handler.
+ */
+export declare const requireCategoryAtLeast: <TLimits = unknown>(minCategory: string) => RequestHandler;
+/** Options for the `enforceLimit` middleware. */
+export interface EnforceLimitOptions<TLimits = unknown> {
+    /** Stable identifier for the limit (used in error payloads, telemetry). */
+    limitType: LimitType;
+    /**
+     * Pulls the numeric cap out of the user's tier `limits` object.
+     *
+     * @param limits - The tier-specific limits.
+     * @returns The numeric cap to enforce.
+     */
+    getLimit: (limits: TLimits) => number;
+    /**
+     * Computes the user's current usage. Receives the userId resolved from the
+     * session and the request object so apps can scope by additional fields
+     * (e.g. organization, project) when needed.
+     *
+     * @param userId - The authenticated user ID.
+     * @param req - The incoming request, in case scoping needs query/body data.
+     * @returns The current usage count.
+     */
+    getCurrent: (userId: string, req: Request) => Promise<number> | number;
+    /**
+     * Optional override for the response status. Defaults to 403; some apps
+     * prefer 429 for usage-style limits.
+     */
+    status?: number;
+}
+/**
+ * Creates middleware that allows the request only when the user is below
+ * their tier limit for the given resource. The user's tier `limits` object
+ * supplies the cap, and the caller-supplied `getCurrent` function counts
+ * the current usage.
+ *
+ * @param options - The limit type, limit accessor, and current-usage accessor.
+ * @returns An Express request handler.
+ *
+ * @example
+ * ```typescript
+ * router.post('/posts',
+ *   enforceLimit<BlogLimits>({
+ *     limitType: 'maxPosts',
+ *     getLimit: (limits) => limits.maxPosts,
+ *     getCurrent: (userId) => count('posts', [{ field: 'userId', operator: '=', value: userId }]),
+ *   }),
+ *   handlers.createPost,
+ * )
+ * ```
+ */
+export declare const enforceLimit: <TLimits = unknown>(options: EnforceLimitOptions<TLimits>) => RequestHandler;
+export {};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAqB,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEpE;;;;;;;;;;GAUG;AACH,UAAU,OAAO;IACf,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAC7B;AAED,2EAA2E;AAC3E,UAAU,QAAQ;IAChB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC9B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAA;IAC7B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC3C,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpE;AAED,wCAAwC;AACxC,KAAK,YAAY,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AAE3C,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzB;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAU,OAAO,GAAG,OAAO,EACtD,KAAK,QAAQ,KACZ,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAOvB,CAAA;AAaD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,GAAG,OAAO,EAC/C,GAAG,mBAAmB,MAAM,EAAE,KAC7B,cAqBF,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,GAAG,OAAO,EAAE,aAAa,MAAM,KAAG,cA0B/E,CAAA;AAED,iDAAiD;AACjD,MAAM,WAAW,mBAAmB,CAAC,OAAO,GAAG,OAAO;IACpD,2EAA2E;IAC3E,SAAS,EAAE,SAAS,CAAA;IAEpB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAA;IAErC;;;;;;;;OAQG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IAEtE;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,GAAG,OAAO,EAC5C,SAAS,mBAAmB,CAAC,OAAO,CAAC,KACpC,cA2BF,CAAA"}

package/dist/middleware.js

@@ -0,0 +1,155 @@
+/**
+ * Express middleware factories for tier-based entitlements.
+ *
+ * `requireCategory` and `requireCategoryAtLeast` gate endpoints by the user's
+ * tier category. `enforceLimit` checks a quantitative limit before allowing
+ * the request to proceed (e.g. "max 10 projects per user").
+ *
+ * Tier-aware windowed rate limiting (e.g. "60 requests per minute on free,
+ * 300 on pro") is intentionally not handled here — wire one
+ * `@molecule/api-rate-limit` middleware per tier and dispatch on category,
+ * or use the bonded rate-limit provider directly.
+ *
+ * @module
+ */
+import { t } from '@molecule/api-i18n';
+import { getCachedPlanKey } from './cache.js';
+import { buildLimitError } from './error.js';
+import { getProvider } from './provider.js';
+/**
+ * Resolves the effective tier for the user attached to the request via
+ * `res.locals.session.userId`. Falls back to the registry's default tier
+ * when no user is on the request, when the user record cannot be found, or
+ * when the stored plan has expired.
+ *
+ * @param res - The response object whose `locals.session.userId` identifies the user.
+ * @returns The user's effective tier.
+ */
+export const getEffectiveTier = async (res) => {
+    const registry = getProvider();
+    const userId = res.locals?.session?.userId;
+    if (!userId)
+        return registry.getDefaultTier();
+    const planKey = await getCachedPlanKey(userId);
+    return registry.findTier(planKey);
+};
+/**
+ * Builds a 401 response payload for unauthenticated requests.
+ *
+ * @returns An error envelope shaped like `LimitErrorPayload` for client uniformity.
+ */
+const buildUnauthorizedPayload = () => ({
+    error: t('entitlements.error.unauthenticated', undefined, {
+        defaultValue: 'Authentication required.',
+    }),
+});
+/**
+ * Creates middleware that allows the request only when the user's tier
+ * category is one of the listed values. Responds 401 if the request is
+ * unauthenticated, 403 with a `LimitErrorPayload`-shaped body if the user's
+ * tier is not in the list.
+ *
+ * @param allowedCategories - The tier categories that are permitted (e.g. `['pro', 'team']`).
+ * @returns An Express request handler.
+ */
+export const requireCategory = (...allowedCategories) => {
+    return async (_req, res, next) => {
+        const userId = res.locals?.session?.userId;
+        if (!userId) {
+            res.status(401).json(buildUnauthorizedPayload());
+            return;
+        }
+        const tier = await getEffectiveTier(res);
+        if (!allowedCategories.includes(tier.category)) {
+            const payload = buildLimitError({
+                limitType: 'category',
+                category: tier.category,
+                currentLimit: 0,
+            });
+            res.status(403).json(payload);
+            return;
+        }
+        next();
+    };
+};
+/**
+ * Creates middleware that allows the request only when the user's tier
+ * rank is at least as high as the named category. Useful for "pro and above"
+ * style gates without listing every category individually.
+ *
+ * Apps must include all gated categories in `categoryOrder` when calling
+ * `defineTiers(...)`; categories absent from the order produce `null` ranks
+ * and therefore fail the check.
+ *
+ * @param minCategory - The minimum acceptable category.
+ * @returns An Express request handler.
+ */
+export const requireCategoryAtLeast = (minCategory) => {
+    return async (_req, res, next) => {
+        const userId = res.locals?.session?.userId;
+        if (!userId) {
+            res.status(401).json(buildUnauthorizedPayload());
+            return;
+        }
+        const registry = getProvider();
+        const minRank = registry.getCategoryRank(minCategory);
+        const tier = await getEffectiveTier(res);
+        const userRank = registry.getCategoryRank(tier.category);
+        if (minRank == null || userRank == null || userRank < minRank) {
+            const payload = buildLimitError({
+                limitType: 'categoryAtLeast',
+                category: tier.category,
+                currentLimit: userRank ?? 0,
+            });
+            res.status(403).json(payload);
+            return;
+        }
+        next();
+    };
+};
+/**
+ * Creates middleware that allows the request only when the user is below
+ * their tier limit for the given resource. The user's tier `limits` object
+ * supplies the cap, and the caller-supplied `getCurrent` function counts
+ * the current usage.
+ *
+ * @param options - The limit type, limit accessor, and current-usage accessor.
+ * @returns An Express request handler.
+ *
+ * @example
+ * ```typescript
+ * router.post('/posts',
+ *   enforceLimit<BlogLimits>({
+ *     limitType: 'maxPosts',
+ *     getLimit: (limits) => limits.maxPosts,
+ *     getCurrent: (userId) => count('posts', [{ field: 'userId', operator: '=', value: userId }]),
+ *   }),
+ *   handlers.createPost,
+ * )
+ * ```
+ */
+export const enforceLimit = (options) => {
+    const { limitType, getLimit, getCurrent, status = 403 } = options;
+    return async (req, res, next) => {
+        const userId = res.locals?.session?.userId;
+        if (!userId) {
+            res.status(401).json(buildUnauthorizedPayload());
+            return;
+        }
+        const tier = await getEffectiveTier(res);
+        const limit = getLimit(tier.limits);
+        const current = await getCurrent(userId, req);
+        if (current >= limit) {
+            const payload = buildLimitError({
+                limitType,
+                category: tier.category,
+                currentLimit: limit,
+                resolveUpgradedLimit: getLimit,
+            });
+            res.status(status).json(payload);
+            return;
+        }
+        next();
+    };
+};
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/provider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Entitlements provider bond accessor.
+ *
+ * Apps construct a `TierRegistry` (typically via `defineTiers(...)`) and call
+ * `setProvider(registry)` at startup. Handler code, middleware, and any other
+ * consumer then resolves the bonded registry via `getProvider<TLimits>()`.
+ *
+ * @module
+ */
+import type { TierRegistry } from './types.js';
+/**
+ * Registers a tier registry as the active entitlements provider.
+ * Called by the application during startup.
+ *
+ * @param provider - The tier registry to bond.
+ */
+export declare const setProvider: <TLimits = unknown>(provider: TierRegistry<TLimits>) => void;
+/**
+ * Retrieves the bonded tier registry, throwing if none is configured.
+ *
+ * The generic parameter is the caller's responsibility — entitlements is
+ * inherently app-specific in its `TLimits` shape, and bonds are erased at
+ * runtime. Callers should pass their app's `TLimits` type at the call site.
+ *
+ * @returns The bonded tier registry.
+ * @throws {Error} If no entitlements provider has been bonded.
+ */
+export declare const getProvider: <TLimits = unknown>() => TierRegistry<TLimits>;
+/**
+ * Checks whether an entitlements provider is currently bonded.
+ *
+ * @returns `true` if a tier registry is bonded.
+ */
+export declare const hasProvider: () => boolean;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAK9C;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,GAAG,OAAO,EAAE,UAAU,YAAY,CAAC,OAAO,CAAC,KAAG,IAEhF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,GAAG,OAAO,OAAK,YAAY,CAAC,OAAO,CAYrE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAE9B,CAAA"}

package/dist/provider.js

@@ -0,0 +1,51 @@
+/**
+ * Entitlements provider bond accessor.
+ *
+ * Apps construct a `TierRegistry` (typically via `defineTiers(...)`) and call
+ * `setProvider(registry)` at startup. Handler code, middleware, and any other
+ * consumer then resolves the bonded registry via `getProvider<TLimits>()`.
+ *
+ * @module
+ */
+import { bond, expectBond, isBonded, require as bondRequire } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const BOND_TYPE = 'entitlements';
+expectBond(BOND_TYPE);
+/**
+ * Registers a tier registry as the active entitlements provider.
+ * Called by the application during startup.
+ *
+ * @param provider - The tier registry to bond.
+ */
+export const setProvider = (provider) => {
+    bond(BOND_TYPE, provider);
+};
+/**
+ * Retrieves the bonded tier registry, throwing if none is configured.
+ *
+ * The generic parameter is the caller's responsibility — entitlements is
+ * inherently app-specific in its `TLimits` shape, and bonds are erased at
+ * runtime. Callers should pass their app's `TLimits` type at the call site.
+ *
+ * @returns The bonded tier registry.
+ * @throws {Error} If no entitlements provider has been bonded.
+ */
+export const getProvider = () => {
+    try {
+        return bondRequire(BOND_TYPE);
+    }
+    catch (error) {
+        throw new Error(t('entitlements.error.noProvider', undefined, {
+            defaultValue: 'Entitlements provider not configured. Call setProvider(tierRegistry) at startup.',
+        }), { cause: error });
+    }
+};
+/**
+ * Checks whether an entitlements provider is currently bonded.
+ *
+ * @returns `true` if a tier registry is bonded.
+ */
+export const hasProvider = () => {
+    return isBonded(BOND_TYPE);
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACvF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAItC,MAAM,SAAS,GAAG,cAAc,CAAA;AAChC,UAAU,CAAC,SAAS,CAAC,CAAA;AAErB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAoB,QAA+B,EAAQ,EAAE;IACtF,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAA6C,EAAE;IACxE,IAAI,CAAC;QACH,OAAO,WAAW,CAAwB,SAAS,CAAC,CAAA;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,+BAA+B,EAAE,SAAS,EAAE;YAC5C,YAAY,EACV,kFAAkF;SACrF,CAAC,EACF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE;IACvC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA"}

package/dist/registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tier registry construction.
+ *
+ * `defineTiers(...)` builds a `TierRegistry` from a flat record of tiers plus
+ * a category upgrade order. Apps typically call this once at startup and
+ * bond the result via `setProvider(...)`.
+ *
+ * @module
+ */
+import type { DefineTiersOptions, TierRegistry } from './types.js';
+/**
+ * Constructs a `TierRegistry` from a tier record and category order.
+ *
+ * Validates that the `defaultPlanKey` exists in the `tiers` record and that
+ * every tier's `category` appears in `categoryOrder`. Throws synchronously
+ * on misconfiguration so problems surface at startup, not at request time.
+ *
+ * @param options - The tier set, default plan key, and category upgrade order.
+ * @returns A typed tier registry suitable for `setProvider(...)`.
+ * @throws {Error} If `defaultPlanKey` is missing from `tiers` or any tier's
+ *   category is missing from `categoryOrder`.
+ *
+ * @example
+ * ```typescript
+ * interface BlogLimits {
+ *   maxPosts: number
+ *   maxCommentsPerDay: number
+ * }
+ *
+ * const registry = defineTiers<BlogLimits>({
+ *   tiers: {
+ *     free: { planKey: 'free', category: 'free', name: 'Free', limits: { maxPosts: 5, maxCommentsPerDay: 50 } },
+ *     stripeMonthly: { planKey: 'stripeMonthly', category: 'pro', name: 'Pro', limits: { maxPosts: 100, maxCommentsPerDay: 1000 } },
+ *   },
+ *   defaultPlanKey: 'free',
+ *   categoryOrder: ['free', 'pro'],
+ * })
+ * ```
+ */
+export declare const defineTiers: <TLimits = unknown>(options: DefineTiersOptions<TLimits>) => TierRegistry<TLimits>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAQ,YAAY,EAAE,MAAM,YAAY,CAAA;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,GAAG,OAAO,EAC3C,SAAS,kBAAkB,CAAC,OAAO,CAAC,KACnC,YAAY,CAAC,OAAO,CAiEtB,CAAA"}

package/dist/registry.js

@@ -0,0 +1,88 @@
+/**
+ * Tier registry construction.
+ *
+ * `defineTiers(...)` builds a `TierRegistry` from a flat record of tiers plus
+ * a category upgrade order. Apps typically call this once at startup and
+ * bond the result via `setProvider(...)`.
+ *
+ * @module
+ */
+import { t } from '@molecule/api-i18n';
+/**
+ * Constructs a `TierRegistry` from a tier record and category order.
+ *
+ * Validates that the `defaultPlanKey` exists in the `tiers` record and that
+ * every tier's `category` appears in `categoryOrder`. Throws synchronously
+ * on misconfiguration so problems surface at startup, not at request time.
+ *
+ * @param options - The tier set, default plan key, and category upgrade order.
+ * @returns A typed tier registry suitable for `setProvider(...)`.
+ * @throws {Error} If `defaultPlanKey` is missing from `tiers` or any tier's
+ *   category is missing from `categoryOrder`.
+ *
+ * @example
+ * ```typescript
+ * interface BlogLimits {
+ *   maxPosts: number
+ *   maxCommentsPerDay: number
+ * }
+ *
+ * const registry = defineTiers<BlogLimits>({
+ *   tiers: {
+ *     free: { planKey: 'free', category: 'free', name: 'Free', limits: { maxPosts: 5, maxCommentsPerDay: 50 } },
+ *     stripeMonthly: { planKey: 'stripeMonthly', category: 'pro', name: 'Pro', limits: { maxPosts: 100, maxCommentsPerDay: 1000 } },
+ *   },
+ *   defaultPlanKey: 'free',
+ *   categoryOrder: ['free', 'pro'],
+ * })
+ * ```
+ */
+export const defineTiers = (options) => {
+    const { tiers, defaultPlanKey, categoryOrder } = options;
+    const defaultTier = tiers[defaultPlanKey];
+    if (!defaultTier) {
+        throw new Error(t('entitlements.error.missingDefaultTier', { planKey: defaultPlanKey }, {
+            defaultValue: `defineTiers: defaultPlanKey "${defaultPlanKey}" not found in tiers record.`,
+        }));
+    }
+    const orderRanks = new Map();
+    categoryOrder.forEach((category, index) => {
+        orderRanks.set(category, index);
+    });
+    for (const [planKey, tier] of Object.entries(tiers)) {
+        if (!orderRanks.has(tier.category)) {
+            throw new Error(t('entitlements.error.missingCategory', { planKey, category: tier.category }, {
+                defaultValue: `defineTiers: tier "${planKey}" has category "${tier.category}" which is not in categoryOrder.`,
+            }));
+        }
+    }
+    const allTiers = Object.values(tiers);
+    return {
+        findTier(planKey) {
+            if (planKey == null)
+                return defaultTier;
+            const tier = tiers[planKey];
+            if (tier)
+                return tier;
+            return defaultTier;
+        },
+        getDefaultTier() {
+            return defaultTier;
+        },
+        getAllTiers() {
+            return allTiers;
+        },
+        getCategoryRank(category) {
+            const rank = orderRanks.get(category);
+            return rank ?? null;
+        },
+        getNextCategory(category) {
+            const rank = orderRanks.get(category);
+            if (rank == null)
+                return null;
+            const next = categoryOrder[rank + 1];
+            return next ?? null;
+        },
+    };
+};
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAItC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,OAAoC,EACb,EAAE;IACzB,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,OAAO,CAAA;IAExD,MAAM,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,CAAA;IACzC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,CAAC,CACC,uCAAuC,EACvC,EAAE,OAAO,EAAE,cAAc,EAAE,EAC3B;YACE,YAAY,EAAE,gCAAgC,cAAc,8BAA8B;SAC3F,CACF,CACF,CAAA;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC5C,aAAa,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE;QACxC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IACjC,CAAC,CAAC,CAAA;IAEF,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,CAAC,CACC,oCAAoC,EACpC,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,EACpC;gBACE,YAAY,EAAE,sBAAsB,OAAO,mBAAmB,IAAI,CAAC,QAAQ,kCAAkC;aAC9G,CACF,CACF,CAAA;QACH,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAoB,CAAA;IAExD,OAAO;QACL,QAAQ,CAAC,OAAO;YACd,IAAI,OAAO,IAAI,IAAI;gBAAE,OAAO,WAAW,CAAA;YACvC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAA;YAC3B,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAA;YACrB,OAAO,WAAW,CAAA;QACpB,CAAC;QAED,cAAc;YACZ,OAAO,WAAW,CAAA;QACpB,CAAC;QAED,WAAW;YACT,OAAO,QAAQ,CAAA;QACjB,CAAC;QAED,eAAe,CAAC,QAAQ;YACtB,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACrC,OAAO,IAAI,IAAI,IAAI,CAAA;QACrB,CAAC;QAED,eAAe,CAAC,QAAQ;YACtB,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACrC,IAAI,IAAI,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAA;YAC7B,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,CAAC,CAAA;YACpC,OAAO,IAAI,IAAI,IAAI,CAAA;QACrB,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}