@tumbaland/backend-core 1.23.0 → 1.25.0

package/dist/entitlements/definitions.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * The entitlement *vocabulary*: which meters and features exist, what they
+ * mean, and what a plan gets when nothing else says otherwise.
+ *
+ * The actual per-plan numbers are NOT here — they live on the `Plan` document
+ * in Mongo and are editable by an admin at runtime (see payment-service's
+ * `Plan.limits` and `PUT /api/plans/:code/limits`). Shipping a code change to
+ * move a limit from 50 GB to 75 GB would be absurd, and a hardcoded table
+ * would immediately drift from what the pricing page renders.
+ *
+ * What code still owns:
+ *   - the set of valid keys, so a typo in an admin form can't invent a meter
+ *     that nothing enforces (`normalizeLimits` drops unknown keys);
+ *   - `DEFAULT_PLAN_LIMITS`, the values used when a Plan document has no
+ *     `limits` yet (fresh install, newly created plan) or when payment-service
+ *     is unreachable and the client has to fail closed;
+ *   - `ENTITLEMENT_CATALOG`, the metadata an admin UI renders its form from,
+ *     so adding a meter needs no frontend change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTITLEMENT_CATALOG = exports.FALLBACK_PLAN = exports.STAFF_PLAN = exports.DEFAULT_PLAN_LIMITS = exports.FEATURE_KEYS = exports.METER_KEYS = exports.FEATURE_DEFINITIONS = exports.METER_DEFINITIONS = exports.UNLIMITED = void 0;
+exports.meterPeriod = meterPeriod;
+exports.isMeterKey = isMeterKey;
+exports.isFeatureKey = isFeatureKey;
+exports.resolveLimits = resolveLimits;
+exports.applyLimits = applyLimits;
+exports.normalizeLimits = normalizeLimits;
+exports.fitsWithin = fitsWithin;
+/** Sentinel for "no ceiling". Chosen over `Infinity` because it survives JSON and BSON. */
+exports.UNLIMITED = -1;
+exports.METER_DEFINITIONS = [
+    {
+        key: 'storageBytes',
+        label: 'Storage',
+        unit: 'bytes',
+        period: 'ALL',
+        description: 'Total bytes of uploaded photos and files held for the user.'
+    },
+    {
+        key: 'aiJobs',
+        label: 'AI analyses',
+        unit: 'count',
+        period: 'MONTH',
+        description: 'Segmentation and object-detection jobs dispatched per calendar month.'
+    },
+    {
+        key: 'trackedTickers',
+        label: 'Tracked tickers',
+        unit: 'count',
+        period: 'ALL',
+        description: 'Instruments followed for price history. Each one spends the deployment-wide market-data budget.'
+    },
+    {
+        key: 'seats',
+        label: 'Group seats',
+        unit: 'count',
+        period: 'ALL',
+        description: 'Members that may join groups owned by the user, including the owner.'
+    }
+];
+exports.FEATURE_DEFINITIONS = [
+    {
+        key: 'cleanExport',
+        label: 'Clean export',
+        description: 'Exports and downloads without a watermark.'
+    }
+];
+exports.METER_KEYS = exports.METER_DEFINITIONS.map(m => m.key);
+exports.FEATURE_KEYS = exports.FEATURE_DEFINITIONS.map(f => f.key);
+const METER_PERIODS = Object.fromEntries(exports.METER_DEFINITIONS.map(m => [m.key, m.period]));
+function meterPeriod(meter) {
+    return METER_PERIODS[meter] ?? 'ALL';
+}
+function isMeterKey(value) {
+    return exports.METER_KEYS.includes(value);
+}
+function isFeatureKey(value) {
+    return exports.FEATURE_KEYS.includes(value);
+}
+const GB = 1024 * 1024 * 1024;
+/**
+ * Bootstrap values only — a Plan document's own `limits` wins over anything
+ * here. These are what a plan gets before an admin has ever touched it, and
+ * what the entitlement client falls back to when payment-service is down.
+ *
+ * Keep `free` conservative for exactly that reason: an outage degrades paying
+ * users to these numbers, and the alternative (fail-open) gives the product
+ * away for the length of the outage.
+ */
+exports.DEFAULT_PLAN_LIMITS = {
+    free: {
+        meters: { storageBytes: 1 * GB, aiJobs: 25, trackedTickers: 3, seats: 1 },
+        features: { cleanExport: false },
+        retentionDays: 90
+    },
+    personal: {
+        meters: { storageBytes: 50 * GB, aiJobs: 200, trackedTickers: 25, seats: 1 },
+        features: { cleanExport: true },
+        retentionDays: exports.UNLIMITED
+    },
+    family: {
+        meters: { storageBytes: 250 * GB, aiJobs: 600, trackedTickers: 100, seats: 5 },
+        features: { cleanExport: true },
+        retentionDays: exports.UNLIMITED
+    },
+    /**
+     * Everything unlimited, for the maintainers and for comped friends. Held as a
+     * real plan with a real subscription rather than an exemption branch in the
+     * code, so the people running the product go through the identical
+     * enforcement path as a paying customer — an `if (isStaff) skipEverything`
+     * flag would mean the paywall is never exercised by anyone who could notice
+     * it was broken.
+     *
+     * Kept off the public catalog through `Plan.isPublic = false`.
+     */
+    staff: {
+        meters: { storageBytes: exports.UNLIMITED, aiJobs: exports.UNLIMITED, trackedTickers: exports.UNLIMITED, seats: exports.UNLIMITED },
+        features: { cleanExport: true },
+        retentionDays: exports.UNLIMITED
+    }
+};
+/** Plan code the seeded staff/comp plan uses. */
+exports.STAFF_PLAN = 'staff';
+exports.FALLBACK_PLAN = 'free';
+/**
+ * Code defaults for a plan code, with unknown codes resolving to free.
+ *
+ * That fallback is deliberate: a typo'd or newly-added plan code must never
+ * silently grant unlimited. Callers that want the admin-configured numbers
+ * read them from the Plan document and pass them through `normalizeLimits`;
+ * this function is the floor underneath that.
+ */
+function resolveLimits(planCode) {
+    const limits = exports.DEFAULT_PLAN_LIMITS[planCode ?? exports.FALLBACK_PLAN] ?? exports.DEFAULT_PLAN_LIMITS[exports.FALLBACK_PLAN];
+    return cloneLimits(limits);
+}
+function cloneLimits(limits) {
+    return {
+        meters: { ...limits.meters },
+        features: { ...limits.features },
+        retentionDays: limits.retentionDays
+    };
+}
+function normalizeCeiling(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    // Anything negative means "unlimited"; nothing else is a meaningful ceiling.
+    if (value < 0)
+        return exports.UNLIMITED;
+    return Math.floor(value);
+}
+/**
+ * Layers a partial set of limits over a complete one.
+ *
+ * Entitlements resolve through three layers, each one partial and each one
+ * overriding the last: code defaults → the Plan document's `limits` → a
+ * per-user `EntitlementOverride`. This is the single step all three share.
+ *
+ * - unknown meter/feature keys are dropped — no store can invent enforcement;
+ * - missing keys keep the base value, so adding a new meter in code works
+ *   everywhere before any stored document mentions it;
+ * - negative numbers normalize to `UNLIMITED`, fractions floor.
+ */
+function applyLimits(base, input) {
+    const result = cloneLimits(base);
+    if (!input)
+        return result;
+    for (const key of exports.METER_KEYS) {
+        result.meters[key] = normalizeCeiling(input.meters?.[key], result.meters[key]);
+    }
+    for (const key of exports.FEATURE_KEYS) {
+        const value = input.features?.[key];
+        result.features[key] = typeof value === 'boolean' ? value : result.features[key];
+    }
+    result.retentionDays = normalizeCeiling(input.retentionDays, result.retentionDays);
+    return result;
+}
+/**
+ * Turns whatever is stored on a Plan document (or arrived from an admin form)
+ * into a complete, valid `PlanLimits`, filling the gaps from that plan code's
+ * code defaults.
+ */
+function normalizeLimits(input, planCode) {
+    return applyLimits(resolveLimits(planCode), input);
+}
+/** True when `used + amount` fits under `limit`. `UNLIMITED` always fits. */
+function fitsWithin(limit, used, amount = 0) {
+    if (limit === exports.UNLIMITED || limit < 0)
+        return true;
+    return used + amount <= limit;
+}
+/**
+ * Everything an admin UI needs to render a limits editor without hardcoding a
+ * single meter name — new keys appear in the form as soon as they exist here.
+ */
+exports.ENTITLEMENT_CATALOG = {
+    unlimited: exports.UNLIMITED,
+    meters: exports.METER_DEFINITIONS,
+    features: exports.FEATURE_DEFINITIONS,
+    retentionDays: {
+        key: 'retentionDays',
+        label: 'History retention (days)',
+        unit: 'days',
+        description: 'How far back reads may reach. Gates relationship history and, through the price-history range, the portfolio planner.'
+    },
+    defaults: exports.DEFAULT_PLAN_LIMITS,
+    fallbackPlan: exports.FALLBACK_PLAN
+};
+//# sourceMappingURL=definitions.js.map

