@newhomestar/sdk 0.7.25 → 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

@@ -354,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),
                     }));
@@ -409,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.7.25",
+  "version": "0.8.0",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {