@i4e/invest4edu-access-core 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {

package/src/entitlement-store.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Type declarations for the entitlement store.
+ *
+ * The package is plain JavaScript with JSDoc, which is fine for the Node services. NFD AI is
+ * TypeScript, and without declarations every call through this module widens to `any` — which
+ * silently removes the type checking from the one place in the codebase that decides whether a
+ * customer is over quota. Declaring it here rather than in the consumer keeps one definition:
+ * a copy in each TypeScript service would be a second description of this contract, free to drift
+ * from the implementation without anything failing.
+ */
+
+export interface EntitlementResult {
+  /** False only on a deliberate refusal — never on an infrastructure failure. */
+  allowed: boolean;
+  unlocked: boolean;
+  /** True when this feature is counted; consume() is a no-op otherwise. */
+  metered: boolean;
+  quota: number | null;
+  used: number;
+  remaining: number | null;
+  overage_policy: string;
+  reason?: string;
+  period?: string | null;
+  subject_key?: string | null;
+  /** Carried so consume() counts against the exact bucket that was just checked. */
+  carriedSubscriptionId?: unknown;
+  carriedPeriodStart?: Date | string | null;
+  carriedIdentity?: { accountId?: string | null; userId?: string | null };
+  carriedRow?: Record<string, unknown> | null;
+}
+
+export interface ConsumeResult {
+  consumed: boolean;
+  /** "not_metered" | "quota_exceeded" | "error" */
+  reason?: string;
+}
+
+export interface EntitlementStore {
+  findSubscription(args: {
+    subjectType: string;
+    subjectId: string;
+  }): Promise<Record<string, unknown> | null>;
+
+  entitlementFor(args: {
+    subjectType: string;
+    subjectId: string;
+    featureCode: string;
+    feature?: Record<string, unknown>;
+    identity?: { accountId?: string | null; userId?: string | null };
+    bypass?: boolean;
+    now?: Date;
+  }): Promise<EntitlementResult>;
+
+  consume(args: {
+    entitlement?: EntitlementResult;
+    featureCode: string;
+    n?: number;
+    now?: Date;
+    subscriptionId?: unknown;
+    row?: Record<string, unknown> | null;
+    identity?: { accountId?: string | null; userId?: string | null };
+    periodStart?: Date | string | null;
+  }): Promise<ConsumeResult>;
+
+  /** Idempotent; returns null when there is no default plan or the write failed. */
+  provisionDefault(args: {
+    subjectType: string;
+    subjectId: string;
+    accountId?: string | null;
+    now?: Date;
+  }): Promise<Record<string, unknown> | null>;
+}
+
+export function createEntitlementStore(opts: {
+  /** Returns a raw MongoDB `Db`, or null/undefined when the connection is not ready. */
+  getDb: () => unknown;
+  /** Cast an id the way the caller's driver expects. Defaults to pass-through. */
+  toObjectId?: (v: string) => unknown;
+  logger?: { warn: (msg: string) => void };
+}): EntitlementStore;
+
+declare const _default: { createEntitlementStore: typeof createEntitlementStore };
+export default _default;

package/src/subscription-lifecycle.js

@@ -29,7 +29,10 @@ export const LIVE_STATUSES = Object.freeze(["trialing", "active", "past_due"]);
 
 export const TRANSITIONS = Object.freeze({
   trialing: ["active", "cancelled", "expired"],
-  active: ["past_due", "blocked", "cancelled"],
+  // `expired` because a FIXED-TERM subscription that reaches its end has simply run out. Without
+  // it the only exits are `blocked`, which implies a deliberate cut-off, and `cancelled`, which
+  // implies the customer chose to leave — neither is true of a 90-day plan reaching day 91.
+  active: ["past_due", "blocked", "cancelled", "expired"],
   past_due: ["active", "blocked", "cancelled"],
   blocked: ["active", "cancelled"],
   cancelled: [],