@tumbaland/backend-core 1.22.0 → 1.24.0

package/dist/entitlements/index.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retentionFloor = exports.requireQuota = exports.requireEntitlement = exports.loadEntitlements = exports.clearEntitlementsCache = exports.invalidateEntitlements = exports.getEntitlements = exports.setUsage = exports.releaseQuota = exports.consumeQuota = exports.checkQuota = exports.getUsageSnapshot = exports.getUsage = exports.currentPeriod = exports.UsageMeter = exports.resetEntitlementsModeWarning = exports.getEntitlementsMode = exports.fitsWithin = exports.isFeatureKey = exports.isMeterKey = exports.meterPeriod = exports.normalizeLimits = exports.resolveLimits = exports.ENTITLEMENT_CATALOG = exports.DEFAULT_PLAN_LIMITS = exports.FEATURE_DEFINITIONS = exports.METER_DEFINITIONS = exports.FEATURE_KEYS = exports.METER_KEYS = exports.applyLimits = exports.STAFF_PLAN = exports.FALLBACK_PLAN = exports.UNLIMITED = void 0;
+var definitions_1 = require("./definitions");
+Object.defineProperty(exports, "UNLIMITED", { enumerable: true, get: function () { return definitions_1.UNLIMITED; } });
+Object.defineProperty(exports, "FALLBACK_PLAN", { enumerable: true, get: function () { return definitions_1.FALLBACK_PLAN; } });
+Object.defineProperty(exports, "STAFF_PLAN", { enumerable: true, get: function () { return definitions_1.STAFF_PLAN; } });
+Object.defineProperty(exports, "applyLimits", { enumerable: true, get: function () { return definitions_1.applyLimits; } });
+Object.defineProperty(exports, "METER_KEYS", { enumerable: true, get: function () { return definitions_1.METER_KEYS; } });
+Object.defineProperty(exports, "FEATURE_KEYS", { enumerable: true, get: function () { return definitions_1.FEATURE_KEYS; } });
+Object.defineProperty(exports, "METER_DEFINITIONS", { enumerable: true, get: function () { return definitions_1.METER_DEFINITIONS; } });
+Object.defineProperty(exports, "FEATURE_DEFINITIONS", { enumerable: true, get: function () { return definitions_1.FEATURE_DEFINITIONS; } });
+Object.defineProperty(exports, "DEFAULT_PLAN_LIMITS", { enumerable: true, get: function () { return definitions_1.DEFAULT_PLAN_LIMITS; } });
+Object.defineProperty(exports, "ENTITLEMENT_CATALOG", { enumerable: true, get: function () { return definitions_1.ENTITLEMENT_CATALOG; } });
+Object.defineProperty(exports, "resolveLimits", { enumerable: true, get: function () { return definitions_1.resolveLimits; } });
+Object.defineProperty(exports, "normalizeLimits", { enumerable: true, get: function () { return definitions_1.normalizeLimits; } });
+Object.defineProperty(exports, "meterPeriod", { enumerable: true, get: function () { return definitions_1.meterPeriod; } });
+Object.defineProperty(exports, "isMeterKey", { enumerable: true, get: function () { return definitions_1.isMeterKey; } });
+Object.defineProperty(exports, "isFeatureKey", { enumerable: true, get: function () { return definitions_1.isFeatureKey; } });
+Object.defineProperty(exports, "fitsWithin", { enumerable: true, get: function () { return definitions_1.fitsWithin; } });
+var mode_1 = require("./mode");
+Object.defineProperty(exports, "getEntitlementsMode", { enumerable: true, get: function () { return mode_1.getEntitlementsMode; } });
+Object.defineProperty(exports, "resetEntitlementsModeWarning", { enumerable: true, get: function () { return mode_1.resetEntitlementsModeWarning; } });
+var UsageMeter_1 = require("./UsageMeter");
+Object.defineProperty(exports, "UsageMeter", { enumerable: true, get: function () { return UsageMeter_1.UsageMeter; } });
+Object.defineProperty(exports, "currentPeriod", { enumerable: true, get: function () { return UsageMeter_1.currentPeriod; } });
+var usage_1 = require("./usage");
+Object.defineProperty(exports, "getUsage", { enumerable: true, get: function () { return usage_1.getUsage; } });
+Object.defineProperty(exports, "getUsageSnapshot", { enumerable: true, get: function () { return usage_1.getUsageSnapshot; } });
+Object.defineProperty(exports, "checkQuota", { enumerable: true, get: function () { return usage_1.checkQuota; } });
+Object.defineProperty(exports, "consumeQuota", { enumerable: true, get: function () { return usage_1.consumeQuota; } });
+Object.defineProperty(exports, "releaseQuota", { enumerable: true, get: function () { return usage_1.releaseQuota; } });
+Object.defineProperty(exports, "setUsage", { enumerable: true, get: function () { return usage_1.setUsage; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "getEntitlements", { enumerable: true, get: function () { return client_1.getEntitlements; } });
+Object.defineProperty(exports, "invalidateEntitlements", { enumerable: true, get: function () { return client_1.invalidateEntitlements; } });
+Object.defineProperty(exports, "clearEntitlementsCache", { enumerable: true, get: function () { return client_1.clearEntitlementsCache; } });
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "loadEntitlements", { enumerable: true, get: function () { return middleware_1.loadEntitlements; } });
+Object.defineProperty(exports, "requireEntitlement", { enumerable: true, get: function () { return middleware_1.requireEntitlement; } });
+Object.defineProperty(exports, "requireQuota", { enumerable: true, get: function () { return middleware_1.requireQuota; } });
+Object.defineProperty(exports, "retentionFloor", { enumerable: true, get: function () { return middleware_1.retentionFloor; } });
+//# sourceMappingURL=index.js.map

package/dist/entitlements/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":";;;AAAA,6CAiBuB;AAhBrB,wGAAA,SAAS,OAAA;AACT,4GAAA,aAAa,OAAA;AACb,yGAAA,UAAU,OAAA;AACV,0GAAA,WAAW,OAAA;AACX,yGAAA,UAAU,OAAA;AACV,2GAAA,YAAY,OAAA;AACZ,gHAAA,iBAAiB,OAAA;AACjB,kHAAA,mBAAmB,OAAA;AACnB,kHAAA,mBAAmB,OAAA;AACnB,kHAAA,mBAAmB,OAAA;AACnB,4GAAA,aAAa,OAAA;AACb,8GAAA,eAAe,OAAA;AACf,0GAAA,WAAW,OAAA;AACX,yGAAA,UAAU,OAAA;AACV,2GAAA,YAAY,OAAA;AACZ,yGAAA,UAAU,OAAA;AAaZ,+BAA2E;AAAlE,2GAAA,mBAAmB,OAAA;AAAE,oHAAA,4BAA4B,OAAA;AAE1D,2CAAyD;AAAhD,wGAAA,UAAU,OAAA;AAAE,2GAAA,aAAa,OAAA;AAElC,iCAAuG;AAA9F,iGAAA,QAAQ,OAAA;AAAE,yGAAA,gBAAgB,OAAA;AAAE,mGAAA,UAAU,OAAA;AAAE,qGAAA,YAAY,OAAA;AAAE,qGAAA,YAAY,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAGrF,mCAA2F;AAAlF,yGAAA,eAAe,OAAA;AAAE,gHAAA,sBAAsB,OAAA;AAAE,gHAAA,sBAAsB,OAAA;AAExE,2CAAkG;AAAzF,8GAAA,gBAAgB,OAAA;AAAE,gHAAA,kBAAkB,OAAA;AAAE,0GAAA,YAAY,OAAA;AAAE,4GAAA,cAAc,OAAA"}

package/dist/entitlements/middleware.d.ts

@@ -0,0 +1,54 @@
+import { Request, RequestHandler } from 'express';
+import { FeatureKey, MeterKey } from './definitions';
+import { Entitlements } from './types';
+declare global {
+    namespace Express {
+        interface Request {
+            /** Populated by the entitlement middlewares so controllers can read limits without a second lookup. */
+            entitlements?: Entitlements;
+        }
+    }
+}
+/**
+ * Who the check is billed to. Defaults to the authenticated user; group
+ * chokepoints override it with the group owner, since pooled quota belongs to
+ * whoever pays for the group.
+ */
+export type SubjectResolver = (req: Request) => string | undefined | Promise<string | undefined>;
+export interface EntitlementOptions {
+    subject?: SubjectResolver;
+}
+/**
+ * Resolves and caches entitlements on the request. Two checks on one route
+ * (a feature gate plus a quota gate) therefore cost one lookup, not two.
+ */
+export declare function loadEntitlements(req: Request, resolve?: SubjectResolver): Promise<Entitlements>;
+/**
+ * Gate a feature flag. Reads are never gated by design — use this on writes,
+ * dispatches and exports only.
+ */
+export declare function requireEntitlement(feature: FeatureKey, options?: EntitlementOptions): RequestHandler;
+export interface QuotaOptions extends EntitlementOptions {
+    /**
+     * How much this request costs. A function when the amount is in the payload
+     * — an upload's `sizeBytes`, say — which is also why the storage gate sits on
+     * the signed-URL request: it is the only point where the size is known
+     * *before* the bytes are written.
+     */
+    amount?: number | ((req: Request) => number);
+}
+/**
+ * Read-only quota gate. Records nothing — the increment belongs at the point
+ * the resource actually comes into existence, via `consumeQuota`.
+ */
+export declare function requireQuota(meter: MeterKey, options?: QuotaOptions): RequestHandler;
+/**
+ * The oldest timestamp a user may read, or `null` for unlimited history.
+ *
+ * Meant to be dropped straight into an aggregation `$match` — this is what
+ * gates the portfolio planner, since the planner runs entirely client-side and
+ * any `<PaywallGate>` around it is bypassable from devtools. Truncating the
+ * price history it depends on is not.
+ */
+export declare function retentionFloor(email: string, now?: Date): Promise<Date | null>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/entitlements/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/entitlements/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAa,MAAM,eAAe,CAAC;AAIhE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,uGAAuG;YACvG,YAAY,CAAC,EAAE,YAAY,CAAC;SAC7B;KACF;CACF;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjG,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAID;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,eAAgC,GAAG,OAAO,CAAC,YAAY,CAAC,CASrH;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,GAAE,kBAAuB,GAAG,cAAc,CA+BxG;AAED,MAAM,WAAW,YAAa,SAAQ,kBAAkB;IACtD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAE,YAAiB,GAAG,cAAc,CAoBxF;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAQhG"}

package/dist/entitlements/middleware.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEntitlements = loadEntitlements;
+exports.requireEntitlement = requireEntitlement;
+exports.requireQuota = requireQuota;
+exports.retentionFloor = retentionFloor;
+const logger_1 = __importDefault(require("../logging/logger"));
+const HttpError_1 = require("../errors/HttpError");
+const definitions_1 = require("./definitions");
+const client_1 = require("./client");
+const usage_1 = require("./usage");
+const mode_1 = require("./mode");
+const defaultSubject = req => req.user?.email;
+/**
+ * Resolves and caches entitlements on the request. Two checks on one route
+ * (a feature gate plus a quota gate) therefore cost one lookup, not two.
+ */
+async function loadEntitlements(req, resolve = defaultSubject) {
+    if (req.entitlements)
+        return req.entitlements;
+    const subject = await resolve(req);
+    if (!subject)
+        throw new HttpError_1.UnauthorizedError('Authentication required');
+    const entitlements = await (0, client_1.getEntitlements)(subject);
+    req.entitlements = entitlements;
+    return entitlements;
+}
+/**
+ * Gate a feature flag. Reads are never gated by design — use this on writes,
+ * dispatches and exports only.
+ */
+function requireEntitlement(feature, options = {}) {
+    return async (req, _res, next) => {
+        try {
+            const mode = (0, mode_1.getEntitlementsMode)();
+            if (mode === 'off')
+                return next();
+            const entitlements = await loadEntitlements(req, options.subject);
+            if (entitlements.limits.features[feature])
+                return next();
+            if (mode === 'observe') {
+                logger_1.default.info('entitlement.would_block', {
+                    event: 'entitlement.would_block',
+                    feature,
+                    subjectId: entitlements.email,
+                    planCode: entitlements.planCode,
+                    route: req.originalUrl,
+                    stale: entitlements.stale === true
+                });
+                return next();
+            }
+            throw new HttpError_1.PaymentRequiredError(`Your plan does not include ${feature}`, {
+                code: 'FEATURE_NOT_IN_PLAN',
+                feature,
+                planCode: entitlements.planCode,
+                upgradeTo: entitlements.upgradeTo
+            });
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+}
+/**
+ * Read-only quota gate. Records nothing — the increment belongs at the point
+ * the resource actually comes into existence, via `consumeQuota`.
+ */
+function requireQuota(meter, options = {}) {
+    return async (req, _res, next) => {
+        try {
+            if ((0, mode_1.getEntitlementsMode)() === 'off')
+                return next();
+            const entitlements = await loadEntitlements(req, options.subject);
+            const amount = typeof options.amount === 'function' ? options.amount(req) : (options.amount ?? 1);
+            await (0, usage_1.checkQuota)({
+                subjectId: entitlements.email,
+                meter,
+                amount,
+                entitlements,
+                route: req.originalUrl
+            });
+            next();
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+}
+/**
+ * The oldest timestamp a user may read, or `null` for unlimited history.
+ *
+ * Meant to be dropped straight into an aggregation `$match` — this is what
+ * gates the portfolio planner, since the planner runs entirely client-side and
+ * any `<PaywallGate>` around it is bypassable from devtools. Truncating the
+ * price history it depends on is not.
+ */
+async function retentionFloor(email, now = new Date()) {
+    if ((0, mode_1.getEntitlementsMode)() !== 'enforce')
+        return null;
+    const { limits } = await (0, client_1.getEntitlements)(email);
+    const days = limits.retentionDays;
+    if (days === definitions_1.UNLIMITED || days < 0)
+        return null;
+    return new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
+}
+//# sourceMappingURL=middleware.js.map

package/dist/entitlements/middleware.js.map

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

package/dist/entitlements/mode.d.ts

@@ -0,0 +1,10 @@
+import { EntitlementsMode } from './types';
+/**
+ * Read per call rather than cached at import time: a service can be flipped to
+ * `enforce` by restarting it with a new env value, and tests set the variable
+ * between cases. The cost is one `process.env` lookup per check.
+ */
+export declare function getEntitlementsMode(): EntitlementsMode;
+/** Test seam — the "already warned" latch would otherwise leak between cases. */
+export declare function resetEntitlementsModeWarning(): void;
+//# sourceMappingURL=mode.d.ts.map

package/dist/entitlements/mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/entitlements/mode.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAM3C;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAUtD;AAED,iFAAiF;AACjF,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}

package/dist/entitlements/mode.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEntitlementsMode = getEntitlementsMode;
+exports.resetEntitlementsModeWarning = resetEntitlementsModeWarning;
+const logger_1 = __importDefault(require("../logging/logger"));
+const VALID_MODES = ['off', 'observe', 'enforce'];
+let warnedAboutInvalidMode = false;
+/**
+ * Read per call rather than cached at import time: a service can be flipped to
+ * `enforce` by restarting it with a new env value, and tests set the variable
+ * between cases. The cost is one `process.env` lookup per check.
+ */
+function getEntitlementsMode() {
+    const raw = (process.env.ENTITLEMENTS_MODE || '').trim().toLowerCase();
+    if (!raw)
+        return 'observe';
+    if (VALID_MODES.includes(raw))
+        return raw;
+    if (!warnedAboutInvalidMode) {
+        warnedAboutInvalidMode = true;
+        logger_1.default.warn('Invalid ENTITLEMENTS_MODE, falling back to observe', { value: raw });
+    }
+    return 'observe';
+}
+/** Test seam — the "already warned" latch would otherwise leak between cases. */
+function resetEntitlementsModeWarning() {
+    warnedAboutInvalidMode = false;
+}
+//# sourceMappingURL=mode.js.map

package/dist/entitlements/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../src/entitlements/mode.ts"],"names":[],"mappings":";;;;;AAYA,kDAUC;AAGD,oEAEC;AA3BD,+DAAuC;AAGvC,MAAM,WAAW,GAAgC,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAE/E,IAAI,sBAAsB,GAAG,KAAK,CAAC;AAEnC;;;;GAIG;AACH,SAAgB,mBAAmB;IACjC,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvE,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAK,WAAiC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,GAAuB,CAAC;IAErF,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC5B,sBAAsB,GAAG,IAAI,CAAC;QAC9B,gBAAM,CAAC,IAAI,CAAC,oDAAoD,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iFAAiF;AACjF,SAAgB,4BAA4B;IAC1C,sBAAsB,GAAG,KAAK,CAAC;AACjC,CAAC"}

package/dist/entitlements/types.d.ts

@@ -0,0 +1,29 @@
+import { PlanLimits } from './definitions';
+/**
+ * What payment-service answers for a user, and what the client caches.
+ * `limits` is already normalized — consumers never merge defaults themselves.
+ */
+export interface Entitlements {
+    email: string;
+    planCode: string;
+    /** Subscription status backing the plan; `null` for users on the implicit free plan. */
+    status: string | null;
+    limits: PlanLimits;
+    /** Cheapest active plan priced above the current one, for the upgrade dialog's CTA. */
+    upgradeTo?: string;
+    /**
+     * Set when payment-service could not be reached and these are fallback
+     * limits rather than the user's real ones. Enforcement still applies (fail
+     * closed), but the value lets callers log the difference.
+     */
+    stale?: boolean;
+}
+/**
+ * `off` — no metering, no blocking. `observe` — record usage and log what
+ * would have been blocked, block nothing. `enforce` — block.
+ *
+ * Observe is the default because the configured limits start as guesses; two
+ * weeks of `entitlement.would_block` volume is what turns them into numbers.
+ */
+export type EntitlementsMode = 'off' | 'observe' | 'enforce';
+//# sourceMappingURL=types.d.ts.map

package/dist/entitlements/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entitlements/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC"}

package/dist/entitlements/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/entitlements/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/entitlements/types.ts"],"names":[],"mappings":""}

package/dist/entitlements/usage.d.ts

@@ -0,0 +1,56 @@
+import { MeterKey } from './definitions';
+import { Entitlements } from './types';
+export interface QuotaRequest {
+    /** Who the usage is billed to — see `IUsageMeter.subjectId`. */
+    subjectId: string;
+    meter: MeterKey;
+    /** How much this request wants. Bytes for `storageBytes`, otherwise a count. */
+    amount?: number;
+    entitlements: Entitlements;
+    /** Attached to the observe-mode log line so a would-block can be traced to a route. */
+    route?: string;
+}
+/** Current count for one meter in its live period. */
+export declare function getUsage(subjectId: string, meter: MeterKey, now?: Date): Promise<number>;
+/** Every meter at once, for the account page and the pricing table's live numbers. */
+export declare function getUsageSnapshot(subjectId: string, now?: Date): Promise<Record<MeterKey, number>>;
+/**
+ * Read-only check for cumulative meters whose real increment happens later
+ * (storage is counted when the upload lands, not when it is authorized).
+ *
+ * Racy by construction — two concurrent requests can both pass — which is
+ * acceptable here precisely because the meters it guards are reconciled from
+ * the underlying data. Use `consumeQuota` where the count is the only record.
+ */
+export declare function checkQuota(req: QuotaRequest): Promise<void>;
+/**
+ * Atomically reserve capacity, throwing when the reservation would overrun.
+ *
+ * The increment and the check are one `$inc` + read, not a read-then-write:
+ * two concurrent requests that both read "24 used" against a limit of 25 would
+ * both proceed and overrun. Incrementing first and rejecting on the
+ * *post-increment* value means the loser of that race is the one rejected.
+ *
+ * A rejected reservation rolls its own increment back before throwing — unlike
+ * the provider-quota version this generalizes, where an over-limit count just
+ * sits there until the day rolls over. A per-user cumulative meter never rolls
+ * over, so a leaked increment is permanent and shows up months later as a user
+ * who cannot upload despite being well under their limit.
+ */
+export declare function consumeQuota(req: QuotaRequest): Promise<void>;
+/**
+ * Hand back capacity after a failure that never consumed it (the upload errored,
+ * the AI service refused the job), and on deletes — a cumulative meter that only
+ * counts up is a bug that surfaces as an angry support email six months in.
+ *
+ * Never drops below zero, and never throws: a failed release must not turn a
+ * recoverable error into a 500 for the caller that was already unwinding.
+ */
+export declare function releaseQuota(subjectId: string, meter: MeterKey, amount?: number, now?: Date): Promise<void>;
+/**
+ * Set a meter to a known value. For the backfill (existing storage has to be
+ * seeded or every current user starts at zero and silently exceeds later) and
+ * for periodic reconciliation against the source of truth.
+ */
+export declare function setUsage(subjectId: string, meter: MeterKey, count: number, now?: Date): Promise<void>;
+//# sourceMappingURL=usage.d.ts.map

package/dist/entitlements/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/entitlements/usage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAqC,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,YAAY,CAAC;IAC3B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sDAAsD;AACtD,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAO9F;AAED,sFAAsF;AACtF,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAYvG;AA2BD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAejE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BnE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EACf,MAAM,SAAI,EACV,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/entitlements/usage.js

@@ -0,0 +1,159 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUsage = getUsage;
+exports.getUsageSnapshot = getUsageSnapshot;
+exports.checkQuota = checkQuota;
+exports.consumeQuota = consumeQuota;
+exports.releaseQuota = releaseQuota;
+exports.setUsage = setUsage;
+const logger_1 = __importDefault(require("../logging/logger"));
+const HttpError_1 = require("../errors/HttpError");
+const UsageMeter_1 = require("./UsageMeter");
+const definitions_1 = require("./definitions");
+const mode_1 = require("./mode");
+/** Current count for one meter in its live period. */
+async function getUsage(subjectId, meter, now) {
+    const doc = await UsageMeter_1.UsageMeter.findOne({
+        subjectId: subjectId.toLowerCase(),
+        meter,
+        period: (0, UsageMeter_1.currentPeriod)(meter, now)
+    }).lean();
+    return doc?.count ?? 0;
+}
+/** Every meter at once, for the account page and the pricing table's live numbers. */
+async function getUsageSnapshot(subjectId, now) {
+    const periods = definitions_1.METER_KEYS.map(meter => ({ meter, period: (0, UsageMeter_1.currentPeriod)(meter, now) }));
+    const docs = await UsageMeter_1.UsageMeter.find({
+        subjectId: subjectId.toLowerCase(),
+        $or: periods.map(p => ({ meter: p.meter, period: p.period }))
+    }).lean();
+    const snapshot = Object.fromEntries(definitions_1.METER_KEYS.map(k => [k, 0]));
+    for (const doc of docs) {
+        if (definitions_1.METER_KEYS.includes(doc.meter))
+            snapshot[doc.meter] = doc.count;
+    }
+    return snapshot;
+}
+function quotaError(req, used, limit) {
+    return new HttpError_1.PaymentRequiredError(`Limit reached for ${req.meter}`, {
+        code: 'QUOTA_EXCEEDED',
+        meter: req.meter,
+        used,
+        limit,
+        planCode: req.entitlements.planCode,
+        upgradeTo: req.entitlements.upgradeTo
+    });
+}
+function logWouldBlock(req, used, limit) {
+    logger_1.default.info('entitlement.would_block', {
+        event: 'entitlement.would_block',
+        meter: req.meter,
+        subjectId: req.subjectId,
+        amount: req.amount ?? 1,
+        used,
+        limit,
+        planCode: req.entitlements.planCode,
+        route: req.route,
+        stale: req.entitlements.stale === true
+    });
+}
+/**
+ * Read-only check for cumulative meters whose real increment happens later
+ * (storage is counted when the upload lands, not when it is authorized).
+ *
+ * Racy by construction — two concurrent requests can both pass — which is
+ * acceptable here precisely because the meters it guards are reconciled from
+ * the underlying data. Use `consumeQuota` where the count is the only record.
+ */
+async function checkQuota(req) {
+    const mode = (0, mode_1.getEntitlementsMode)();
+    if (mode === 'off')
+        return;
+    const limit = req.entitlements.limits.meters[req.meter] ?? definitions_1.UNLIMITED;
+    if (limit === definitions_1.UNLIMITED)
+        return;
+    const used = await getUsage(req.subjectId, req.meter);
+    if ((0, definitions_1.fitsWithin)(limit, used, req.amount ?? 1))
+        return;
+    if (mode === 'observe') {
+        logWouldBlock(req, used, limit);
+        return;
+    }
+    throw quotaError(req, used, limit);
+}
+/**
+ * Atomically reserve capacity, throwing when the reservation would overrun.
+ *
+ * The increment and the check are one `$inc` + read, not a read-then-write:
+ * two concurrent requests that both read "24 used" against a limit of 25 would
+ * both proceed and overrun. Incrementing first and rejecting on the
+ * *post-increment* value means the loser of that race is the one rejected.
+ *
+ * A rejected reservation rolls its own increment back before throwing — unlike
+ * the provider-quota version this generalizes, where an over-limit count just
+ * sits there until the day rolls over. A per-user cumulative meter never rolls
+ * over, so a leaked increment is permanent and shows up months later as a user
+ * who cannot upload despite being well under their limit.
+ */
+async function consumeQuota(req) {
+    const mode = (0, mode_1.getEntitlementsMode)();
+    if (mode === 'off')
+        return;
+    const amount = req.amount ?? 1;
+    const limit = req.entitlements.limits.meters[req.meter] ?? definitions_1.UNLIMITED;
+    const period = (0, UsageMeter_1.currentPeriod)(req.meter);
+    const subjectId = req.subjectId.toLowerCase();
+    const usage = await UsageMeter_1.UsageMeter.findOneAndUpdate({ subjectId, meter: req.meter, period }, { $inc: { count: amount } }, { upsert: true, returnDocument: 'after', setDefaultsOnInsert: true });
+    if (limit === definitions_1.UNLIMITED || usage.count <= limit)
+        return;
+    const usedBefore = usage.count - amount;
+    if (mode === 'observe') {
+        // Keep the increment: observe mode exists to measure real demand, and a
+        // rolled-back count would under-report exactly the users who matter.
+        logWouldBlock(req, usedBefore, limit);
+        return;
+    }
+    await releaseQuota(subjectId, req.meter, amount);
+    throw quotaError(req, usedBefore, limit);
+}
+/**
+ * Hand back capacity after a failure that never consumed it (the upload errored,
+ * the AI service refused the job), and on deletes — a cumulative meter that only
+ * counts up is a bug that surfaces as an angry support email six months in.
+ *
+ * Never drops below zero, and never throws: a failed release must not turn a
+ * recoverable error into a 500 for the caller that was already unwinding.
+ */
+async function releaseQuota(subjectId, meter, amount = 1, now) {
+    try {
+        const filter = { subjectId: subjectId.toLowerCase(), meter, period: (0, UsageMeter_1.currentPeriod)(meter, now) };
+        // Conditional `$inc` rather than read-then-write: a read-modify-write here
+        // loses concurrent releases, which on a cumulative meter is permanent drift.
+        const result = await UsageMeter_1.UsageMeter.updateOne({ ...filter, count: { $gte: amount } }, { $inc: { count: -amount } });
+        if (result.matchedCount === 0) {
+            // Either no counter exists, or it holds less than we are handing back
+            // (a reconciliation reset it in between). Clamp at zero, never negative.
+            await UsageMeter_1.UsageMeter.updateOne({ ...filter, count: { $lt: amount } }, { $set: { count: 0 } });
+        }
+    }
+    catch (err) {
+        logger_1.default.warn('Failed to release usage quota', {
+            subjectId,
+            meter,
+            amount,
+            error: err?.message
+        });
+    }
+}
+/**
+ * Set a meter to a known value. For the backfill (existing storage has to be
+ * seeded or every current user starts at zero and silently exceeds later) and
+ * for periodic reconciliation against the source of truth.
+ */
+async function setUsage(subjectId, meter, count, now) {
+    await UsageMeter_1.UsageMeter.updateOne({ subjectId: subjectId.toLowerCase(), meter, period: (0, UsageMeter_1.currentPeriod)(meter, now) }, { $set: { count: Math.max(0, Math.floor(count)) } }, { upsert: true, setDefaultsOnInsert: true });
+}
+//# sourceMappingURL=usage.js.map

package/dist/entitlements/usage.js.map

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

package/dist/errors/HttpError.d.ts

@@ -9,7 +9,13 @@
  */
 export declare class HttpError extends Error {
     statusCode: number;
-    constructor(statusCode: number, message: string);
+    /**
+     * Extra fields merged into the JSON body by the shared errorHandler. Used by
+     * errors the client has to *act* on rather than just display — a 402 tells
+     * the upgrade dialog which meter blocked and which plan lifts it.
+     */
+    details?: Record<string, unknown>;
+    constructor(statusCode: number, message: string, details?: Record<string, unknown>);
 }
 export declare class BadRequestError extends HttpError {
     constructor(message?: string);
@@ -29,4 +35,27 @@ export declare class ConflictError extends HttpError {
 export declare class TooManyRequestsError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * Fields the upgrade dialog renders. Every one of them comes from the response
+ * body, so the dialog needs no knowledge of which call failed.
+ */
+export interface PaymentRequiredDetails {
+    /** Machine-readable reason, e.g. `QUOTA_EXCEEDED` or `FEATURE_NOT_IN_PLAN`. */
+    code: string;
+    meter?: string;
+    feature?: string;
+    used?: number;
+    limit?: number;
+    planCode?: string;
+    /** The cheapest plan that lifts this particular limit, when one exists. */
+    upgradeTo?: string;
+}
+/**
+ * 402, never 403. 403 means "you may not"; 402 means "you may, for money" —
+ * and the frontend needs to tell those apart to choose between an error toast
+ * and an upgrade dialog.
+ */
+export declare class PaymentRequiredError extends HttpError {
+    constructor(message: string, details: PaymentRequiredDetails);
+}
 //# sourceMappingURL=HttpError.d.ts.map

package/dist/errors/HttpError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpError.d.ts","sourceRoot":"","sources":["../../src/errors/HttpError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,UAAU,EAAE,MAAM,CAAC;gBAEP,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAQhD;AAED,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,SAAgB;CAGpC;AAED,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,SAAiB;CAGrC;AAED,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,SAAkB;CAGtC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAc;CAGlC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAa;CAGjC;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,SAAsB;CAG1C"}
+{"version":3,"file":"HttpError.d.ts","sourceRoot":"","sources":["../../src/errors/HttpError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASnF;AAED,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,SAAgB;CAGpC;AAED,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,SAAiB;CAGrC;AAED,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,SAAkB;CAGtC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAc;CAGlC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAa;CAGjC;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,SAAsB;CAG1C;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB;CAG7D"}