@newhomestar/sdk 0.7.14 → 0.7.16

package/dist/credentials.d.ts

@@ -45,6 +45,12 @@ export declare class TokenExchangeError extends Error {
  * Reads from PLATFORM_SUPABASE_URL + PLATFORM_SUPABASE_SERVICE_ROLE_KEY.
  */
 export declare function createPlatformClient(): SupabaseClient;
+/**
+ * Evict a cached token for the given integration slug and optional userId.
+ * Call this when an API returns 401 so the next resolveCredentials() call
+ * fetches a fresh token instead of re-using the revoked one.
+ */
+export declare function clearTokenCache(slug: string, userId?: string): void;
 /**
  * Resolves an access token for an integration, handling all auth modes.
  *
@@ -90,7 +96,9 @@ export declare function emitPlatformEvent(platformDB: SupabaseClient, topic: str
  * @param bearerToken - JWT to authenticate with the auth server
  * @param userId      - Optional user ID (for cache key differentiation)
  */
-export declare function resolveCredentialsViaHttp(authBaseUrl: string, slug: string, bearerToken: string, userId?: string): Promise<ResolvedCredentials>;
+export declare function resolveCredentialsViaHttp(authBaseUrl: string, slug: string, bearerToken: string, userId?: string, options?: {
+    forceRefresh?: boolean;
+}): Promise<ResolvedCredentials>;
 /**
  * Detect which credential resolution strategy to use.
  * Returns 'db' if PLATFORM_SUPABASE_* are available, 'http' if AUTH_ISSUER_BASE_URL

package/dist/credentials.js

@@ -78,6 +78,16 @@ const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
 function getCacheKey(integrationSlug, userId) {
     return `${integrationSlug}:${userId ?? SYSTEM_USER_ID}`;
 }
+/**
+ * Evict a cached token for the given integration slug and optional userId.
+ * Call this when an API returns 401 so the next resolveCredentials() call
+ * fetches a fresh token instead of re-using the revoked one.
+ */
+export function clearTokenCache(slug, userId) {
+    const key = getCacheKey(slug, userId);
+    const deleted = _tokenCache.delete(key);
+    console.log(`[nova-sdk] 🗑️  Cleared in-memory token cache for "${slug}" (key=${key}, existed=${deleted})`);
+}
 function getCachedToken(key) {
     const cached = _tokenCache.get(key);
     if (!cached)
@@ -613,20 +623,23 @@ function buildMtlsAgentFromPem(slug, certPem, keyPem) {
  * Requires a valid JWT Bearer token (the same one that authenticated the
  * inbound request to this container).
  *
- * @param authBaseUrl - Auth server base URL (e.g., "http://localhost:3001")
- * @param slug        - Integration slug (e.g., "adp")
- * @param bearerToken - JWT to forward as Authorization header
+ * @param authBaseUrl  - Auth server base URL (e.g., "http://localhost:3001")
+ * @param slug         - Integration slug (e.g., "adp")
+ * @param bearerToken  - JWT to forward as Authorization header
+ * @param forceRefresh - When true, sends X-Nova-Token-Invalid: true to trigger a forced refresh
  */
-async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken) {
+async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken, forceRefresh = false) {
     const url = `${authBaseUrl}/api/integrations/${encodeURIComponent(slug)}/credentials`;
-    console.log(`[nova-sdk] 🌐 Fetching credentials via HTTP: GET ${url}`);
-    const res = await fetch(url, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${bearerToken}`,
-            Accept: "application/json",
-        },
-    });
+    console.log(`[nova-sdk] 🌐 Fetching credentials via HTTP: GET ${url}${forceRefresh ? " (force-refresh)" : ""}`);
+    const headers = {
+        Authorization: `Bearer ${bearerToken}`,
+        Accept: "application/json",
+    };
+    // Signal the auth server to discard its stored token and force a refresh
+    if (forceRefresh) {
+        headers["X-Nova-Token-Invalid"] = "true";
+    }
+    const res = await fetch(url, { method: "GET", headers });
     if (!res.ok) {
         const errBody = await res.text().catch(() => "");
         if (res.status === 401) {
@@ -656,12 +669,13 @@ async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken) {
  * @param bearerToken - JWT to authenticate with the auth server
  * @param userId      - Optional user ID (for cache key differentiation)
  */
-export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken, userId) {
+export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken, userId, options) {
     const effectiveUserId = userId ?? SYSTEM_USER_ID;
     const cacheKey = getCacheKey(slug, effectiveUserId);
-    console.log(`[nova-sdk] 🔑 Resolving credentials for "${slug}" via HTTP (userId: ${effectiveUserId})`);
-    // ── Step 1: Check in-memory cache ─────────────────────────────────────
-    const cached = getCachedToken(cacheKey);
+    const forceRefresh = options?.forceRefresh ?? false;
+    console.log(`[nova-sdk] 🔑 Resolving credentials for "${slug}" via HTTP (userId: ${effectiveUserId}${forceRefresh ? ", forceRefresh=true" : ""})`);
+    // ── Step 1: Check in-memory cache (skip if forcing refresh) ──────────
+    const cached = forceRefresh ? null : getCachedToken(cacheKey);
     if (cached) {
         // Derive authMode: use stored value if available, otherwise infer from httpsAgent
         const cachedAuthMode = cached.authMode ?? (cached.httpsAgent ? "mtls" : "client_credentials");
@@ -675,7 +689,7 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
         };
     }
     // ── Step 2: Fetch credentials from auth server ────────────────────────
-    const creds = await fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken);
+    const creds = await fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken, forceRefresh);
     // ── Step 2b: Standard auth — use pre-resolved access token if available ──
     if (creds.authMode === "standard") {
         if (creds.accessToken) {

package/dist/index.d.ts

@@ -85,6 +85,45 @@ export interface ActionDef<I extends ZodTypeAny, O extends ZodTypeAny> {
         eventTypes?: string[];
         consumerGroup?: string;
     }>;
+    /**
+     * Sync capability metadata — declares this action as a data sync endpoint.
+     * Read by `nova integrations build` to include sync config in nova-integration.yaml.
+     * Surfaced in the Odyssey UI DataSyncTab for each integration.
+     *
+     * @example
+     * ```ts
+     * sync: {
+     *   entityType: "issue",
+     *   direction: "to_nova",
+     *   label: "Jira Issues",
+     *   description: "Import all Jira issues into Nova",
+     * }
+     * ```
+     */
+    sync?: {
+        /** Entity type identifier (e.g., "issue", "contact", "employee") */
+        entityType: string;
+        /** Direction of sync: to_nova = import from provider; from_nova = export to provider */
+        direction: 'to_nova' | 'from_nova' | 'bidirectional';
+        /** Human-readable label shown in the UI (e.g., "Jira Issues") */
+        label: string;
+        /** Optional description shown below the label in the DataSyncTab */
+        description?: string;
+    };
+    /**
+     * Trigger-based routing declarations.
+     * Used by the SSE worker mode to route incoming messages to this action's handler.
+     * Also read by `nova integrations build` to register event_subscriptions on push.
+     */
+    triggers?: Array<{
+        type: 'event';
+        events: string[];
+    } | {
+        type: 'schedule';
+        cron: string;
+        timezone?: string;
+        description?: string;
+    }>;
 }
 /** Validated JWT claims from express-oauth2-jwt-bearer */
 export interface JWTPayload {
@@ -208,6 +247,30 @@ export declare function action<I extends ZodTypeAny, O extends ZodTypeAny>(cfg:
         eventTypes?: string[];
         consumerGroup?: string;
     }>;
+    /**
+     * Sync capability metadata — declares this action as a data sync endpoint.
+     * Surfaced in the Odyssey UI DataSyncTab and included in nova-integration.yaml
+     * by `nova integrations build`.
+     */
+    sync?: {
+        entityType: string;
+        direction: 'to_nova' | 'from_nova' | 'bidirectional';
+        label: string;
+        description?: string;
+    };
+    /**
+     * Trigger-based routing declarations for event/schedule triggers.
+     * Used by the SSE worker and CLI build pipeline.
+     */
+    triggers?: Array<{
+        type: 'event';
+        events: string[];
+    } | {
+        type: 'schedule';
+        cron: string;
+        timezone?: string;
+        description?: string;
+    }>;
     handler: (input: z.infer<I>, ctx: ActionCtx) => Promise<z.infer<O>>;
 }): ActionDef<I, O>;
 import type { NovaSpec } from './parseSpec.js';

package/dist/index.js

@@ -6,7 +6,7 @@ import { createServer } from "node:http";
 import { os } from "@orpc/server";
 import { RPCHandler } from "@orpc/server/node";
 import { CORSPlugin } from "@orpc/server/plugins";
-import { createPlatformClient, resolveCredentials as _resolveCredentials, resolveCredentialsViaHttp as _resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch as _integrationFetch, } from "./credentials.js";
+import { createPlatformClient, resolveCredentials as _resolveCredentials, resolveCredentialsViaHttp as _resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch as _integrationFetch, clearTokenCache as _clearTokenCache, } from "./credentials.js";
 if (!process.env.RUNTIME_SUPABASE_URL) {
     // local dev – read .env.local
     dotenv.config({ path: ".env.local", override: true });
@@ -580,7 +580,42 @@ function buildCredentialCtx(defaultSlug, authToken) {
     };
     const ctxFetch = async (url, options, credentials) => {
         const creds = credentials ?? _lastCreds ?? await ctxResolveCredentials();
-        return _integrationFetch(url, creds, options);
+        const response = await _integrationFetch(url, creds, options);
+        // ── 401 auto-retry: token may have been revoked ──────────────────────────
+        // If the API returns 401 AND the caller didn't supply explicit credentials
+        // (i.e., we used the cached/resolved ones), clear the in-memory cache and
+        // force-refresh from the auth server, then retry once.
+        // This handles the "user re-authenticated but container still holds the old
+        // revoked token" scenario.
+        if (response.status === 401 && !credentials) {
+            console.warn(`[nova-sdk] ⚠️ 401 received from ${url} — clearing cache and force-refreshing credentials for "${defaultSlug}"`);
+            _clearTokenCache(defaultSlug);
+            _lastCreds = null;
+            let freshCreds;
+            if (strategy === "http") {
+                // HTTP strategy: signal auth server to bypass its stored token and refresh
+                const authBaseUrl = process.env.AUTH_ISSUER_BASE_URL;
+                if (!authToken) {
+                    console.error("[nova-sdk] ❌ Cannot force-refresh: no authToken available");
+                    return response; // return original 401
+                }
+                freshCreds = await _resolveCredentialsViaHttp(authBaseUrl, defaultSlug, authToken, undefined, { forceRefresh: true });
+            }
+            else {
+                // DB strategy: just re-resolve (DB always reads latest from vault)
+                freshCreds = await ctxResolveCredentials();
+            }
+            _lastCreds = freshCreds;
+            // Only retry if we got a different (fresh) token — avoid an infinite loop
+            if (freshCreds.accessToken !== creds.accessToken) {
+                console.log(`[nova-sdk] 🔄 Retrying request with refreshed token for "${defaultSlug}"`);
+                return _integrationFetch(url, freshCreds, options);
+            }
+            else {
+                console.warn(`[nova-sdk] ⚠️ Force-refresh returned the same token for "${defaultSlug}" — not retrying`);
+            }
+        }
+        return response;
     };
     return { resolveCredentials: ctxResolveCredentials, fetch: ctxFetch };
 }
@@ -732,7 +767,10 @@ export function runHttpServer(def, opts = {}) {
                         rawInput[key] = val === 'true' || val === '1';
                     }
                     // Auto-detect from Zod schema shape if no explicit uiType
-                    else if (!uiType && act.input?._def?.shape) {
+                    // Guard: _def.shape must be a function (Zod v3 thunk) before calling it.
+                    // Some Zod internals expose _def.shape as a plain object; calling a non-function
+                    // throws "act.input._def.shape is not a function" at runtime.
+                    else if (!uiType && typeof act.input?._def?.shape === 'function') {
                         const fieldDef = act.input._def.shape()?.[key];
                         const innerType = fieldDef?._def?.innerType?._def?.typeName ?? fieldDef?._def?.typeName;
                         if (innerType === 'ZodNumber') {

package/package.json

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