package/dist/entitlements/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/entitlements/definitions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AA8EH,kCAEC;AAED,gCAEC;AAED,oCAEC;AA0ED,sCAGC;AA6BD,kCAcC;AAOD,0CAEC;AAGD,gCAGC;AAjND,2FAA2F;AAC9E,QAAA,SAAS,GAAG,CAAC,CAAC,CAAC;AAiBf,QAAA,iBAAiB,GAA+B;IAC3D;QACE,GAAG,EAAE,cAAc;QACnB,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,KAAK;QACb,WAAW,EAAE,6DAA6D;KAC3E;IACD;QACE,GAAG,EAAE,QAAQ;QACb,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,OAAO;QACf,WAAW,EAAE,uEAAuE;KACrF;IACD;QACE,GAAG,EAAE,gBAAgB;QACrB,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,KAAK;QACb,WAAW,EAAE,iGAAiG;KAC/G;IACD;QACE,GAAG,EAAE,OAAO;QACZ,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,KAAK;QACb,WAAW,EAAE,sEAAsE;KACpF;CACO,CAAC;AAEE,QAAA,mBAAmB,GAAiC;IAC/D;QACE,GAAG,EAAE,aAAa;QAClB,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,4CAA4C;KAC1D;CACO,CAAC;AAEE,QAAA,UAAU,GAAwB,yBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACpE,QAAA,YAAY,GAA0B,2BAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAEvF,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CACtC,yBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CACb,CAAC;AAEnC,SAAgB,WAAW,CAAC,KAAe;IACzC,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;AACvC,CAAC;AAED,SAAgB,UAAU,CAAC,KAAa;IACtC,OAAQ,kBAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED,SAAgB,YAAY,CAAC,KAAa;IACxC,OAAQ,oBAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAiBD,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9B;;;;;;;;GAQG;AACU,QAAA,mBAAmB,GAAyC;IACvE,IAAI,EAAE;QACJ,MAAM,EAAE,EAAE,YAAY,EAAE,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;QACzE,QAAQ,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;QAChC,aAAa,EAAE,EAAE;KAClB;IACD,QAAQ,EAAE;QACR,MAAM,EAAE,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;QAC5E,QAAQ,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;QAC/B,aAAa,EAAE,iBAAS;KACzB;IACD,MAAM,EAAE;QACN,MAAM,EAAE,EAAE,YAAY,EAAE,GAAG,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE;QAC9E,QAAQ,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;QAC/B,aAAa,EAAE,iBAAS;KACzB;IACD;;;;;;;;;OASG;IACH,KAAK,EAAE;QACL,MAAM,EAAE,EAAE,YAAY,EAAE,iBAAS,EAAE,MAAM,EAAE,iBAAS,EAAE,cAAc,EAAE,iBAAS,EAAE,KAAK,EAAE,iBAAS,EAAE;QACnG,QAAQ,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;QAC/B,aAAa,EAAE,iBAAS;KACzB;CACF,CAAC;AAEF,iDAAiD;AACpC,QAAA,UAAU,GAAG,OAAO,CAAC;AAErB,QAAA,aAAa,GAAG,MAAM,CAAC;AAEpC;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,QAAiB;IAC7C,MAAM,MAAM,GAAG,2BAAmB,CAAC,QAAQ,IAAI,qBAAa,CAAC,IAAI,2BAAmB,CAAC,qBAAa,CAAC,CAAC;IACpG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,WAAW,CAAC,MAAkB;IACrC,OAAO;QACL,MAAM,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE;QAC5B,QAAQ,EAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE;QAChC,aAAa,EAAE,MAAM,CAAC,aAAa;KACpC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc,EAAE,QAAgB;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1E,6EAA6E;IAC7E,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,iBAAS,CAAC;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,WAAW,CAAC,IAAgB,EAAE,KAAgC;IAC5E,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAE1B,KAAK,MAAM,GAAG,IAAI,kBAAU,EAAE,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,oBAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,CAAC,aAAa,GAAG,gBAAgB,CAAC,KAAK,CAAC,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IAEnF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAAC,KAAgC,EAAE,QAAiB;IACjF,OAAO,WAAW,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC;AAED,6EAA6E;AAC7E,SAAgB,UAAU,CAAC,KAAa,EAAE,IAAY,EAAE,MAAM,GAAG,CAAC;IAChE,IAAI,KAAK,KAAK,iBAAS,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,OAAO,IAAI,GAAG,MAAM,IAAI,KAAK,CAAC;AAChC,CAAC;AAED;;;GAGG;AACU,QAAA,mBAAmB,GAAG;IACjC,SAAS,EAAE,iBAAS;IACpB,MAAM,EAAE,yBAAiB;IACzB,QAAQ,EAAE,2BAAmB;IAC7B,aAAa,EAAE;QACb,GAAG,EAAE,eAAwB;QAC7B,KAAK,EAAE,0BAA0B;QACjC,IAAI,EAAE,MAAe;QACrB,WAAW,EACT,uHAAuH;KAC1H;IACD,QAAQ,EAAE,2BAAmB;IAC7B,YAAY,EAAE,qBAAa;CAC5B,CAAC"}

