@managemint-solutions/sdk 0.34.0 → 0.36.0

package/README.md

@@ -21,7 +21,8 @@ are peer dependencies — the request DTOs (`AddStatusDto`, `UpdateStatusDto`, `
 `ResetPasswordDto`, `CreateConfigDto`, `UpdateConfigDto`) ship with their class-validator
 decorators so consumers validate against
 the same rules the SDK's input types describe. `@nestjs/common` (^11) is an optional peer
-dependency, needed only for the `@managemint-solutions/sdk/nest` subpath.
+dependency, needed only for the `@managemint-solutions/sdk/nest` subpath, and `@upstash/redis`
+(^1.38) is an optional peer needed only for the `@managemint-solutions/sdk/cache` subpath.
 
 ## Usage
 
@@ -412,6 +413,44 @@ missing JWT is `401 Authentication Error`. Consumers return these as-is instead
 database errors themselves, and `error.code` keeps the raw Postgres code for the few callers
 that branch on one (the invoice-number retry on `23505`).
 
+## Cache
+
+```ts
+import { createCache, profileCacheKey } from '@managemint-solutions/sdk/cache';
+import { PROFILE_CACHE_TTL_SECONDS } from '@managemint-solutions/entities/users/cache';
+import { FEATURE_FLAGS_CACHE_KEY } from '@managemint-solutions/entities/feature-flags';
+
+const cache = createCache({ url: UPSTASH_REDIS_REST_URL, token: UPSTASH_REDIS_REST_TOKEN });
+
+// Profiles: one hash per organization, one field per member.
+await cache.setField(profileCacheKey(organizationId), mmsId, profile, PROFILE_CACHE_TTL_SECONDS);
+const hit = await cache.getField<LoggedInUser>(profileCacheKey(organizationId), mmsId); // null on a miss
+await cache.deleteField(profileCacheKey(organizationId), mmsId); // one member
+await cache.delete(profileCacheKey(organizationId));             // every member
+
+// Global values: plain strings with their own TTL.
+await cache.set(FEATURE_FLAGS_CACHE_KEY, flags, 86_400);
+const flags = await cache.get<FeatureFlags>(FEATURE_FLAGS_CACHE_KEY);
+```
+
+A small client on Upstash Redis (REST), shared by the portal, which reads and writes each
+member's own `GET /users/me` and reads the feature flags, and the api, which writes the flags
+and drops profile entries after a write. Two shapes, chosen so the data browser stays readable
+and nothing needs an index of its own: a **string** per global value, and a **hash per
+organization** for the profiles, so dropping a member is one field delete and dropping an
+organization is one key delete. `setField` is one pipeline (`HSET`, then `EXPIRE … NX`): the
+hash's TTL is set once, when it is first written, so an organization's whole cache re-reads
+once a day however busy it is. Every other call is one round trip. Values are JSON-serialised
+by the client; `get<T>` / `getField<T>` are the caller's promise about what was written, not a
+check.
+
+The client takes its URL and token as config — the SDK reads no environment variables — and
+retries once with a three-second timeout per request. It **throws** on a failed call: what a
+failure means is the caller's decision, and both callers today fail open (a miss on the portal,
+a Sentry report on the api). The key prefix and TTL for the profile hash live in
+`@managemint-solutions/entities/users/cache` and the flags key in `entities/feature-flags`;
+`profileCacheKey` here is the one builder both sides use.
+
 ## NestJS
 
 ```ts

package/dist/cache/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The Upstash Redis cache shared by the portal (which reads and writes profile entries and
+ * reads the feature flags) and the api (which writes the flags and deletes profile entries).
+ *
+ * Two shapes, chosen so the data browser stays readable and nothing needs an index of its own:
+ *
+ * - **A string per global value** - the feature flags - with its own TTL.
+ * - **A hash per organization** for the member profiles: one field per member, so dropping a
+ *   member is one field delete and dropping an organization is one key delete. The hash's
+ *   TTL is set once, when it is first written, so the whole organization re-reads once a day
+ *   however busy it is.
+ *
+ * Like every other client in the SDK it takes its configuration as an argument and reads no
+ * environment variables. It throws on a failed call; the callers decide what a failure means,
+ * and both of them fail open.
+ */
+export type CacheConfig = {
+    /** The database's REST URL, `https://<name>.upstash.io`. */
+    url: string;
+    /** The database's REST token. */
+    token: string;
+};
+/** The hash that holds an organization's cached member profiles. */
+export declare const profileCacheKey: (organizationId: string) => string;
+export declare class Cache {
+    private readonly redis;
+    constructor(config: CacheConfig);
+    /**
+     * The string under `key`, or null when there is none. The value is JSON-parsed by the
+     * client; `T` is the caller's promise about what was written, not a check.
+     */
+    get<T>(key: string): Promise<T | null>;
+    /** Writes `value` under `key` for `ttl` seconds. One round trip. */
+    set(key: string, value: unknown, ttl: number): Promise<void>;
+    /** Deletes `key` - a string or a whole hash. One round trip. */
+    delete(key: string): Promise<void>;
+    /** One field of the hash under `key`, or null when either is missing. */
+    getField<T>(key: string, field: string): Promise<T | null>;
+    /**
+     * Writes one field of the hash under `key`, and gives the hash `ttl` seconds to live if it
+     * has no expiry yet - a hash written to every day still dies once a day. One round trip.
+     */
+    setField(key: string, field: string, value: unknown, ttl: number): Promise<void>;
+    /** Deletes one field of the hash under `key`; a missing field or hash is a no-op. One round trip. */
+    deleteField(key: string, field: string): Promise<void>;
+}
+export declare const createCache: (config: CacheConfig) => Cache;

package/dist/cache/index.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCache = exports.Cache = exports.profileCacheKey = void 0;
+const redis_1 = require("@upstash/redis");
+const cache_1 = require("@managemint-solutions/entities/users/cache");
+/**
+ * How long one Upstash call may take before it is abandoned. Every call here sits on the
+ * request path - a portal boot on the read side, a profile write on the delete side - so a
+ * stalled Redis must cost the caller a bounded wait and nothing more.
+ */
+const REQUEST_TIMEOUT_MS = 3_000;
+/** One retry, briefly: the callers fail open, so patience only lengthens the miss. */
+const RETRY = { retries: 1, backoff: () => 200 };
+/** The hash that holds an organization's cached member profiles. */
+const profileCacheKey = (organizationId) => `${cache_1.PROFILE_CACHE_KEY_PREFIX}${organizationId}`;
+exports.profileCacheKey = profileCacheKey;
+class Cache {
+    redis;
+    constructor(config) {
+        this.redis = new redis_1.Redis({
+            url: config.url,
+            token: config.token,
+            retry: RETRY,
+            // A function, so each request gets a fresh signal; one shared signal would be dead for
+            // every call after the first timeout.
+            signal: () => AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    /**
+     * The string under `key`, or null when there is none. The value is JSON-parsed by the
+     * client; `T` is the caller's promise about what was written, not a check.
+     */
+    get(key) {
+        return this.redis.get(key);
+    }
+    /** Writes `value` under `key` for `ttl` seconds. One round trip. */
+    async set(key, value, ttl) {
+        await this.redis.set(key, value, { ex: ttl });
+    }
+    /** Deletes `key` - a string or a whole hash. One round trip. */
+    async delete(key) {
+        await this.redis.del(key);
+    }
+    /** One field of the hash under `key`, or null when either is missing. */
+    getField(key, field) {
+        return this.redis.hget(key, field);
+    }
+    /**
+     * Writes one field of the hash under `key`, and gives the hash `ttl` seconds to live if it
+     * has no expiry yet - a hash written to every day still dies once a day. One round trip.
+     */
+    async setField(key, field, value, ttl) {
+        await this.redis
+            .pipeline()
+            .hset(key, { [field]: value })
+            .expire(key, ttl, 'NX')
+            .exec();
+    }
+    /** Deletes one field of the hash under `key`; a missing field or hash is a no-op. One round trip. */
+    async deleteField(key, field) {
+        await this.redis.hdel(key, field);
+    }
+}
+exports.Cache = Cache;
+const createCache = (config) => new Cache(config);
+exports.createCache = createCache;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managemint-solutions/sdk",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Typed Supabase data-access SDK for ManageMint Solutions",
   "license": "UNLICENSED",
   "author": "Scott Bebington <scottbebington@gmail.com>",
@@ -20,6 +20,10 @@
     "./nest": {
       "types": "./dist/nest/index.d.ts",
       "default": "./dist/nest/index.js"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.ts",
+      "default": "./dist/cache/index.js"
     }
   },
   "files": [
@@ -47,11 +51,12 @@
     "testEnvironment": "node"
   },
   "dependencies": {
-    "@managemint-solutions/entities": "^1.17.0"
+    "@managemint-solutions/entities": "^1.20.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
     "@supabase/supabase-js": "^2.103.0",
+    "@upstash/redis": "^1.38.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.0",
     "reflect-metadata": "^0.2.0"
@@ -59,6 +64,9 @@
   "peerDependenciesMeta": {
     "@nestjs/common": {
       "optional": true
+    },
+    "@upstash/redis": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -67,6 +75,7 @@
     "@types/express": "^5.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.10.7",
+    "@upstash/redis": "^1.38.4",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",
     "jest": "^30.0.0",