@tumbaland/backend-core 1.23.0 → 1.25.0

package/dist/app/createBaseApp.d.ts

@@ -18,6 +18,12 @@ export interface CreateBaseAppOptions {
     tracing?: boolean;
     /** Use requestLoggerWithMetrics (adds Prometheus histograms) instead of the plain requestLogger. Default true. */
     metrics?: boolean;
+    /**
+     * Value for Express's `trust proxy`. Defaults to trusting private/loopback
+     * addresses — see the note on tumbaland-proxy below. Pass `false` for a
+     * service exposed directly to clients with no proxy in front of it.
+     */
+    trustProxy?: Parameters<Express['set']>[1];
 }
 /**
  * Assembles the middleware stack every service was hand-rolling in its own
@@ -39,6 +45,24 @@ export interface CreateBaseAppOptions {
  * Services with non-standard body parsing (a webhook needing the raw body,
  * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
  * false` and mount those themselves at the exact point they need to.
+ *
+ * `trust proxy` is on by default because nothing here is reached directly:
+ * every service sits behind tumbaland-proxy, which sets `X-Forwarded-For`.
+ * Left at Express's default (`false`) that header is ignored, which
+ * express-rate-limit reports as `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` — and
+ * it is right to: the limiter would then key every request in the cluster on
+ * the proxy's own container IP, so one busy client could exhaust the window
+ * for everyone.
+ *
+ * The value is `loopback, linklocal, uniquelocal` (private ranges) rather
+ * than a hop count, because the chain length differs per ingress path: a
+ * direct hit arrives as `client` + the proxy's own socket address, while
+ * traffic through the Cloudflare tunnel arrives as `client, 127.0.0.1` (the
+ * local cloudflared) + that same socket address. Express walks the chain
+ * right-to-left and stops at the first address it does not trust, so both
+ * paths land on the real client; a fixed number would be wrong for one of
+ * them. All the intermediaries are private addresses and the client is not,
+ * which is exactly the split this preset encodes.
  */
 export declare function createBaseApp(options?: CreateBaseAppOptions): Express;
 //# sourceMappingURL=createBaseApp.d.ts.map

package/dist/app/createBaseApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createBaseApp.d.ts","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK3D,OAAO,EAAwB,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAI3F,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,cAAc,GAAG,KAAK,CAAC;IACrC,4IAA4I;IAC5I,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kHAAkH;IAClH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAwBzE"}
+{"version":3,"file":"createBaseApp.d.ts","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK3D,OAAO,EAAwB,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAI3F,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,cAAc,GAAG,KAAK,CAAC;IACrC,4IAA4I;IAC5I,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kHAAkH;IAClH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CA2BzE"}

package/dist/app/createBaseApp.js