package/dist/entitlements/index.d.ts

@@ -0,0 +1,12 @@
+export { UNLIMITED, FALLBACK_PLAN, STAFF_PLAN, applyLimits, METER_KEYS, FEATURE_KEYS, METER_DEFINITIONS, FEATURE_DEFINITIONS, DEFAULT_PLAN_LIMITS, ENTITLEMENT_CATALOG, resolveLimits, normalizeLimits, meterPeriod, isMeterKey, isFeatureKey, fitsWithin } from './definitions';
+export type { MeterKey, FeatureKey, MeterPeriod, MeterDefinition, FeatureDefinition, PlanLimits, PartialPlanLimits } from './definitions';
+export type { Entitlements, EntitlementsMode } from './types';
+export { getEntitlementsMode, resetEntitlementsModeWarning } from './mode';
+export { UsageMeter, currentPeriod } from './UsageMeter';
+export type { IUsageMeter } from './UsageMeter';
+export { getUsage, getUsageSnapshot, checkQuota, consumeQuota, releaseQuota, setUsage } from './usage';
+export type { QuotaRequest } from './usage';
+export { getEntitlements, invalidateEntitlements, clearEntitlementsCache } from './client';
+export { loadEntitlements, requireEntitlement, requireQuota, retentionFloor } from './middleware';
+export type { EntitlementOptions, QuotaOptions, SubjectResolver } from './middleware';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,UAAU,EACX,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,4BAA4B,EAAE,MAAM,QAAQ,CAAC;AAE3E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACvG,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAE3F,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAClG,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

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"}