@newhomestar/sdk 0.8.0 → 0.8.1

package/dist/next.d.ts

@@ -124,8 +124,9 @@ export interface NovaFgaCheckDef {
      * Where to resolve object_id from in the request:
      *   'path'  → Next.js route params (e.g. params.id for /communities/:id)
      *   'query' → URL query string param
+     *   'body'  → JSON request body (for POST/PATCH endpoints where the id is in the body)
      */
-    object_id_from: 'path' | 'query';
+    object_id_from: 'path' | 'query' | 'body';
     /** The param name to extract object_id from (e.g. 'id', 'community_id') */
     object_id_param: string;
     /** Optional tenant_id param name for multi-tenant scoped checks */
@@ -789,6 +790,8 @@ export interface ServiceDef {
 export declare function defineService<T extends ServiceDef>(def: T): T & {
     readonly __novaService: true;
 };
+export { UserCache, userCache } from './userCache.js';
+export type { UserProfile, UserCacheOptions } from './userCache.js';
 /** @deprecated Use `buildPageResponse` instead */
 export declare function buildPaginatedResponse<T extends {
     id: string;

package/dist/next.js

@@ -375,6 +375,8 @@ export function defineService(def) {
     }
     return { ...def, __novaService: true };
 }
+// ─── User Cache (re-export from userCache.ts) ────────────────────────────────
+export { UserCache, userCache } from './userCache.js';
 // ─── Legacy re-exports (backward compat) ─────────────────────────────────────
 /** @deprecated Use `buildPageResponse` instead */
 export function buildPaginatedResponse(data, count, pageSize) {

package/dist/userCache.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Lightweight user profile shape returned by the Auth Service internal endpoints.
+ * Used for display purposes (resolving `created_by` UUIDs to names/emails/avatars).
+ */
+export interface UserProfile {
+    id: string;
+    email: string | null;
+    display_name: string | null;
+    first_name: string | null;
+    last_name: string | null;
+    avatar_url: string | null;
+    external_id: number | null;
+}
+export interface UserCacheOptions {
+    /** Auth Service base URL. Defaults to AUTH_ISSUER_BASE_URL env var. */
+    authServiceURL?: string;
+    /** Service-to-service JWT. Defaults to NOVA_SERVICE_TOKEN env var. */
+    serviceToken?: string;
+    /** Auto-refresh interval in milliseconds. Default: 300_000 (5 min). */
+    refreshIntervalMs?: number;
+    /** Enable verbose debug logging. Default: true when NODE_ENV !== 'production'. */
+    debug?: boolean;
+}
+export declare class UserCache {
+    /** UUID → UserProfile */
+    private byId;
+    /** external_id (INT) → UUID */
+    private byExternalId;
+    private readonly authServiceURL;
+    private readonly serviceToken;
+    private readonly refreshIntervalMs;
+    private readonly _debug;
+    private timer;
+    private _lastRefreshed;
+    constructor(options?: UserCacheOptions);
+    private log;
+    /**
+     * Fetch all user profiles from the Auth Service and start the auto-refresh timer.
+     * Call once during service startup (e.g., in instrumentation.ts).
+     */
+    start(): Promise<void>;
+    /** Stop the auto-refresh timer. Call during graceful shutdown. */
+    stop(): void;
+    /**
+     * Force an immediate full refresh from the Auth Service.
+     * Paginates through GET /api/internal/users/all until all pages are loaded,
+     * then atomically swaps the in-memory maps.
+     */
+    refresh(): Promise<void>;
+    /** Get a user profile by platform UUID. Returns undefined on cache miss. */
+    getUser(uuid: string): UserProfile | undefined;
+    /** Get a user profile by legacy external_id (INT). */
+    getUserByExternalId(extId: number): UserProfile | undefined;
+    /**
+     * Resolve multiple UUIDs at once. Returns a Map of found profiles.
+     *
+     * By default, cache misses trigger an HTTP fallback to
+     * POST /api/internal/users/resolve on the Auth Service, which backfills
+     * the in-memory cache. Set `fetchMissing: false` to skip the HTTP call.
+     */
+    resolveMany(uuids: string[], options?: {
+        fetchMissing?: boolean;
+    }): Promise<Map<string, UserProfile>>;
+    /** Check if a UUID exists in the cache. */
+    has(uuid: string): boolean;
+    /** Cache statistics for health checks and monitoring. */
+    get stats(): {
+        userCount: number;
+        externalIdCount: number;
+        lastRefreshed: Date | null;
+        isRunning: boolean;
+    };
+}
+export declare const userCache: UserCache;

package/dist/userCache.js

@@ -0,0 +1,210 @@
+// ── User Profile Cache ────────────────────────────────────────────────────────
+// In-memory cache of platform user profiles, loaded from the Auth Service.
+// Mirrors the IAMPermissionCache pattern — startup warm-up, periodic refresh,
+// and HTTP fallback for cache misses.
+//
+// Startup:  userCache.start()  (called from instrumentation.ts in consuming services)
+// Usage:    userCache.getUser(uuid)          → UserProfile | undefined
+//           userCache.getUserByExternalId(n) → UserProfile | undefined
+//           userCache.resolveMany(uuids)     → Map<uuid, UserProfile>
+//           userCache.stats                  → { userCount, lastRefreshed, isRunning }
+//
+// Reads:    GET  /api/internal/users/all      on AUTH_ISSUER_BASE_URL
+//           POST /api/internal/users/resolve  on AUTH_ISSUER_BASE_URL
+// Auth:     Bearer NOVA_SERVICE_TOKEN
+// Refresh:  Every USER_CACHE_REFRESH_MS (default: 5 minutes)
+//
+// See directory service .nova/user_service.md for full architecture docs.
+// ── Class ─────────────────────────────────────────────────────────────────────
+export class UserCache {
+    /** UUID → UserProfile */
+    byId = new Map();
+    /** external_id (INT) → UUID */
+    byExternalId = new Map();
+    authServiceURL;
+    serviceToken;
+    refreshIntervalMs;
+    _debug;
+    timer = null;
+    _lastRefreshed = null;
+    constructor(options = {}) {
+        this.authServiceURL = (options.authServiceURL ??
+            process.env.AUTH_ISSUER_BASE_URL ??
+            '').replace(/\/+$/, '');
+        this.serviceToken =
+            options.serviceToken ??
+                process.env.NOVA_SERVICE_TOKEN ??
+                '';
+        this.refreshIntervalMs =
+            options.refreshIntervalMs ??
+                parseInt(process.env.USER_CACHE_REFRESH_MS ?? '300000', 10);
+        this._debug = options.debug ?? (process.env.NODE_ENV !== 'production');
+    }
+    log(msg) {
+        if (this._debug)
+            console.log(`[UserCache] ${msg}`);
+    }
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+    /**
+     * Fetch all user profiles from the Auth Service and start the auto-refresh timer.
+     * Call once during service startup (e.g., in instrumentation.ts).
+     */
+    async start() {
+        if (!this.authServiceURL) {
+            this.log('⚠️  AUTH_ISSUER_BASE_URL not set — user cache disabled');
+            return;
+        }
+        if (!this.serviceToken) {
+            this.log('⚠️  NOVA_SERVICE_TOKEN not set — user cache disabled');
+            return;
+        }
+        this.log('🚀 Starting user cache...');
+        await this.refresh();
+        this.timer = setInterval(() => {
+            this.log('⏱  Auto-refresh triggered');
+            this.refresh().catch((err) => {
+                this.log(`⚠️  Auto-refresh failed: ${err.message}`);
+                console.error('[UserCache] ❌', err.message);
+            });
+        }, this.refreshIntervalMs);
+        // Allow the Node.js process to exit even if the timer is still pending
+        if (this.timer.unref)
+            this.timer.unref();
+        const nextMin = Math.round(this.refreshIntervalMs / 1000 / 60);
+        this.log(`✅ User cache started — ${this.byId.size} user(s) loaded, next refresh in ${nextMin}m`);
+    }
+    /** Stop the auto-refresh timer. Call during graceful shutdown. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.log('🛑 Auto-refresh stopped');
+        }
+    }
+    /**
+     * Force an immediate full refresh from the Auth Service.
+     * Paginates through GET /api/internal/users/all until all pages are loaded,
+     * then atomically swaps the in-memory maps.
+     */
+    async refresh() {
+        const newById = new Map();
+        const newByExtId = new Map();
+        const startMs = Date.now();
+        let page = 1;
+        // Paginate through all users
+        while (true) {
+            const url = `${this.authServiceURL}/api/internal/users/all?page=${page}&per_page=1000`;
+            this.log(`🔄 Fetching page ${page} from ${url}...`);
+            const res = await fetch(url, {
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.serviceToken}`,
+                },
+            });
+            if (!res.ok) {
+                const errMsg = `refresh() failed on page ${page}: ${res.status} ${res.statusText}`;
+                this.log(`❌ ${errMsg}`);
+                throw new Error(errMsg);
+            }
+            const json = (await res.json());
+            for (const user of json.users) {
+                newById.set(user.id, user);
+                if (user.external_id != null) {
+                    newByExtId.set(user.external_id, user.id);
+                }
+            }
+            if (json.next_page == null)
+                break;
+            page = json.next_page;
+        }
+        // Atomically swap the cache
+        this.byId = newById;
+        this.byExternalId = newByExtId;
+        this._lastRefreshed = new Date();
+        const elapsedMs = Date.now() - startMs;
+        this.log(`✅ Loaded ${newById.size} user(s), ${newByExtId.size} external ID mapping(s) in ${elapsedMs}ms`);
+    }
+    // ── Query Methods ─────────────────────────────────────────────────────────
+    /** Get a user profile by platform UUID. Returns undefined on cache miss. */
+    getUser(uuid) {
+        return this.byId.get(uuid);
+    }
+    /** Get a user profile by legacy external_id (INT). */
+    getUserByExternalId(extId) {
+        const uuid = this.byExternalId.get(extId);
+        return uuid ? this.byId.get(uuid) : undefined;
+    }
+    /**
+     * Resolve multiple UUIDs at once. Returns a Map of found profiles.
+     *
+     * By default, cache misses trigger an HTTP fallback to
+     * POST /api/internal/users/resolve on the Auth Service, which backfills
+     * the in-memory cache. Set `fetchMissing: false` to skip the HTTP call.
+     */
+    async resolveMany(uuids, options) {
+        const result = new Map();
+        const missing = [];
+        for (const uuid of uuids) {
+            const cached = this.byId.get(uuid);
+            if (cached) {
+                result.set(uuid, cached);
+            }
+            else {
+                missing.push(uuid);
+            }
+        }
+        // HTTP fallback for cache misses
+        const shouldFetch = missing.length > 0 &&
+            options?.fetchMissing !== false &&
+            this.authServiceURL &&
+            this.serviceToken;
+        if (shouldFetch) {
+            try {
+                const res = await fetch(`${this.authServiceURL}/api/internal/users/resolve`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.serviceToken}`,
+                    },
+                    body: JSON.stringify({ ids: missing }),
+                });
+                if (res.ok) {
+                    const json = (await res.json());
+                    for (const [id, profile] of Object.entries(json.users)) {
+                        result.set(id, profile);
+                        // Backfill the in-memory cache so subsequent lookups are instant
+                        this.byId.set(id, profile);
+                        if (profile.external_id != null) {
+                            this.byExternalId.set(profile.external_id, id);
+                        }
+                    }
+                    this.log(`🔄 Backfilled ${Object.keys(json.users).length} cache miss(es)`);
+                }
+                else {
+                    this.log(`⚠️  HTTP fallback failed: ${res.status} ${res.statusText}`);
+                }
+            }
+            catch (err) {
+                this.log(`⚠️  HTTP fallback error: ${err.message}`);
+            }
+        }
+        return result;
+    }
+    /** Check if a UUID exists in the cache. */
+    has(uuid) {
+        return this.byId.has(uuid);
+    }
+    // ── Stats ─────────────────────────────────────────────────────────────────
+    /** Cache statistics for health checks and monitoring. */
+    get stats() {
+        return {
+            userCount: this.byId.size,
+            externalIdCount: this.byExternalId.size,
+            lastRefreshed: this._lastRefreshed,
+            isRunning: this.timer !== null,
+        };
+    }
+}
+// ── Singleton ─────────────────────────────────────────────────────────────────
+// Module-level singleton — import and use directly from route handlers.
+export const userCache = new UserCache();

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@newhomestar/sdk",
-  "version": "0.8.0",
-  "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
-  "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
-  "bugs": {
-    "url": "https://github.com/newhomestar/nova-node-sdk/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/newhomestar/nova-node-sdk.git"
-  },
-  "license": "ISC",
-  "author": "Christian Gomez",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./next": {
-      "import": "./dist/next.js",
-      "types": "./dist/next.d.ts"
-    },
-    "./events": {
-      "import": "./dist/events.js",
-      "types": "./dist/events.d.ts"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc"
-  },
-  "dependencies": {
-    "@openfga/sdk": "^0.9.0",
-    "@orpc/openapi": "1.7.4",
-    "@orpc/server": "1.7.4",
-    "@supabase/supabase-js": "^2.39.0",
-    "body-parser": "^1.20.2",
-    "dotenv": "^16.4.3",
-    "express": "^4.18.2",
-    "express-oauth2-jwt-bearer": "^1.7.4",
-    "undici": "^7.24.4",
-    "yaml": "^2.7.1"
-  },
-  "peerDependencies": {
-    "zod": ">=4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.17",
-    "typescript": "^5.4.4",
-    "zod": "^4.3.0"
-  }
-}
+{
+  "name": "@newhomestar/sdk",
+  "version": "0.8.1",
+  "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
+  "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/newhomestar/nova-node-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/newhomestar/nova-node-sdk.git"
+  },
+  "license": "ISC",
+  "author": "Christian Gomez",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./next": {
+      "import": "./dist/next.js",
+      "types": "./dist/next.d.ts"
+    },
+    "./events": {
+      "import": "./dist/events.js",
+      "types": "./dist/events.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@openfga/sdk": "^0.9.0",
+    "@orpc/openapi": "1.7.4",
+    "@orpc/server": "1.7.4",
+    "@supabase/supabase-js": "^2.39.0",
+    "body-parser": "^1.20.2",
+    "dotenv": "^16.4.3",
+    "express": "^4.18.2",
+    "express-oauth2-jwt-bearer": "^1.7.4",
+    "undici": "^7.24.4",
+    "yaml": "^2.7.1"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.17",
+    "typescript": "^5.4.4",
+    "zod": "^4.3.0"
+  }
+}