@@ -32,10 +32,29 @@ const healthController_1 = require("../health/healthController");
  * Services with non-standard body parsing (a webhook needing the raw body,
  * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
  * false` and mount those themselves at the exact point they need to.
+ *
+ * `trust proxy` is on by default because nothing here is reached directly:
+ * every service sits behind tumbaland-proxy, which sets `X-Forwarded-For`.
+ * Left at Express's default (`false`) that header is ignored, which
+ * express-rate-limit reports as `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` — and
+ * it is right to: the limiter would then key every request in the cluster on
+ * the proxy's own container IP, so one busy client could exhaust the window
+ * for everyone.
+ *
+ * The value is `loopback, linklocal, uniquelocal` (private ranges) rather
+ * than a hop count, because the chain length differs per ingress path: a
+ * direct hit arrives as `client` + the proxy's own socket address, while
+ * traffic through the Cloudflare tunnel arrives as `client, 127.0.0.1` (the
+ * local cloudflared) + that same socket address. Express walks the chain
+ * right-to-left and stops at the first address it does not trust, so both
+ * paths land on the real client; a fixed number would be wrong for one of
+ * them. All the intermediaries are private addresses and the client is not,
+ * which is exactly the split this preset encodes.
  */
 function createBaseApp(options = {}) {
-    const { corsOptions, rateLimiter = security_1.standardRateLimiter, parseJson = true, parseCookies = true, tracing = true, metrics = true } = options;
+    const { corsOptions, rateLimiter = security_1.standardRateLimiter, parseJson = true, parseCookies = true, tracing = true, metrics = true, trustProxy = 'loopback, linklocal, uniquelocal' } = options;
     const app = (0, express_1.default)();
+    app.set('trust proxy', trustProxy);
     app.get('/health/live', healthController_1.healthLive);
     app.use(security_1.securityHeaders);
     if (rateLimiter)

package/dist/app/createBaseApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"createBaseApp.js","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":";;;;;AAkDA,sCAwBC;AA1ED,sDAA2D;AAC3D,kEAAyC;AACzC,sDAA6D;AAC7D,wCAA+C;AAC/C,+DAAsF;AACtF,iEAA2F;AAC3F,qDAA8E;AAC9E,iEAAwD;AAsBxD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,EACJ,WAAW,EACX,WAAW,GAAG,8BAAmB,EACjC,SAAS,GAAG,IAAI,EAChB,YAAY,GAAG,IAAI,EACnB,OAAO,GAAG,IAAI,EACd,OAAO,GAAG,IAAI,EACf,GAAG,OAAO,CAAC;IAEZ,MAAM,GAAG,GAAG,IAAA,iBAAO,GAAE,CAAC;IAEtB,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,6BAAU,CAAC,CAAC;IAEpC,GAAG,CAAC,GAAG,CAAC,0BAAe,CAAC,CAAC;IACzB,IAAI,WAAW;QAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,CAAC,mCAAqB,CAAC,CAAC;IAC/B,IAAI,OAAO;QAAE,GAAG,CAAC,GAAG,CAAC,2BAAiB,CAAC,CAAC;IACxC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,wCAAwB,CAAC,CAAC,CAAC,6BAAa,CAAC,CAAC;IAC5D,GAAG,CAAC,GAAG,CAAC,IAAA,qCAAoB,EAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,IAAI,YAAY;QAAE,GAAG,CAAC,GAAG,CAAC,IAAA,uBAAY,GAAE,CAAC,CAAC;IAC1C,IAAI,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,iBAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEvC,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"createBaseApp.js","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":";;;;;AA0EA,sCA2BC;AArGD,sDAA2D;AAC3D,kEAAyC;AACzC,sDAA6D;AAC7D,wCAA+C;AAC/C,+DAAsF;AACtF,iEAA2F;AAC3F,qDAA8E;AAC9E,iEAAwD;AA4BxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,EACJ,WAAW,EACX,WAAW,GAAG,8BAAmB,EACjC,SAAS,GAAG,IAAI,EAChB,YAAY,GAAG,IAAI,EACnB,OAAO,GAAG,IAAI,EACd,OAAO,GAAG,IAAI,EACd,UAAU,GAAG,kCAAkC,EAChD,GAAG,OAAO,CAAC;IAEZ,MAAM,GAAG,GAAG,IAAA,iBAAO,GAAE,CAAC;IAEtB,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IAEnC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,6BAAU,CAAC,CAAC;IAEpC,GAAG,CAAC,GAAG,CAAC,0BAAe,CAAC,CAAC;IACzB,IAAI,WAAW;QAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,CAAC,mCAAqB,CAAC,CAAC;IAC/B,IAAI,OAAO;QAAE,GAAG,CAAC,GAAG,CAAC,2BAAiB,CAAC,CAAC;IACxC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,wCAAwB,CAAC,CAAC,CAAC,6BAAa,CAAC,CAAC;IAC5D,GAAG,CAAC,GAAG,CAAC,IAAA,qCAAoB,EAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,IAAI,YAAY;QAAE,GAAG,CAAC,GAAG,CAAC,IAAA,uBAAY,GAAE,CAAC,CAAC;IAC1C,IAAI,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,iBAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEvC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/entitlements/UsageMeter.d.ts

@@ -0,0 +1,30 @@
+import { Document, Model } from 'mongoose';
+import { MeterKey } from './definitions';
+/**
+ * One counter per (subject, meter, period). Lives in the shared database, so
+ * album-service can write `storageBytes` while payment-service reads it back
+ * for the pricing page without another round trip.
+ *
+ * `subjectId` is whoever the usage is billed to — an email for personal
+ * meters, the group owner's email for pooled ones. It is deliberately not a
+ * user ObjectId: every service already has the email on the JWT, and none of
+ * them share a users collection.
+ */
+export interface IUsageMeter extends Document {
+    subjectId: string;
+    meter: MeterKey;
+    /** `ALL` for cumulative meters, `YYYY-MM` for monthly ones. */
+    period: string;
+    count: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Registered through `models` first: several services import this module into
+ * the same mongoose singleton during tests, and a second `model()` call with
+ * the same name throws `OverwriteModelError`.
+ */
+export declare const UsageMeter: Model<IUsageMeter>;
+/** The period bucket a meter counts into right now. Monthly meters roll over at 00:00 UTC on the 1st. */
+export declare function currentPeriod(meter: MeterKey, now?: Date): string;
+//# sourceMappingURL=UsageMeter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UsageMeter.d.ts","sourceRoot":"","sources":["../../src/entitlements/UsageMeter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,EAAE,QAAQ,EAA4B,MAAM,eAAe,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAcD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,WAAW,CACuD,CAAC;AAElG,yGAAyG;AACzG,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAI7E"}

package/dist/entitlements/UsageMeter.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageMeter = void 0;
+exports.currentPeriod = currentPeriod;
+const mongoose_1 = require("mongoose");
+const definitions_1 = require("./definitions");
+const UsageMeterSchema = new mongoose_1.Schema({
+    subjectId: { type: String, required: true, lowercase: true, trim: true },
+    meter: { type: String, required: true },
+    period: { type: String, required: true, default: 'ALL' },
+    count: { type: Number, required: true, default: 0 }
+}, { timestamps: true });
+UsageMeterSchema.index({ subjectId: 1, meter: 1, period: 1 }, { unique: true });
+/**
+ * Registered through `models` first: several services import this module into
+ * the same mongoose singleton during tests, and a second `model()` call with
+ * the same name throws `OverwriteModelError`.
+ */
+exports.UsageMeter = mongoose_1.models.UsageMeter || (0, mongoose_1.model)('UsageMeter', UsageMeterSchema);
+/** The period bucket a meter counts into right now. Monthly meters roll over at 00:00 UTC on the 1st. */
+function currentPeriod(meter, now = new Date()) {
+    const period = (0, definitions_1.meterPeriod)(meter);
+    if (period === 'ALL')
+        return 'ALL';
+    return now.toISOString().slice(0, 7); // YYYY-MM
+}
+//# sourceMappingURL=UsageMeter.js.map

package/dist/entitlements/UsageMeter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UsageMeter.js","sourceRoot":"","sources":["../../src/entitlements/UsageMeter.ts"],"names":[],"mappings":";;;AA4CA,sCAIC;AAhDD,uCAAkE;AAClE,+CAAmE;AAsBnE,MAAM,gBAAgB,GAAG,IAAI,iBAAM,CACjC;IACE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;IACxE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IACvC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;IACxD,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;CACpD,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,CACrB,CAAC;AAEF,gBAAgB,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAEhF;;;;GAIG;AACU,QAAA,UAAU,GACpB,iBAAM,CAAC,UAAiC,IAAI,IAAA,gBAAK,EAAc,YAAY,EAAE,gBAAgB,CAAC,CAAC;AAElG,yGAAyG;AACzG,SAAgB,aAAa,CAAC,KAAe,EAAE,MAAY,IAAI,IAAI,EAAE;IACnE,MAAM,MAAM,GAAgB,IAAA,yBAAW,EAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU;AAClD,CAAC"}

package/dist/entitlements/client.d.ts

@@ -0,0 +1,17 @@
+import { Entitlements } from './types';
+/**
+ * The user's current plan and limits, cached for {@link CACHE_TTL_MS}.
+ *
+ * Failures are never cached — a fallback result would otherwise pin a paying
+ * user to free limits for a full minute after the outage ended.
+ */
+export declare function getEntitlements(email: string): Promise<Entitlements>;
+/**
+ * Drop a user's cached entitlements. Call after anything that changes their
+ * plan (checkout completed, subscription canceled) to collapse the staleness
+ * window from 60s to zero for the user who is watching.
+ */
+export declare function invalidateEntitlements(email: string): void;
+/** Empties the whole cache. Test seam, and a usable lever after a bulk plan edit. */
+export declare function clearEntitlementsCache(): void;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/entitlements/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsHvC;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAoB1E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}

package/dist/entitlements/client.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEntitlements = getEntitlements;
+exports.invalidateEntitlements = invalidateEntitlements;
+exports.clearEntitlementsCache = clearEntitlementsCache;
+const logger_1 = __importDefault(require("../logging/logger"));
+const definitions_1 = require("./definitions");
+/**
+ * Entitlements are read over the internal-service channel, not carried on the
+ * JWT.
+ *
+ * The JWT is signed for 24h and no service outside auth-service checks
+ * `tokenVersion`, so a plan embedded in it would be stale in both directions:
+ * a user who upgrades waits up to a day for what they just paid for, and a user
+ * who cancels keeps paid features for up to a day. A 60-second cache in front
+ * of a live lookup bounds that to a minute, and the enforcement points are
+ * writes and dispatches — low frequency — so the network cost is negligible.
+ */
+const CACHE_TTL_MS = 60_000;
+/** Bounded so a service under enumeration can't grow the cache without limit. */
+const MAX_CACHE_ENTRIES = 5_000;
+const REQUEST_TIMEOUT_MS = 3_000;
+const cache = new Map();
+/**
+ * Concurrent callers for the same email share one request. Without this, a
+ * burst of uploads from one user on a cold cache fans out into one
+ * payment-service call each.
+ */
+const inFlight = new Map();
+function cacheKey(email) {
+    return email.trim().toLowerCase();
+}
+function putInCache(key, value) {
+    if (cache.size >= MAX_CACHE_ENTRIES) {
+        // Map iterates in insertion order, so the first key is the oldest write.
+        const oldest = cache.keys().next();
+        if (!oldest.done)
+            cache.delete(oldest.value);
+    }
+    cache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+/**
+ * Fail closed: an unreachable payment-service degrades everyone to free limits
+ * rather than handing the product out for the length of the outage. The blast
+ * radius is bounded by design — reads are never gated, only writes and
+ * dispatches — so the worst case is "cannot upload for a minute", not
+ * "cannot use the app".
+ */
+function fallbackEntitlements(email) {
+    return {
+        email,
+        planCode: definitions_1.FALLBACK_PLAN,
+        status: null,
+        limits: (0, definitions_1.resolveLimits)(definitions_1.FALLBACK_PLAN),
+        stale: true
+    };
+}
+async function fetchEntitlements(email) {
+    const baseUrl = process.env.PAYMENT_API_URL;
+    const token = process.env.INTERNAL_SERVICE_TOKEN;
+    const serviceId = process.env.SERVICE_NAME || 'unknown-service';
+    if (!baseUrl || !token) {
+        logger_1.default.error('Entitlement lookup not configured', {
+            hasPaymentApiUrl: Boolean(baseUrl),
+            hasInternalToken: Boolean(token)
+        });
+        return fallbackEntitlements(email);
+    }
+    try {
+        const response = await fetch(`${baseUrl}/internal/entitlements?email=${encodeURIComponent(email)}`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-internal-token': token,
+                'x-service-id': serviceId
+            },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        });
+        if (!response.ok) {
+            logger_1.default.error('Entitlement lookup failed', { email, status: response.status });
+            return fallbackEntitlements(email);
+        }
+        const body = (await response.json());
+        const planCode = body.planCode || definitions_1.FALLBACK_PLAN;
+        return {
+            email,
+            planCode,
+            status: body.status ?? null,
+            // Re-normalized on this side too: the payload crossed a network boundary
+            // and a partially-configured plan must not leave a meter undefined.
+            limits: (0, definitions_1.normalizeLimits)(body.limits, planCode),
+            upgradeTo: body.upgradeTo
+        };
+    }
+    catch (err) {
+        logger_1.default.error('Entitlement lookup errored', { email, error: err?.message });
+        return fallbackEntitlements(email);
+    }
+}
+/**
+ * The user's current plan and limits, cached for {@link CACHE_TTL_MS}.
+ *
+ * Failures are never cached — a fallback result would otherwise pin a paying
+ * user to free limits for a full minute after the outage ended.
+ */
+async function getEntitlements(email) {
+    const key = cacheKey(email);
+    const cached = cache.get(key);
+    if (cached && cached.expiresAt > Date.now())
+        return cached.value;
+    const pending = inFlight.get(key);
+    if (pending)
+        return pending;
+    const request = fetchEntitlements(key)
+        .then(value => {
+        if (!value.stale)
+            putInCache(key, value);
+        return value;
+    })
+        .finally(() => {
+        inFlight.delete(key);
+    });
+    inFlight.set(key, request);
+    return request;
+}
+/**
+ * Drop a user's cached entitlements. Call after anything that changes their
+ * plan (checkout completed, subscription canceled) to collapse the staleness
+ * window from 60s to zero for the user who is watching.
+ */
+function invalidateEntitlements(email) {
+    cache.delete(cacheKey(email));
+}
+/** Empties the whole cache. Test seam, and a usable lever after a bulk plan edit. */
+function clearEntitlementsCache() {
+    cache.clear();
+    inFlight.clear();
+}
+//# sourceMappingURL=client.js.map

package/dist/entitlements/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/entitlements/client.ts"],"names":[],"mappings":";;;;;AA8HA,0CAoBC;AAOD,wDAEC;AAGD,wDAGC;AAjKD,+DAAuC;AACvC,+CAA8E;AAG9E;;;;;;;;;;GAUG;AACH,MAAM,YAAY,GAAG,MAAM,CAAC;AAE5B,iFAAiF;AACjF,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAOjC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;AAE1D,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,UAAU,CAAC,GAAW,EAAE,KAAmB;IAClD,IAAI,KAAK,CAAC,IAAI,IAAI,iBAAiB,EAAE,CAAC;QACpC,yEAAyE;QACzE,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,MAAM,CAAC,IAAI;YAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,KAAa;IACzC,OAAO;QACL,KAAK;QACL,QAAQ,EAAE,2BAAa;QACvB,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,IAAA,2BAAa,EAAC,2BAAa,CAAC;QACpC,KAAK,EAAE,IAAI;KACZ,CAAC;AACJ,CAAC;AAUD,KAAK,UAAU,iBAAiB,CAAC,KAAa;IAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACjD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,iBAAiB,CAAC;IAEhE,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,gBAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE;YAChD,gBAAgB,EAAE,OAAO,CAAC,OAAO,CAAC;YAClC,gBAAgB,EAAE,OAAO,CAAC,KAAK,CAAC;SACjC,CAAC,CAAC;QACH,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,gCAAgC,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE;YAClG,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,kBAAkB,EAAE,KAAK;gBACzB,cAAc,EAAE,SAAS;aAC1B;YACD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,kBAAkB,CAAC;SAChD,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,gBAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YAC9E,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAwB,CAAC;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,2BAAa,CAAC;QAChD,OAAO;YACL,KAAK;YACL,QAAQ;YACR,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;YAC3B,yEAAyE;YACzE,oEAAoE;YACpE,MAAM,EAAE,IAAA,6BAAe,EAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC;YAC9C,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gBAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,KAAK,EAAG,GAAa,EAAE,OAAO,EAAE,CAAC,CAAC;QACtF,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,eAAe,CAAC,KAAa;IACjD,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE5B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC;IAEjE,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC;SACnC,IAAI,CAAC,KAAK,CAAC,EAAE;QACZ,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;SACD,OAAO,CAAC,GAAG,EAAE;QACZ,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;IAEL,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,KAAa;IAClD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,qFAAqF;AACrF,SAAgB,sBAAsB;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/entitlements/definitions.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+export type MeterKey = 'storageBytes' | 'aiJobs' | 'trackedTickers' | 'seats';
+/**
+ * Deliberately small. The portfolio planner is NOT a feature flag — it is gated
+ * by `retentionDays` via the price-history range, because the planner runs
+ * entirely client-side and a boolean flag would be bypassable from devtools.
+ */
+export type FeatureKey = 'cleanExport';
+/** `ALL` = counts up forever (storage, seats). `MONTH` = resets each calendar month (UTC). */
+export type MeterPeriod = 'ALL' | 'MONTH';
+/** Sentinel for "no ceiling". Chosen over `Infinity` because it survives JSON and BSON. */
+export declare const UNLIMITED = -1;
+export interface MeterDefinition {
+    key: MeterKey;
+    label: string;
+    /** Drives formatting in the admin form and in `<UsageMeter>`: bytes get humanized, counts don't. */
+    unit: 'bytes' | 'count';
+    period: MeterPeriod;
+    description: string;
+}
+export interface FeatureDefinition {
+    key: FeatureKey;
+    label: string;
+    description: string;
+}
+export declare const METER_DEFINITIONS: readonly MeterDefinition[];
+export declare const FEATURE_DEFINITIONS: readonly FeatureDefinition[];
+export declare const METER_KEYS: readonly MeterKey[];
+export declare const FEATURE_KEYS: readonly FeatureKey[];
+export declare function meterPeriod(meter: MeterKey): MeterPeriod;
+export declare function isMeterKey(value: string): value is MeterKey;
+export declare function isFeatureKey(value: string): value is FeatureKey;
+export interface PlanLimits {
+    /** `-1` (UNLIMITED) means no ceiling. */
+    meters: Record<MeterKey, number>;
+    features: Record<FeatureKey, boolean>;
+    /** How far back reads may reach. `-1` (UNLIMITED) means the full history. */
+    retentionDays: number;
+}
+/** What an admin form or an API caller may send: any subset, in any order. */
+export interface PartialPlanLimits {
+    meters?: Partial<Record<string, number>>;
+    features?: Partial<Record<string, boolean>>;
+    retentionDays?: number;
+}
+/**
+ * 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.
+ */
+export declare const DEFAULT_PLAN_LIMITS: Readonly<Record<string, PlanLimits>>;
+/** Plan code the seeded staff/comp plan uses. */
+export declare const STAFF_PLAN = "staff";
+export declare const 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.
+ */
+export declare function resolveLimits(planCode?: string): PlanLimits;
+/**
+ * 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.
+ */
+export declare function applyLimits(base: PlanLimits, input?: PartialPlanLimits | null): PlanLimits;
+/**
+ * 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.
+ */
+export declare function normalizeLimits(input?: PartialPlanLimits | null, planCode?: string): PlanLimits;
+/** True when `used + amount` fits under `limit`. `UNLIMITED` always fits. */
+export declare function fitsWithin(limit: number, used: number, amount?: number): boolean;
+/**
+ * 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.
+ */
+export declare const ENTITLEMENT_CATALOG: {
+    unlimited: number;
+    meters: readonly MeterDefinition[];
+    features: readonly FeatureDefinition[];
+    retentionDays: {
+        key: "retentionDays";
+        label: string;
+        unit: "days";
+        description: string;
+    };
+    defaults: Readonly<Record<string, PlanLimits>>;
+    fallbackPlan: string;
+};
+//# sourceMappingURL=definitions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/entitlements/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,QAAQ,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;AAE1C,2FAA2F;AAC3F,eAAO,MAAM,SAAS,KAAK,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EA6B9C,CAAC;AAEX,eAAO,MAAM,mBAAmB,EAAE,SAAS,iBAAiB,EAMlD,CAAC;AAEX,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAAsC,CAAC;AACjF,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAwC,CAAC;AAMvF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAExD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtC,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CA+BpE,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAG3D;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,GAAG,UAAU,CAc1F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAE/F;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAG3E;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;CAa/B,CAAC"}