@stigg/cache-runtime 2.0.0

package/dist/types/transport.d.ts

@@ -0,0 +1,152 @@
+import { TransportErrorClassifier } from './errors';
+import { EntitlementEvaluation } from '@stigg/entitlements-runtime';
+import { AccessDeniedReason, CachedEntitlement, EntitlementQuery, EntitlementType, EntitlementsStateAccessDeniedReason, Maybe, UsageUpdateBehavior } from '@stigg/cache-core';
+/**
+ * Structural stand-in for an observable. Declared here rather than imported so the
+ * package stays off `@apollo/client` — the workspace resolves two incompatible copies
+ * of it (js-client-sdk on 3.4.x, node-server-sdk on 3.14.x), and a port that names
+ * either one only fits one caller.
+ */
+export interface TransportSubscription {
+    unsubscribe(): void;
+}
+export interface TransportObservable<TValue> {
+    subscribe(onNext: (value: TValue) => void, onError: (error: any) => void): TransportSubscription;
+}
+/** The cache state a transport hands back, already unwrapped from its wire format. */
+export type EntitlementsState<Input> = {
+    entitlements: Input[];
+    accessDeniedReason: Maybe<EntitlementsStateAccessDeniedReason>;
+};
+/**
+ * Minimum an entitlement must expose for the read policy to reconcile freshness.
+ * Anything richer is the CacheMapper's business, not the policy's.
+ */
+export type CacheableInput = {
+    entitlementUpdatedAt?: string | null;
+};
+export type DimensionValue = string | number | boolean;
+/**
+ * Write inputs. Flat scalars plus one cache-owned enum, so the SDKs' published DTOs
+ * satisfy them as-is — an API enum member is implicitly assignable to the literal
+ * union, so nothing converts on the way in.
+ */
+export type UsageMeasurementInput = {
+    customerId: string;
+    resourceId?: string;
+    featureId: string;
+    value: number;
+    updateBehavior?: UsageUpdateBehavior;
+    createdAt?: Date;
+    dimensions?: Record<string, DimensionValue>;
+    idempotencyKey?: string;
+};
+export type UsageMeasurementBulkInput = {
+    usages: UsageMeasurementInput[];
+};
+/** Flat scalars, so both hosts' published event DTOs satisfy it as-is. */
+export type UsageEventInput = {
+    eventName: string;
+    customerId: string;
+    idempotencyKey: string;
+    resourceId?: string;
+    dimensions?: Record<string, DimensionValue>;
+    timestamp?: Date;
+};
+export type CreditConsumptionInput = {
+    customerId: string;
+    currencyId: string;
+    amount: number;
+    idempotencyKey: string;
+    resourceId?: string;
+    createdAt?: Date;
+    dimensions?: Record<string, DimensionValue>;
+};
+/** Write-through payloads. Flat scalars, so a transport's own DTOs satisfy them as-is. */
+export type UsageMeasurementResult = {
+    id: string;
+    featureId: string;
+    customerId: string;
+    resourceId?: string | null;
+    currentUsage?: number | null;
+    usagePeriodStart?: string | number | null;
+    usagePeriodEnd?: string | number | null;
+    timestamp: string | number;
+    credit?: (CreditBalanceResult & {
+        consumed: number;
+    }) | null;
+};
+export type CreditBalanceResult = {
+    currencyId: string;
+    currentUsage: number;
+    usagePeriodEnd?: string | number | null;
+    timestamp: string | number;
+};
+export type CreditConsumptionResult = {
+    customerId: string;
+    currencyId: string;
+    resourceId?: string | null;
+    amount: number;
+    timestamp: string | number;
+    credit?: (CreditBalanceResult & {
+        usageLimit: number;
+    }) | null;
+};
+/** The bulk read's answer: one evaluation per entitlement, plus the customer-level reason. */
+export type CustomerEntitlementsEvaluation = {
+    entitlements: EntitlementEvaluation[];
+    accessDeniedReason: AccessDeniedReason | null;
+};
+/** Real-time events, in cache vocabulary. */
+export type EntitlementsUpdatedEvent<Input> = EntitlementsState<Input> & {
+    customerId: string;
+    resourceId?: string | null;
+};
+export type UsageUpdatedEvent = {
+    customerId: string;
+    resourceId?: string | null;
+    entitlementReference: EntitlementQuery;
+    usage: {
+        currentUsage: number;
+        usagePeriodStart: number | null;
+        usagePeriodEnd: number | null;
+        usageUpdatedAt?: number | null;
+    };
+};
+/**
+ * `affectsAllCustomers` is the only thing the read policy needs; `payload` is carried
+ * through untouched for the host's public event, which stays transport-shaped.
+ */
+export type PackagePublishedEvent<TPayload> = {
+    affectsAllCustomers: boolean;
+    payload: TPayload;
+};
+/**
+ * What the read policy needs from a transport. Every member is in cache vocabulary —
+ * the wire format, its error envelope and its mapping are the transport's business.
+ */
+export interface EntitlementsTransport<Input, TPackagePublished = unknown> {
+    /** Classification is transport-specific knowledge, so the transport carries it. */
+    readonly classifier: TransportErrorClassifier;
+    /** Round-trips a cheap authenticated endpoint so a rejected key surfaces at startup, not on the first read. */
+    validateApiKey(): Promise<void>;
+    getEntitlementsState(customerId: string, resourceId: string | undefined, skipEdge?: boolean, timeout?: number): Promise<EntitlementsState<Input>>;
+    reportUsage(input: UsageMeasurementInput): Promise<UsageMeasurementResult>;
+    reportUsageBulk(input: UsageMeasurementBulkInput): Promise<UsageMeasurementResult[]>;
+    consumeCredits(input: CreditConsumptionInput): Promise<CreditConsumptionResult>;
+    reportEvent(events: UsageEventInput[]): Promise<unknown>;
+    consumeCreditsAsync(consumptions: CreditConsumptionInput[]): Promise<unknown>;
+    subscribeEntitlementsUpdated(): TransportObservable<EntitlementsUpdatedEvent<Input>>;
+    subscribeUsageUpdated(): TransportObservable<UsageUpdatedEvent>;
+    subscribePackagePublished(): TransportObservable<PackagePublishedEvent<TPackagePublished>>;
+}
+/**
+ * How the read policy reports real-time updates to its host. The policy owns the cache
+ * handling — purge rules, timestamps, writes — and leaves public event payloads to the
+ * host, which is the only layer that knows their published shape.
+ */
+export interface EntitlementsRuntimeHooks<Input, TPackagePublished = unknown> {
+    onEntitlementsUpdated(event: EntitlementsUpdatedEvent<Input>): void;
+    onUsageUpdated(customerId: string, resourceId: Maybe<string>, entitlement: CachedEntitlement<EntitlementType.Feature>): void;
+    onPackagePublished(payload: TPackagePublished): void;
+}

