@tumbaland/frontend-core 1.8.0 → 1.10.0

package/dist/entitlementsService.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The caller's own plan, limits and live meter readings.
+ *
+ * **The vocabulary is duplicated from `@tumbaland/backend-core`; the numbers
+ * never are.** A browser bundle cannot import backend-core — it pulls in
+ * mongoose — so the meter *keys* are restated here. That is a deliberate line:
+ * duplicating the key names costs a rename, while duplicating the limits would
+ * recreate exactly the defect Phase 0 removed, where `PlansPage` advertised six
+ * ceilings that no service enforced. Every number below arrives from the API at
+ * runtime, resolved by the same `normalizeLimits` the middleware enforces from.
+ */
+export type MeterKey = 'storageBytes' | 'aiJobs' | 'trackedTickers' | 'seats';
+export type FeatureKey = 'cleanExport';
+/** Matches `UNLIMITED` in backend-core. Chosen over `Infinity` because it survives JSON. */
+export declare const UNLIMITED = -1;
+export interface PlanLimits {
+    meters: Record<MeterKey, number>;
+    features: Record<FeatureKey, boolean>;
+    /** How far back reads may reach. `-1` means the full history. */
+    retentionDays: number;
+}
+export interface Entitlements {
+    email: string;
+    planCode: string;
+    /** Subscription status backing the plan; `null` on the implicit free plan. */
+    status: string | null;
+    limits: PlanLimits;
+    /** Cheapest active plan priced above the current one, for an upgrade CTA. */
+    upgradeTo?: string;
+    /** Granted by an admin rather than bought — render as "Complimentary". */
+    isComp?: boolean;
+    hasOverride?: boolean;
+    /** Live meter readings, same keys as `limits.meters`. */
+    usage: Record<MeterKey, number>;
+}
+export interface EntitlementsServiceConfig {
+    /** Read fresh at call time (config may not be resolved yet at module load). */
+    getPaymentApiUrl: () => string;
+    onUnauthorized?: () => void;
+}
+/**
+ * Builds a per-front entitlements service.
+ *
+ *   export const { getMyEntitlements } = createEntitlementsService({
+ *     getPaymentApiUrl: () => getGlobalConfig().PAYMENT_API_URL!
+ *   });
+ */
+export declare function createEntitlementsService(config: EntitlementsServiceConfig): {
+    getMyEntitlements(): Promise<Entitlements>;
+};
+export type EntitlementsService = ReturnType<typeof createEntitlementsService>;
+/** True when a meter has no ceiling. */
+export declare function isUnlimited(limit: number): boolean;
+/**
+ * Share of a meter consumed, 0–1, clamped. Unlimited meters report 0 — there is
+ * no ceiling to be a fraction of, and reporting 1 would paint them as full.
+ */
+export declare function usageRatio(used: number, limit: number): number;

package/dist/entitlementsService.js

@@ -0,0 +1,53 @@
+import { createApiClient } from './apiClient';
+/** Matches `UNLIMITED` in backend-core. Chosen over `Infinity` because it survives JSON. */
+export const UNLIMITED = -1;
+const ZERO_USAGE = {
+    storageBytes: 0,
+    aiJobs: 0,
+    trackedTickers: 0,
+    seats: 0
+};
+/**
+ * Builds a per-front entitlements service.
+ *
+ *   export const { getMyEntitlements } = createEntitlementsService({
+ *     getPaymentApiUrl: () => getGlobalConfig().PAYMENT_API_URL!
+ *   });
+ */
+export function createEntitlementsService(config) {
+    const client = createApiClient({
+        baseUrl: () => config.getPaymentApiUrl(),
+        onUnauthorized: config.onUnauthorized
+    });
+    return {
+        async getMyEntitlements() {
+            const body = await client.get('/api/subscriptions/me/entitlements');
+            // Reject rather than return a half-built object. Without `limits` there
+            // is no ceiling to meter against, and handing back a truthy
+            // `Entitlements` whose `limits` is undefined pushes the crash into every
+            // call site's property access instead of failing here, once.
+            if (!body?.limits?.meters) {
+                throw new Error('Entitlements response is missing limits');
+            }
+            return {
+                ...body,
+                // A meter with no counter yet is simply absent from the snapshot, which
+                // would otherwise render as `undefined of 1 GB`.
+                usage: { ...ZERO_USAGE, ...(body.usage ?? {}) }
+            };
+        }
+    };
+}
+/** True when a meter has no ceiling. */
+export function isUnlimited(limit) {
+    return limit === UNLIMITED || limit < 0;
+}
+/**
+ * Share of a meter consumed, 0–1, clamped. Unlimited meters report 0 — there is
+ * no ceiling to be a fraction of, and reporting 1 would paint them as full.
+ */
+export function usageRatio(used, limit) {
+    if (isUnlimited(limit) || limit === 0)
+        return 0;
+    return Math.min(1, Math.max(0, used / limit));
+}

package/dist/index.d.ts

@@ -4,6 +4,10 @@ export { createAuthService, createAppAuthService } from './authService';
 export type { AuthServiceConfig, AuthService, AppAuthConfig } from './authService';
 export { createGroupService } from './groupService';
 export type { GroupServiceConfig, GroupService } from './groupService';
