@tumbaland/backend-core 1.22.0 → 1.24.0

package/src/entitlements/client.ts

@@ -0,0 +1,162 @@
+import logger from '../logging/logger';
+import { FALLBACK_PLAN, normalizeLimits, resolveLimits } from './definitions';
+import { Entitlements } from './types';
+
+/**
+ * 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;
+
+interface CacheEntry {
+  value: Entitlements;
+  expiresAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * 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<string, Promise<Entitlements>>();
+
+function cacheKey(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+function putInCache(key: string, value: Entitlements): void {
+  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: string): Entitlements {
+  return {
+    email,
+    planCode: FALLBACK_PLAN,
+    status: null,
+    limits: resolveLimits(FALLBACK_PLAN),
+    stale: true
+  };
+}
+
+interface EntitlementResponse {
+  success?: boolean;
+  planCode?: string;
+  status?: string | null;
+  limits?: Parameters<typeof normalizeLimits>[0];
+  upgradeTo?: string;
+}
+
+async function fetchEntitlements(email: string): Promise<Entitlements> {
+  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.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.error('Entitlement lookup failed', { email, status: response.status });
+      return fallbackEntitlements(email);
+    }
+
+    const body = (await response.json()) as EntitlementResponse;
+    const planCode = body.planCode || 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: normalizeLimits(body.limits, planCode),
+      upgradeTo: body.upgradeTo
+    };
+  } catch (err) {
+    logger.error('Entitlement lookup errored', { email, error: (err as Error)?.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.
+ */
+export async function getEntitlements(email: string): Promise<Entitlements> {
+  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.
+ */
+export function invalidateEntitlements(email: string): void {
+  cache.delete(cacheKey(email));
+}
+
+/** Empties the whole cache. Test seam, and a usable lever after a bulk plan edit. */
+export function clearEntitlementsCache(): void {
+  cache.clear();
+  inFlight.clear();
+}

package/src/entitlements/definitions.test.ts

@@ -0,0 +1,161 @@
+import {
+  DEFAULT_PLAN_LIMITS,
+  FALLBACK_PLAN,
+  FEATURE_KEYS,
+  METER_KEYS,
+  STAFF_PLAN,
+  UNLIMITED,
+  applyLimits,
+  fitsWithin,
+  isFeatureKey,
+  isMeterKey,
+  meterPeriod,
+  normalizeLimits,
+  resolveLimits
+} from './definitions';
+
+describe('resolveLimits', () => {
+  it('returns the defaults for a known plan code', () => {
+    expect(resolveLimits('personal')).toEqual(DEFAULT_PLAN_LIMITS.personal);
+  });
+
+  it('falls back to free for an unknown code, never to unlimited', () => {
+    expect(resolveLimits('enterprise-typo')).toEqual(DEFAULT_PLAN_LIMITS.free);
+    expect(resolveLimits(undefined)).toEqual(DEFAULT_PLAN_LIMITS[FALLBACK_PLAN]);
+  });
+
+  it('returns a copy, so a caller mutating limits cannot poison the defaults', () => {
+    const limits = resolveLimits('free');
+    limits.meters.storageBytes = 999;
+    limits.features.cleanExport = true;
+
+    expect(resolveLimits('free').meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
+    expect(resolveLimits('free').features.cleanExport).toBe(false);
+  });
+});
+
+describe('normalizeLimits', () => {
+  it('applies stored values over the plan defaults', () => {
+    const limits = normalizeLimits({ meters: { storageBytes: 123 }, retentionDays: 30 }, 'personal');
+
+    expect(limits.meters.storageBytes).toBe(123);
+    expect(limits.retentionDays).toBe(30);
+    // Untouched keys keep the plan's defaults rather than resetting to free.
+    expect(limits.meters.trackedTickers).toBe(DEFAULT_PLAN_LIMITS.personal.meters.trackedTickers);
+  });
+
+  it('drops keys that no code enforces', () => {
+    const limits = normalizeLimits(
+      { meters: { storageBytes: 5, wormholes: 1000 }, features: { cleanExport: true, teleport: true } },
+      'free'
+    );
+
+    expect(limits.meters).not.toHaveProperty('wormholes');
+    expect(limits.features).not.toHaveProperty('teleport');
+    expect(Object.keys(limits.meters).sort()).toEqual([...METER_KEYS].sort());
+  });
+
+  it('normalizes any negative ceiling to UNLIMITED and floors fractions', () => {
+    const limits = normalizeLimits({ meters: { aiJobs: -5, trackedTickers: 7.9 }, retentionDays: -2 }, 'free');
+
+    expect(limits.meters.aiJobs).toBe(UNLIMITED);
+    expect(limits.meters.trackedTickers).toBe(7);
+    expect(limits.retentionDays).toBe(UNLIMITED);
+  });
+
+  it('ignores non-numeric and non-boolean junk instead of producing NaN limits', () => {
+    const limits = normalizeLimits(
+      { meters: { seats: 'lots' as unknown as number }, features: { cleanExport: 'yes' as unknown as boolean } },
+      'family'
+    );
+
+    expect(limits.meters.seats).toBe(DEFAULT_PLAN_LIMITS.family.meters.seats);
+    expect(limits.features.cleanExport).toBe(true);
+  });
+
+  it('returns the plan defaults for an empty or missing payload', () => {
+    expect(normalizeLimits(undefined, 'family')).toEqual(DEFAULT_PLAN_LIMITS.family);
+    expect(normalizeLimits(null, 'family')).toEqual(DEFAULT_PLAN_LIMITS.family);
+    expect(normalizeLimits({}, 'family')).toEqual(DEFAULT_PLAN_LIMITS.family);
+  });
+
+  it('resolves an unknown plan code to free even when limits are stored', () => {
+    const limits = normalizeLimits({ meters: { seats: 3 } }, 'gold-tier-that-never-shipped');
+
+    expect(limits.meters.seats).toBe(3);
+    expect(limits.meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
+    expect(limits.features.cleanExport).toBe(false);
+  });
+});
+
+describe('applyLimits', () => {
+  it('layers a partial set over a complete one without mutating the base', () => {
+    const base = resolveLimits('free');
+
+    const layered = applyLimits(base, { meters: { storageBytes: 500 } });
+
+    expect(layered.meters.storageBytes).toBe(500);
+    expect(base.meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
+  });
+
+  it('stacks: defaults, then plan, then a per-user override', () => {
+    const planLimits = normalizeLimits({ meters: { storageBytes: 100, seats: 2 } }, 'free');
+
+    const withOverride = applyLimits(planLimits, { meters: { storageBytes: 5000 }, features: { cleanExport: true } });
+
+    expect(withOverride.meters.storageBytes).toBe(5000); // override wins
+    expect(withOverride.meters.seats).toBe(2); // plan wins where the override is silent
+    expect(withOverride.meters.aiJobs).toBe(DEFAULT_PLAN_LIMITS.free.meters.aiJobs); // default underneath both
+    expect(withOverride.features.cleanExport).toBe(true);
+  });
+});
+
+describe('the staff plan', () => {
+  it('grants every meter and feature without limit', () => {
+    const limits = resolveLimits(STAFF_PLAN);
+
+    for (const meter of METER_KEYS) {
+      expect(limits.meters[meter]).toBe(UNLIMITED);
+    }
+    expect(limits.retentionDays).toBe(UNLIMITED);
+    expect(limits.features.cleanExport).toBe(true);
+  });
+});
+
+describe('fitsWithin', () => {
+  it('treats UNLIMITED as always fitting', () => {
+    expect(fitsWithin(UNLIMITED, Number.MAX_SAFE_INTEGER, 1)).toBe(true);
+  });
+
+  it('allows landing exactly on the limit but not passing it', () => {
+    expect(fitsWithin(10, 9, 1)).toBe(true);
+    expect(fitsWithin(10, 10, 1)).toBe(false);
+  });
+});
+
+describe('key registry', () => {
+  it('recognizes only registered keys', () => {
+    expect(isMeterKey('storageBytes')).toBe(true);
+    expect(isMeterKey('storagebytes')).toBe(false);
+    expect(isFeatureKey('cleanExport')).toBe(true);
+    expect(isFeatureKey('planner')).toBe(false);
+  });
+
+  it('assigns every meter a period', () => {
+    expect(meterPeriod('aiJobs')).toBe('MONTH');
+    expect(meterPeriod('storageBytes')).toBe('ALL');
+  });
+
+  it('gives every registered plan a value for every registered key', () => {
+    for (const [code, limits] of Object.entries(DEFAULT_PLAN_LIMITS)) {
+      for (const meter of METER_KEYS) {
+        expect(typeof limits.meters[meter]).toBe(`number`);
+      }
+      for (const feature of FEATURE_KEYS) {
+        expect(typeof limits.features[feature]).toBe('boolean');
+      }
+      expect(typeof limits.retentionDays).toBe(`number`);
+      expect(code).toBeTruthy();
+    }
+  });
+});

package/src/entitlements/definitions.ts

@@ -0,0 +1,261 @@
+/**
+ * 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 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 const METER_DEFINITIONS: readonly MeterDefinition[] = [
+  {
+    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.'
+  }
+] as const;
+
+export const FEATURE_DEFINITIONS: readonly FeatureDefinition[] = [
+  {
+    key: 'cleanExport',
+    label: 'Clean export',
+    description: 'Exports and downloads without a watermark.'
+  }
+] as const;
+
+export const METER_KEYS: readonly MeterKey[] = METER_DEFINITIONS.map(m => m.key);
+export const FEATURE_KEYS: readonly FeatureKey[] = FEATURE_DEFINITIONS.map(f => f.key);
+
+const METER_PERIODS = Object.fromEntries(
+  METER_DEFINITIONS.map(m => [m.key, m.period])
+) as Record<MeterKey, MeterPeriod>;
+
+export function meterPeriod(meter: MeterKey): MeterPeriod {
+  return METER_PERIODS[meter] ?? 'ALL';
+}
+
+export function isMeterKey(value: string): value is MeterKey {
+  return (METER_KEYS as readonly string[]).includes(value);
+}
+
+export function isFeatureKey(value: string): value is FeatureKey {
+  return (FEATURE_KEYS as readonly string[]).includes(value);
+}
+
+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;
+}
+
+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.
+ */
+export const DEFAULT_PLAN_LIMITS: Readonly<Record<string, PlanLimits>> = {
+  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: UNLIMITED
+  },
+  family: {
+    meters: { storageBytes: 250 * GB, aiJobs: 600, trackedTickers: 100, seats: 5 },
+    features: { cleanExport: true },
+    retentionDays: 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: UNLIMITED, aiJobs: UNLIMITED, trackedTickers: UNLIMITED, seats: UNLIMITED },
+    features: { cleanExport: true },
+    retentionDays: UNLIMITED
+  }
+};
+
+/** Plan code the seeded staff/comp plan uses. */
+export const STAFF_PLAN = 'staff';
+
+export 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 function resolveLimits(planCode?: string): PlanLimits {
+  const limits = DEFAULT_PLAN_LIMITS[planCode ?? FALLBACK_PLAN] ?? DEFAULT_PLAN_LIMITS[FALLBACK_PLAN];
+  return cloneLimits(limits);
+}
+
+function cloneLimits(limits: PlanLimits): PlanLimits {
+  return {
+    meters: { ...limits.meters },
+    features: { ...limits.features },
+    retentionDays: limits.retentionDays
+  };
+}
+
+function normalizeCeiling(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  // Anything negative means "unlimited"; nothing else is a meaningful ceiling.
+  if (value < 0) return 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.
+ */
+export function applyLimits(base: PlanLimits, input?: PartialPlanLimits | null): PlanLimits {
+  const result = cloneLimits(base);
+  if (!input) return result;
+
+  for (const key of METER_KEYS) {
+    result.meters[key] = normalizeCeiling(input.meters?.[key], result.meters[key]);
+  }
+  for (const key of 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.
+ */
+export function normalizeLimits(input?: PartialPlanLimits | null, planCode?: string): PlanLimits {
+  return applyLimits(resolveLimits(planCode), input);
+}
+
+/** True when `used + amount` fits under `limit`. `UNLIMITED` always fits. */
+export function fitsWithin(limit: number, used: number, amount = 0): boolean {
+  if (limit === 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.
+ */
+export const ENTITLEMENT_CATALOG = {
+  unlimited: UNLIMITED,
+  meters: METER_DEFINITIONS,
+  features: FEATURE_DEFINITIONS,
+  retentionDays: {
+    key: 'retentionDays' as const,
+    label: 'History retention (days)',
+    unit: 'days' as const,
+    description:
+      'How far back reads may reach. Gates relationship history and, through the price-history range, the portfolio planner.'
+  },
+  defaults: DEFAULT_PLAN_LIMITS,
+  fallbackPlan: FALLBACK_PLAN
+};

package/src/entitlements/index.ts

@@ -0,0 +1,40 @@
+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';