package/dist/types/transport.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhbnNwb3J0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3R5cGVzL3RyYW5zcG9ydC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist/utils/entitlementQuery.d.ts

@@ -0,0 +1,10 @@
+import { EntitlementQuery } from '@stigg/cache-core';
+/**
+ * Resolve the unified feature-or-credit read params into a query. Exactly one of the two ids must
+ * be given; anything else is ambiguous and yields `undefined` for the caller to answer with a
+ * fallback.
+ */
+export declare function toEntitlementQuery(params: {
+    featureId?: string;
+    currencyId?: string;
+}): EntitlementQuery | undefined;

package/dist/utils/entitlementQuery.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEntitlementQuery = toEntitlementQuery;
+const cache_core_1 = require("@stigg/cache-core");
+/**
+ * Resolve the unified feature-or-credit read params into a query. Exactly one of the two ids must
+ * be given; anything else is ambiguous and yields `undefined` for the caller to answer with a
+ * fallback.
+ */
+function toEntitlementQuery(params) {
+    const hasFeature = params.featureId != null && params.featureId !== '';
+    const hasCredit = params.currencyId != null && params.currencyId !== '';
+    if (hasFeature === hasCredit) {
+        return undefined;
+    }
+    // After guards, exactly one is true
+    if (hasFeature) {
+        return { type: cache_core_1.EntitlementType.Feature, id: params.featureId };
+    }
+    return { type: cache_core_1.EntitlementType.Credit, id: params.currencyId };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW50aXRsZW1lbnRRdWVyeS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlscy9lbnRpdGxlbWVudFF1ZXJ5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBT0EsZ0RBYUM7QUFwQkQsa0RBQXNFO0FBRXRFOzs7O0dBSUc7QUFDSCxTQUFnQixrQkFBa0IsQ0FBQyxNQUFtRDtJQUNwRixNQUFNLFVBQVUsR0FBRyxNQUFNLENBQUMsU0FBUyxJQUFJLElBQUksSUFBSSxNQUFNLENBQUMsU0FBUyxLQUFLLEVBQUUsQ0FBQztJQUN2RSxNQUFNLFNBQVMsR0FBRyxNQUFNLENBQUMsVUFBVSxJQUFJLElBQUksSUFBSSxNQUFNLENBQUMsVUFBVSxLQUFLLEVBQUUsQ0FBQztJQUV4RSxJQUFJLFVBQVUsS0FBSyxTQUFTLEVBQUUsQ0FBQztRQUM3QixPQUFPLFNBQVMsQ0FBQztJQUNuQixDQUFDO0lBRUQsb0NBQW9DO0lBQ3BDLElBQUksVUFBVSxFQUFFLENBQUM7UUFDZixPQUFPLEVBQUUsSUFBSSxFQUFFLDRCQUFlLENBQUMsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLENBQUMsU0FBVSxFQUFFLENBQUM7SUFDbEUsQ0FBQztJQUNELE9BQU8sRUFBRSxJQUFJLEVBQUUsNEJBQWUsQ0FBQyxNQUFNLEVBQUUsRUFBRSxFQUFFLE1BQU0sQ0FBQyxVQUFXLEVBQUUsQ0FBQztBQUNsRSxDQUFDIn0=

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@stigg/cache-runtime",
+  "version": "2.0.0",
+  "description": "Transport-agnostic read policy for Stigg's client-side cache",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.js",
+    "typings": "dist/index.d.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stiggio/stigg-sdk.git",
+    "directory": "packages/cache-runtime"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "yarn run -T tsc -p tsconfig.build.json",
+    "lint": "yarn run -T eslint \"src/**/*.ts\"",
+    "test": "yarn run -T jest --forceExit --passWithNoTests"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "dependencies": {
+    "lodash": "^4.18.1",
+    "lru-cache": "^10.0.1",
+    "nanoid": "^3.3.8"
+  },
+  "peerDependencies": {
+    "@stigg/cache-core": "1.27.0",
+    "@stigg/cache-redis-store": "1.28.0",
+    "@stigg/entitlements-runtime": "2.0.0"
+  }
+}