+export { createEntitlementsService, isUnlimited, usageRatio, UNLIMITED } from './entitlementsService';
+export type { EntitlementsServiceConfig, EntitlementsService, Entitlements, PlanLimits, MeterKey, FeatureKey } from './entitlementsService';
+export { createPlansService } from './plansService';
+export type { CatalogPlan, PlansServiceConfig, PlansService } from './plansService';
 export type { User, AuthResponse, Group, ApiResponse } from './types';
 export { TENANT_STORAGE_KEY, clearSessionScopedStorage } from './sessionStorage';
 export { initMonitoring, captureException, captureMessage, setUser, setTag, startTransaction, recordMetric, initWebVitals, flushLogs, initConsoleInterception, generateCorrelationId, getCorrelationId, getSessionId, logger } from './monitoring';

package/dist/index.js

@@ -2,6 +2,8 @@
 export { createApiClient, ApiError } from './apiClient';
 export { createAuthService, createAppAuthService } from './authService';
 export { createGroupService } from './groupService';
+export { createEntitlementsService, isUnlimited, usageRatio, UNLIMITED } from './entitlementsService';
+export { createPlansService } from './plansService';
 export { TENANT_STORAGE_KEY, clearSessionScopedStorage } from './sessionStorage';
 // Monitoring: headless logging, error capture, correlation IDs, and web-vitals
 export { initMonitoring, captureException, captureMessage, setUser, setTag, startTransaction, recordMetric, initWebVitals, flushLogs, initConsoleInterception, generateCorrelationId, getCorrelationId, getSessionId, logger } from './monitoring';

package/dist/plansService.d.ts

@@ -0,0 +1,51 @@
+import { PlanLimits } from './entitlementsService';
+/**
+ * The public plan catalog, as the pricing page renders it.
+ *
+ * **The numbers are never duplicated here.** `effectiveLimits` arrives from the
+ * API already resolved by the same `normalizeLimits` the entitlement middleware
+ * enforces from, so the ceiling on the card and the ceiling that produces a 402
+ * are the same value read from the same place. A hardcoded pricing table is the
+ * exact defect Phase 0 removed — `PlansPage` advertised six limits no service
+ * enforced — and re-creating it at the moment money changes hands would attach
+ * a payment to the claim.
+ *
+ * What a front *may* own is copy: a plan's tagline and which card is
+ * highlighted are presentation, not entitlement.
+ */
+export interface CatalogPlan {
+    code: string;
+    name: string;
+    /** Admin-editable tagline. Absent on plans nobody has written copy for. */
+    description?: string;
+    /** Cents, so there is never a float in a price. */
+    priceMonthlyCents: number;
+    priceYearlyCents?: number;
+    /** Marketing bullets. Deliberately unused by the limit rows — see above. */
+    features?: string[];
+    isPublic?: boolean;
+    /** Whether the plan can be bought at all; a priced plan without one returns 503 at checkout. */
+    stripePriceId?: string;
+    /** Limits after code defaults fill whatever the plan document leaves unset. */
+    effectiveLimits: PlanLimits;
+}
+export interface PlansServiceConfig {
+    /** Read fresh at call time (config may not be resolved yet at module load). */
+    getPaymentApiUrl: () => string;
+}
+/**
+ * Builds a per-front plans service.
+ *
+ *   export const { getPlans } = createPlansService({
+ *     getPaymentApiUrl: () => getGlobalConfig().PAYMENT_API_URL!
+ *   });
+ *
+ * `GET /api/plans` is optionally authenticated: a signed-out visitor gets the
+ * public catalog, and a signed-in one additionally gets the hidden plan they
+ * are actually on. No `onUnauthorized` redirect, therefore — the landing page
+ * is reachable without an account and must stay that way.
+ */
+export declare function createPlansService(config: PlansServiceConfig): {
+    getPlans(): Promise<CatalogPlan[]>;
+};
+export type PlansService = ReturnType<typeof createPlansService>;

package/dist/plansService.js

@@ -0,0 +1,25 @@
+import { createApiClient } from './apiClient';
+/**
+ * Builds a per-front plans service.
+ *
+ *   export const { getPlans } = createPlansService({
+ *     getPaymentApiUrl: () => getGlobalConfig().PAYMENT_API_URL!
+ *   });
+ *
+ * `GET /api/plans` is optionally authenticated: a signed-out visitor gets the
+ * public catalog, and a signed-in one additionally gets the hidden plan they
+ * are actually on. No `onUnauthorized` redirect, therefore — the landing page
+ * is reachable without an account and must stay that way.
+ */
+export function createPlansService(config) {
+    const client = createApiClient({ baseUrl: () => config.getPaymentApiUrl() });
+    return {
+        async getPlans() {
+            const body = await client.get('/api/plans');
+            const plans = body?.plans ?? [];
+            // A plan without resolved limits cannot be rendered honestly — every line
+            // on its card is a limit — so drop it rather than draw a card with holes.
+            return plans.filter(plan => Boolean(plan?.effectiveLimits?.meters));
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/frontend-core",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Shared frontend auth/group/API-client logic for Tumbaland frontends",
   "author": "Tumbaland",
   "license": "MIT",