@newhomestar/sdk 0.7.26 → 0.8.0

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

@@ -124,9 +124,8 @@ 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' | 'body';
+    object_id_from: 'path' | 'query';
     /** 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 */

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@newhomestar/sdk",
-  "version": "0.7.26",
-  "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.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"
+  }
+}