@managemint-solutions/sdk 0.34.0 → 0.35.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,33 @@ 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 { createTaggedCache } from '@managemint-solutions/sdk/cache';
+import { userMeCacheKey, userCacheTag, USER_ME_CACHE_TTL_SECONDS } from '@managemint-solutions/entities/users/cache';
+
+const cache = createTaggedCache({ url: UPSTASH_REDIS_REST_URL, token: UPSTASH_REDIS_REST_TOKEN });
+
+await cache.set(userMeCacheKey(mmsId), profile, { ttl: USER_ME_CACHE_TTL_SECONDS, tags: [userCacheTag(mmsId)] });
+const hit = await cache.get<LoggedInUser>(userMeCacheKey(mmsId)); // null on a miss
+await cache.invalidateTag([userCacheTag(mmsId)]);
+```
+
+A tag-aware key-value cache on Upstash Redis (REST), shared by the portal, which reads and
+writes each member's own `GET /users/me`, and the api, which only expires it after a write.
+Redis has no tags, so each tag is a set of the keys written under it, stored as `tag:<tag>`
+and expiring with its newest member: `set` is one pipeline (`SET … EX ttl`, then `SADD` and
+`EXPIRE` per tag), `invalidateTag` is two round trips (`SMEMBERS` per tag, then one `DEL` of the
+members and the sets). Values are JSON-serialised by the client; `get<T>` is 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, tag and TTL contract for the profile entry lives in
+`@managemint-solutions/entities/users/cache`, so the tagging is one edit for both sides.
+
 ## NestJS
 
 ```ts

package/dist/cache/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A tag-aware key-value cache on Upstash Redis, shared by the portal (which reads and writes
+ * profile entries) and the api (which only expires them).
+ *
+ * Redis has no tags of its own, so each tag is a set of the keys written under it, stored as
+ * `tag:<tag>`. Expiring a tag deletes every key in the set and the set itself. The sets expire
+ * with the entries they hold, so an entry that simply ages out leaves nothing behind.
+ *
+ * Deliberately narrow: three calls and no knowledge of what is cached. The key, tag and TTL
+ * contract for the one thing cached today lives in `@managemint-solutions/entities/users/cache`.
+ *
+ * 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 TaggedCacheConfig = {
+    /** The database's REST URL, `https://<name>.upstash.io`. */
+    url: string;
+    /** The database's REST token. */
+    token: string;
+};
+export type TaggedCacheSetOptions = {
+    /** Seconds until the entry expires on its own. */
+    ttl: number;
+    /** The tags a later `invalidateTag` may drop the entry under. */
+    tags?: string[];
+};
+export declare class TaggedCache {
+    private readonly redis;
+    constructor(config: TaggedCacheConfig);
+    /**
+     * The entry 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, and files the key under each tag. One round trip. */
+    set(key: string, value: unknown, { ttl, tags }: TaggedCacheSetOptions): Promise<void>;
+    /** Deletes every entry filed under any of `tags`, and the tag sets themselves. Two round trips. */
+    invalidateTag(tags: string[]): Promise<void>;
+}
+export declare const createTaggedCache: (config: TaggedCacheConfig) => TaggedCache;

package/dist/cache/index.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaggedCache = exports.TaggedCache = void 0;
+const redis_1 = require("@upstash/redis");
+/**
+ * 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 expiry 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 };
+const tagSetKey = (tag) => `tag:${tag}`;
+class TaggedCache {
+    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 entry 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, and files the key under each tag. One round trip. */
+    async set(key, value, { ttl, tags = [] }) {
+        const pipeline = this.redis.pipeline().set(key, value, { ex: ttl });
+        for (const tag of tags) {
+            // The set lives at least as long as its newest member, so a member can never outlive
+            // the set that would be used to find it.
+            pipeline.sadd(tagSetKey(tag), key).expire(tagSetKey(tag), ttl);
+        }
+        await pipeline.exec();
+    }
+    /** Deletes every entry filed under any of `tags`, and the tag sets themselves. Two round trips. */
+    async invalidateTag(tags) {
+        if (tags.length === 0) {
+            return;
+        }
+        const sets = tags.map(tagSetKey);
+        const read = this.redis.pipeline();
+        for (const set of sets) {
+            read.smembers(set);
+        }
+        const members = (await read.exec()).flat();
+        await this.redis.del(...new Set([...members, ...sets]));
+    }
+}
+exports.TaggedCache = TaggedCache;
+const createTaggedCache = (config) => new TaggedCache(config);
+exports.createTaggedCache = createTaggedCache;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managemint-solutions/sdk",
-  "version": "0.34.0",
+  "version": "0.35.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": [
@@ -52,6 +56,7 @@
   "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",