@newhomestar/sdk 0.7.26 → 0.8.1

package/dist/credentials.d.ts

@@ -89,3 +89,65 @@ export declare function integrationFetch(url: string, credentials: ResolvedCrede
  * separate from credential resolution. Credential resolution uses HTTP (AUTH_ISSUER_BASE_URL).
  */
 export declare function emitPlatformEvent(platformDB: SupabaseClient, topic: string, integrationSlug: string, payload: Record<string, unknown>): Promise<void>;
+/**
+ * Fetch integration credentials using a service token (NOVA_SERVICE_TOKEN).
+ * Same auth server endpoint as resolveCredentialsViaHttp, but authenticates
+ * with the service token instead of a user JWT. Intended for background
+ * processing loops that run outside the HTTP request context.
+ *
+ * @param authBaseUrl   - Auth server base URL (AUTH_ISSUER_BASE_URL)
+ * @param slug          - Integration slug (e.g., "adp", "bamboohr")
+ * @param serviceToken  - NOVA_SERVICE_TOKEN value
+ */
+export declare function resolveCredentialsViaServiceToken(authBaseUrl: string, slug: string, serviceToken: string): Promise<ResolvedCredentials>;
+/** The client object returned by createIntegrationClient() */
+export interface IntegrationClient {
+    /**
+     * mTLS-aware fetch with auto-refreshing credentials.
+     * Automatically re-resolves credentials when they expire.
+     * On 401, forces a credential refresh and retries once.
+     */
+    fetch: (url: string, options?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+    }) => Promise<Response>;
+    /** Force credential re-resolution (e.g., after persistent 401s) */
+    refreshCredentials: () => Promise<ResolvedCredentials>;
+    /** Get current credentials (resolves if needed) */
+    ensureCredentials: () => Promise<ResolvedCredentials>;
+    /** The integration slug */
+    readonly slug: string;
+}
+/**
+ * Create a standalone integration client for background / headless contexts.
+ *
+ * Uses NOVA_SERVICE_TOKEN to resolve credentials from the auth server.
+ * Credentials are cached in memory and auto-refreshed when they expire
+ * (with a 60-second buffer before expiry).
+ *
+ * Designed for the two-phase ledger queue pattern:
+ *   1. Action handler seeds ledger rows (fast, no API calls)
+ *   2. Background loop processes ledger rows using this client
+ *
+ * @param slug    - Integration slug (e.g., "adp", "bamboohr")
+ * @param options - Optional overrides for service token and auth URL
+ *
+ * @example
+ * ```typescript
+ * // In action handler (has JWT context):
+ * const client = createIntegrationClient("adp");
+ * setImmediate(() => processLedgerQueue(jobId, tenantId, client));
+ *
+ * // In background loop:
+ * const resp = await client.fetch("https://api.adp.com/hr/v2/workers/123");
+ * if (resp.status === 204) continue; // handled correctly — no crash
+ * const data = await resp.json();
+ * ```
+ */
+export declare function createIntegrationClient(slug: string, options?: {
+    /** Override service token (defaults to NOVA_SERVICE_TOKEN env var) */
+    serviceToken?: string;
+    /** Override auth server URL (defaults to AUTH_ISSUER_BASE_URL env var) */
+    authBaseUrl?: string;
+}): IntegrationClient;

package/dist/credentials.js

@@ -246,6 +246,16 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
             const expiresAt = creds.expiresAt
                 ? new Date(creds.expiresAt)
                 : new Date(Date.now() + 3600 * 1000); // default 1h if not provided
+            // ── Safety net: if the auth server returned an already-expired token,
+            //    auto-retry with forceRefresh=true to trigger a server-side refresh.
+            //    This guards against clock skew or a stale cached token on the auth server.
+            //    Only retry once (when forceRefresh is not already true) to prevent infinite loops.
+            if (expiresAt.getTime() < Date.now() && !forceRefresh) {
+                console.warn(`[nova-sdk] ⚠️ Auth server returned an already-expired token for "${slug}" ` +
+                    `(expired ${expiresAt.toISOString()}, now ${new Date().toISOString()}). ` +
+                    `Auto-retrying with forceRefresh=true…`);
+                return resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken, userId, { forceRefresh: true });
+            }
             console.log(`[nova-sdk] ✅ Standard auth: received access token for "${slug}" — expires ${expiresAt.toISOString()}`);
             return {
                 accessToken: creds.accessToken,
@@ -344,9 +354,16 @@ export async function integrationFetch(url, credentials, options = {}) {
                 res.on("data", (chunk) => chunks.push(chunk));
                 res.on("end", () => {
                     const bodyStr = Buffer.concat(chunks).toString("utf-8");
-                    console.log(`[nova-sdk] 📥 mTLS response: HTTP ${res.statusCode} for ${options.method ?? "GET"} ${url}`);
-                    resolve(new Response(bodyStr, {
-                        status: res.statusCode ?? 500,
+                    const statusCode = res.statusCode ?? 500;
+                    console.log(`[nova-sdk] 📥 mTLS response: HTTP ${statusCode} for ${options.method ?? "GET"} ${url}`);
+                    // Null-body status codes (204, 304) must NOT include a body per the
+                    // Fetch spec. Node.js v20's Response constructor enforces this — passing
+                    // a non-null body with status 204 throws a TypeError that escapes the
+                    // Promise chain (the https callback is not connected to it), causing
+                    // an uncaught exception AND a permanently-pending Promise (hang).
+                    const isNullBodyStatus = statusCode === 204 || statusCode === 304;
+                    resolve(new Response(isNullBodyStatus ? null : bodyStr, {
+                        status: statusCode,
                         statusText: res.statusMessage ?? "Unknown",
                         headers: new Headers(res.headers),
                     }));
@@ -399,3 +416,170 @@ export async function emitPlatformEvent(platformDB, topic, integrationSlug, payl
         console.log(`[nova-sdk] ✅ Event emitted: ${topic}`);
     }
 }
+// ═══════════════════════════════════════════════════════════════════════════════
+// Service-Token Credential Resolution (for background / headless contexts)
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// Background sync loops (fire-and-forget via setImmediate) don't have an
+// inbound JWT. They use NOVA_SERVICE_TOKEN to authenticate with the auth
+// server's credential endpoint instead.
+//
+// The auth server already accepts this token as a Bearer (matched against
+// INTERNAL_API_SECRET env var on the auth server side).
+//
+// For client_credentials / mTLS integrations (like ADP), no userId is needed.
+// For standard auth, the service token path won't have user context — callers
+// must pre-resolve user tokens in the handler while the JWT is available.
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Fetch integration credentials using a service token (NOVA_SERVICE_TOKEN).
+ * Same auth server endpoint as resolveCredentialsViaHttp, but authenticates
+ * with the service token instead of a user JWT. Intended for background
+ * processing loops that run outside the HTTP request context.
+ *
+ * @param authBaseUrl   - Auth server base URL (AUTH_ISSUER_BASE_URL)
+ * @param slug          - Integration slug (e.g., "adp", "bamboohr")
+ * @param serviceToken  - NOVA_SERVICE_TOKEN value
+ */
+export async function resolveCredentialsViaServiceToken(authBaseUrl, slug, serviceToken) {
+    console.log(`[nova-sdk] 🔑 resolveCredentialsViaServiceToken: slug="${slug}" authBaseUrl="${authBaseUrl}"`);
+    // Fetch credentials from auth server using service token as Bearer
+    const creds = await fetchCredentialsFromAuthServer(authBaseUrl, slug, serviceToken, false);
+    // ── Standard auth — not supported in service-token mode ───────────────
+    if (creds.authMode === "standard") {
+        // Standard auth needs a userId for user_app_connections lookup.
+        // The service token path doesn't carry user context.
+        // If the auth server returned a pre-resolved token (org-level), use it.
+        if (creds.accessToken) {
+            const expiresAt = creds.expiresAt
+                ? new Date(creds.expiresAt)
+                : new Date(Date.now() + 3600 * 1000);
+            return {
+                accessToken: creds.accessToken,
+                expiresAt,
+                integrationId: `service:${slug}`,
+                authMode: "standard",
+            };
+        }
+        throw new Error(`[nova-sdk] Standard auth integration "${slug}" requires user context (JWT). ` +
+            `Use ctx.resolveCredentials() in the handler, not resolveCredentialsViaServiceToken().`);
+    }
+    // ── Validate required fields (client_credentials / mTLS) ─────────────
+    if (!creds.clientId) {
+        throw new CredentialsNotConfiguredError(slug, "client_id is not set");
+    }
+    if (!creds.clientSecret) {
+        throw new CredentialsNotConfiguredError(slug, "client_secret not available");
+    }
+    if (!creds.tokenEndpoint) {
+        throw new CredentialsNotConfiguredError(slug, "token_endpoint is not set");
+    }
+    // ── Build mTLS agent if needed ────────────────────────────────────────
+    let httpsAgent;
+    if (creds.authMode === "mtls") {
+        if (!creds.mtlsCert || !creds.mtlsKey) {
+            throw new CredentialsNotConfiguredError(slug, "mTLS cert/key not returned by auth server");
+        }
+        httpsAgent = buildMtlsAgentFromPem(slug, creds.mtlsCert, creds.mtlsKey);
+    }
+    // ── Perform token exchange ────────────────────────────────────────────
+    console.log(`[nova-sdk] 🔄 Service-token: performing ${creds.authMode} token exchange for "${slug}"`);
+    const tokenResponse = await performTokenExchange(slug, {
+        tokenEndpoint: creds.tokenEndpoint,
+        clientId: creds.clientId,
+        clientSecret: creds.clientSecret,
+        httpsAgent,
+    });
+    const expiresAt = new Date(Date.now() + tokenResponse.expires_in * 1000);
+    console.log(`[nova-sdk] ✅ Service-token: token exchange successful for "${slug}" — expires ${expiresAt.toISOString()}`);
+    return {
+        accessToken: tokenResponse.access_token,
+        expiresAt,
+        integrationId: `service:${slug}`,
+        authMode: creds.authMode,
+        httpsAgent,
+    };
+}
+/**
+ * Create a standalone integration client for background / headless contexts.
+ *
+ * Uses NOVA_SERVICE_TOKEN to resolve credentials from the auth server.
+ * Credentials are cached in memory and auto-refreshed when they expire
+ * (with a 60-second buffer before expiry).
+ *
+ * Designed for the two-phase ledger queue pattern:
+ *   1. Action handler seeds ledger rows (fast, no API calls)
+ *   2. Background loop processes ledger rows using this client
+ *
+ * @param slug    - Integration slug (e.g., "adp", "bamboohr")
+ * @param options - Optional overrides for service token and auth URL
+ *
+ * @example
+ * ```typescript
+ * // In action handler (has JWT context):
+ * const client = createIntegrationClient("adp");
+ * setImmediate(() => processLedgerQueue(jobId, tenantId, client));
+ *
+ * // In background loop:
+ * const resp = await client.fetch("https://api.adp.com/hr/v2/workers/123");
+ * if (resp.status === 204) continue; // handled correctly — no crash
+ * const data = await resp.json();
+ * ```
+ */
+export function createIntegrationClient(slug, options) {
+    const serviceToken = options?.serviceToken ??
+        process.env.NOVA_SERVICE_TOKEN;
+    const authBaseUrl = options?.authBaseUrl ??
+        process.env.AUTH_ISSUER_BASE_URL;
+    if (!serviceToken) {
+        throw new Error(`[nova-sdk] createIntegrationClient("${slug}"): NOVA_SERVICE_TOKEN is required ` +
+            `for background credential resolution. Set it as an environment variable.`);
+    }
+    if (!authBaseUrl) {
+        throw new Error(`[nova-sdk] createIntegrationClient("${slug}"): AUTH_ISSUER_BASE_URL is required. ` +
+            `Set it as an environment variable.`);
+    }
+    let _creds = null;
+    /** Resolve credentials, using cached version if still valid (60s buffer) */
+    const ensureCredentials = async () => {
+        const now = Date.now();
+        // Re-resolve if no cached creds, or if they expire within 60 seconds
+        if (!_creds || _creds.expiresAt.getTime() < now + 60_000) {
+            console.log(`[nova-sdk] 🔄 IntegrationClient("${slug}"): ${_creds ? "refreshing expired" : "resolving initial"} credentials`);
+            _creds = await resolveCredentialsViaServiceToken(authBaseUrl, slug, serviceToken);
+        }
+        return _creds;
+    };
+    /** Force a fresh credential resolution (busts the in-memory cache) */
+    const refreshCredentials = async () => {
+        console.log(`[nova-sdk] 🔄 IntegrationClient("${slug}"): force-refreshing credentials`);
+        _creds = null;
+        return ensureCredentials();
+    };
+    /** mTLS-aware fetch with auto-refresh + 401 retry */
+    const clientFetch = async (url, fetchOptions) => {
+        const creds = await ensureCredentials();
+        const response = await integrationFetch(url, creds, fetchOptions);
+        // ── 401 auto-retry: refresh credentials and retry once ──────────────
+        if (response.status === 401) {
+            console.warn(`[nova-sdk] ⚠️ IntegrationClient("${slug}"): 401 from ${url} — refreshing credentials and retrying`);
+            const freshCreds = await refreshCredentials();
+            // Only retry if we got a different token (prevent infinite loops)
+            if (freshCreds.accessToken !== creds.accessToken) {
+                console.log(`[nova-sdk] 🔄 IntegrationClient("${slug}"): retrying with refreshed token`);
+                return integrationFetch(url, freshCreds, fetchOptions);
+            }
+            else {
+                console.warn(`[nova-sdk] ⚠️ IntegrationClient("${slug}"): refresh returned same token — not retrying`);
+            }
+        }
+        return response;
+    };
+    console.log(`[nova-sdk] ✅ IntegrationClient created for "${slug}" (auth: ${authBaseUrl}, token: ${serviceToken.slice(0, 8)}...)`);
+    return {
+        fetch: clientFetch,
+        refreshCredentials,
+        ensureCredentials,
+        slug,
+    };
+}

package/dist/index.d.ts

@@ -416,5 +416,5 @@ export type ScheduleTrigger = {
 };
 /** Union of all trigger variants */
 export type Trigger = EventTrigger | ScheduleTrigger;
-export { createPlatformClient, resolveCredentialsViaHttp, detectCredentialStrategy, clearTokenCache, integrationFetch, emitPlatformEvent, IntegrationNotFoundError, IntegrationDisabledError, CredentialsNotConfiguredError, ConnectionNotFoundError, TokenExchangeError, } from "./credentials.js";
-export type { ResolvedCredentials, AuthMode, } from "./credentials.js";
+export { createPlatformClient, resolveCredentialsViaHttp, resolveCredentialsViaServiceToken, createIntegrationClient, detectCredentialStrategy, clearTokenCache, integrationFetch, emitPlatformEvent, IntegrationNotFoundError, IntegrationDisabledError, CredentialsNotConfiguredError, ConnectionNotFoundError, TokenExchangeError, } from "./credentials.js";
+export type { ResolvedCredentials, AuthMode, IntegrationClient, } from "./credentials.js";

package/dist/index.js

@@ -913,7 +913,11 @@ export { parseIntegrationSpec, IntegrationSpecSchema } from "./integrationSpec.j
 // Every integration gets vault-backed token caching, mTLS, and OAuth for free.
 export { createPlatformClient, 
 // resolveCredentials (DB-based strategy removed — use resolveCredentialsViaHttp)
-resolveCredentialsViaHttp, detectCredentialStrategy, clearTokenCache, integrationFetch, emitPlatformEvent, 
+resolveCredentialsViaHttp, 
+// Service-token credential resolution (for background / headless sync loops)
+resolveCredentialsViaServiceToken, 
+// Standalone integration client (auto-refresh, mTLS, 401 retry)
+createIntegrationClient, detectCredentialStrategy, clearTokenCache, integrationFetch, emitPlatformEvent, 
 // Error classes
 IntegrationNotFoundError, IntegrationDisabledError, CredentialsNotConfiguredError, ConnectionNotFoundError, TokenExchangeError, } from "./credentials.js";
 // // Default export for compatibility

package/dist/next.d.ts

@@ -790,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,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.7.26",
+  "version": "0.8.1",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {