@newhomestar/sdk 0.8.14 → 0.8.17

package/dist/connections.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The consolidated payload returned by the auth server's
+ * `POST /api/integrations/resolve` endpoint, deserialized for ergonomic use.
+ */
+export interface ResolvedConnection {
+    /** UUID of the Nova `app_user_connections` row */
+    connectionId: string;
+    /** Integration slug, e.g. "jira" */
+    integrationSlug: string;
+    /** The external entity UUID this connection scope was resolved for */
+    remoteId: string;
+    /** External user id at the provider (e.g. Jira accountId), null if not captured */
+    externalUserId: string | null;
+    /** Decrypted OAuth access token — bearer for provider API calls */
+    accessToken: string;
+    /** Token expiry as a JS Date, or null if the provider didn't return one */
+    tokenExpiresAt: Date | null;
+    /** Wizard-saved per-account config (e.g. `{ webhookProjects: ["SUPPORT"] }`) */
+    config: Record<string, unknown>;
+    /** Whether the user completed all required wizard fields */
+    isComplete: boolean;
+}
+/** Options for resolveConnection() */
+export interface ResolveConnectionOptions {
+    /** Integration slug (e.g. "jira", "bamboohr") */
+    slug: string;
+    /** External entity UUID (e.g. TicketingAccount.id, HrisCompany.id) */
+    remoteId: string;
+    /**
+     * Override the auth server URL. Defaults to `process.env.AUTH_ISSUER_BASE_URL`
+     * — the same env var used by `resolveCredentialsViaServiceToken`.
+     */
+    authUrl?: string;
+    /**
+     * Override the service token. Defaults to `process.env.NOVA_SERVICE_TOKEN`.
+     */
+    serviceToken?: string;
+    /**
+     * When true, bypass the in-memory cache and force a fresh round-trip.
+     */
+    forceRefresh?: boolean;
+}
+export declare class ConnectionResolutionError extends Error {
+    readonly status?: number | undefined;
+    readonly responseBody?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, responseBody?: unknown | undefined);
+}
+export declare class ConfigNotFoundError extends ConnectionResolutionError {
+    constructor(slug: string, remoteId: string);
+}
+export declare class ConnectionTokenExpiredError extends ConnectionResolutionError {
+    constructor(slug: string, remoteId: string);
+}
+/**
+ * Resolve a Nova connection + access token + saved config from an external
+ * entity's `remote_id`.
+ *
+ * Typical use inside an outbound event handler:
+ *
+ * ```ts
+ * const conn = await resolveConnection({
+ *   slug: "jira",
+ *   remoteId: event.attributes.account,
+ * });
+ *
+ * await fetch(`${jiraBaseUrl}/issue`, {
+ *   method: "POST",
+ *   headers: { Authorization: `Bearer ${conn.accessToken}` },
+ *   body: JSON.stringify({
+ *     fields: { project: { key: conn.config.webhookProjects[0] }, ... },
+ *   }),
+ * });
+ * ```
+ *
+ * Cache: results are memoized in-process for 30 minutes, evicted automatically
+ * when the token is within 5 minutes of expiry. On 401 from the provider API,
+ * call `invalidateConnection()` and retry to force a refresh.
+ */
+export declare function resolveConnection(options: ResolveConnectionOptions): Promise<ResolvedConnection>;
+/**
+ * Drop a single cached resolution. Use this after the provider returns 401
+ * (the cached token is invalid) before retrying.
+ */
+export declare function invalidateConnection(params: {
+    slug: string;
+    remoteId: string;
+}): void;
+/**
+ * Drop all cached resolutions. Primarily useful in tests; production callers
+ * should prefer `invalidateConnection` for the specific scope that 401'd.
+ */
+export declare function clearConnectionCache(): void;

package/dist/connections.js

@@ -0,0 +1,197 @@
+// Nova SDK — Connection Resolution (`remote_id` → token + config)
+// ================================================================
+// One-shot lookup for outbound integration handlers that receive a platform
+// event payload containing only an external entity id (e.g. a TicketingAccount
+// UUID from `nova_ticketing_service.ticket_created.attributes.account`).
+//
+// Calls the auth server's `POST /api/integrations/resolve` endpoint and
+// returns a single bundle containing:
+//   • the Nova connection that owns the remote scope,
+//   • the wizard-saved per-account config (e.g. Jira `webhookProjects`),
+//   • a valid access token (auth server auto-refreshes if expired).
+//
+// Authentication uses NOVA_SERVICE_TOKEN — intended for background /
+// event-handler contexts that do not have an inbound user JWT.
+//
+// Caching: in-memory keyed `${slug}::${remoteId}` with a 30-minute TTL.
+// Entries are evicted automatically when the access token is within 5 minutes
+// of its expiry so the next call fetches a refreshed token.
+//
+// Public API:
+//   resolveConnection({ slug, remoteId, ... })   → ResolvedConnection
+//   invalidateConnection({ slug, remoteId })     → void
+//   clearConnectionCache()                       → void
+// ─── Error Classes ──────────────────────────────────────────────────────────
+export class ConnectionResolutionError extends Error {
+    status;
+    responseBody;
+    constructor(message, status, responseBody) {
+        super(message);
+        this.status = status;
+        this.responseBody = responseBody;
+        this.name = "ConnectionResolutionError";
+    }
+}
+export class ConfigNotFoundError extends ConnectionResolutionError {
+    constructor(slug, remoteId) {
+        super(`No saved config for integration "${slug}" with remote_id "${remoteId}". ` +
+            `The user must complete the connect wizard for this account before events can be processed.`, 404);
+        this.name = "ConfigNotFoundError";
+    }
+}
+export class ConnectionTokenExpiredError extends ConnectionResolutionError {
+    constructor(slug, remoteId) {
+        super(`Access token expired and could not be refreshed for "${slug}" / remote_id "${remoteId}". ` +
+            `User must re-connect.`, 401);
+        this.name = "ConnectionTokenExpiredError";
+    }
+}
+// ─── Cache ──────────────────────────────────────────────────────────────────
+/** Max age of any cache entry, regardless of token expiry. 30 minutes. */
+const CACHE_TTL_MS = 30 * 60 * 1000;
+/** Re-fetch when the token is within this window of expiry. 5 minutes. */
+const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+const _cache = new Map();
+function cacheKey(slug, remoteId) {
+    return `${slug.toLowerCase()}::${remoteId}`;
+}
+function isCacheEntryFresh(entry) {
+    const now = Date.now();
+    // Hard TTL cap
+    if (now - entry.cachedAt > CACHE_TTL_MS)
+        return false;
+    // Token-expiry buffer
+    const expiresAt = entry.value.tokenExpiresAt;
+    if (expiresAt && expiresAt.getTime() - now < TOKEN_REFRESH_BUFFER_MS) {
+        return false;
+    }
+    return true;
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Resolve a Nova connection + access token + saved config from an external
+ * entity's `remote_id`.
+ *
+ * Typical use inside an outbound event handler:
+ *
+ * ```ts
+ * const conn = await resolveConnection({
+ *   slug: "jira",
+ *   remoteId: event.attributes.account,
+ * });
+ *
+ * await fetch(`${jiraBaseUrl}/issue`, {
+ *   method: "POST",
+ *   headers: { Authorization: `Bearer ${conn.accessToken}` },
+ *   body: JSON.stringify({
+ *     fields: { project: { key: conn.config.webhookProjects[0] }, ... },
+ *   }),
+ * });
+ * ```
+ *
+ * Cache: results are memoized in-process for 30 minutes, evicted automatically
+ * when the token is within 5 minutes of expiry. On 401 from the provider API,
+ * call `invalidateConnection()` and retry to force a refresh.
+ */
+export async function resolveConnection(options) {
+    const { slug, remoteId, forceRefresh = false } = options;
+    const authUrl = options.authUrl ?? process.env.AUTH_ISSUER_BASE_URL;
+    const serviceToken = options.serviceToken ?? process.env.NOVA_SERVICE_TOKEN;
+    if (!authUrl) {
+        throw new ConnectionResolutionError(`[nova-sdk] resolveConnection("${slug}"): AUTH_ISSUER_BASE_URL is not set. ` +
+            `Pass options.authUrl or set the environment variable.`);
+    }
+    if (!serviceToken) {
+        throw new ConnectionResolutionError(`[nova-sdk] resolveConnection("${slug}"): NOVA_SERVICE_TOKEN is not set. ` +
+            `Pass options.serviceToken or set the environment variable.`);
+    }
+    // ── Cache lookup ────────────────────────────────────────────────────
+    const key = cacheKey(slug, remoteId);
+    if (!forceRefresh) {
+        const entry = _cache.get(key);
+        if (entry && isCacheEntryFresh(entry)) {
+            return entry.value;
+        }
+        if (entry) {
+            console.log(`[nova-sdk] 🗑️  resolveConnection cache stale for ${key} — refetching`);
+            _cache.delete(key);
+        }
+    }
+    else {
+        _cache.delete(key);
+    }
+    // ── HTTP call ───────────────────────────────────────────────────────
+    const endpoint = `${authUrl.replace(/\/+$/, "")}/api/integrations/resolve`;
+    console.log(`[nova-sdk] 🌐 resolveConnection: POST ${endpoint} slug="${slug}" remote_id=${remoteId}`);
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                Authorization: `Bearer ${serviceToken}`,
+            },
+            body: JSON.stringify({
+                integration_slug: slug,
+                remote_id: remoteId,
+            }),
+        });
+    }
+    catch (err) {
+        throw new ConnectionResolutionError(`[nova-sdk] resolveConnection: network error calling ${endpoint}: ${err?.message ?? err}`);
+    }
+    if (!res.ok) {
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            /* swallow parse errors — body may be empty */
+        }
+        if (res.status === 404 && body?.error === "config_not_found") {
+            throw new ConfigNotFoundError(slug, remoteId);
+        }
+        if (res.status === 401 && body?.error === "token_expired") {
+            throw new ConnectionTokenExpiredError(slug, remoteId);
+        }
+        const msg = body?.message ??
+            body?.error ??
+            `HTTP ${res.status} from ${endpoint}`;
+        throw new ConnectionResolutionError(`[nova-sdk] resolveConnection failed: ${msg}`, res.status, body);
+    }
+    const data = (await res.json());
+    const resolved = {
+        connectionId: data.connection_id,
+        integrationSlug: data.integration_slug,
+        remoteId: data.remote_id,
+        externalUserId: data.external_user_id,
+        accessToken: data.access_token,
+        tokenExpiresAt: data.token_expires_at ? new Date(data.token_expires_at) : null,
+        config: data.config ?? {},
+        isComplete: data.is_complete,
+    };
+    console.log(`[nova-sdk] ✅ resolveConnection: cached ${key} (token expires ${resolved.tokenExpiresAt?.toISOString() ?? "n/a"})`);
+    _cache.set(key, { value: resolved, cachedAt: Date.now() });
+    return resolved;
+}
+/**
+ * Drop a single cached resolution. Use this after the provider returns 401
+ * (the cached token is invalid) before retrying.
+ */
+export function invalidateConnection(params) {
+    const key = cacheKey(params.slug, params.remoteId);
+    const existed = _cache.delete(key);
+    if (existed) {
+        console.log(`[nova-sdk] 🗑️  invalidateConnection: cleared ${key}`);
+    }
+}
+/**
+ * Drop all cached resolutions. Primarily useful in tests; production callers
+ * should prefer `invalidateConnection` for the specific scope that 401'd.
+ */
+export function clearConnectionCache() {
+    const size = _cache.size;
+    _cache.clear();
+    console.log(`[nova-sdk] 🗑️  clearConnectionCache: cleared ${size} entries`);
+}

package/dist/credentials.js

@@ -190,6 +190,54 @@ async function performTokenExchange(slug, params) {
 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}${forceRefresh ? " (force-refresh)" : ""}`);
+    // ── Outgoing bearer-token preview ──────────────────────────────────────────
+    // We log the JWT's structural claims (NOT the signature, NOT secrets) so we
+    // can correlate the SDK's outgoing token against what the auth server says
+    // it received on the other side. This is invaluable when diagnosing 401s
+    // from `resolveCredentialsViaServiceToken` (the relay path).
+    try {
+        const parts = bearerToken.split(".");
+        if (parts.length === 3) {
+            // base64url → JSON. atob handles base64; we normalize url-safe chars first.
+            const b64urlDecode = (s) => {
+                const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+                // Pad to a multiple of 4
+                const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+                if (typeof Buffer !== "undefined") {
+                    return Buffer.from(padded, "base64").toString("utf8");
+                }
+                // Browser-safe fallback
+                // eslint-disable-next-line no-undef
+                return decodeURIComponent(escape(atob(padded)));
+            };
+            const header = JSON.parse(b64urlDecode(parts[0]));
+            const payload = JSON.parse(b64urlDecode(parts[1]));
+            console.log(`[nova-sdk] 🪪 Outgoing bearer header:`, {
+                alg: header.alg,
+                typ: header.typ,
+                kid: header.kid,
+            });
+            console.log(`[nova-sdk] 🪪 Outgoing bearer payload preview:`, {
+                iss: payload.iss,
+                aud: payload.aud,
+                sub: payload.sub,
+                client_id: payload.client_id,
+                scope: payload.scope,
+                service_name: payload.service_name,
+                exp: payload.exp,
+                iat: payload.iat,
+                secondsUntilExp: typeof payload.exp === "number"
+                    ? payload.exp - Math.floor(Date.now() / 1000)
+                    : null,
+            });
+        }
+        else {
+            console.log(`[nova-sdk] 🪪 Outgoing bearer is NOT a 3-part JWT (parts=${parts.length}, length=${bearerToken.length}). This is expected if the SDK is using INTERNAL_API_SECRET as a service token.`);
+        }
+    }
+    catch (decodeErr) {
+        console.warn(`[nova-sdk] ⚠️ Failed to decode outgoing bearer for preview:`, decodeErr instanceof Error ? decodeErr.message : String(decodeErr));
+    }
     const headers = {
         Authorization: `Bearer ${bearerToken}`,
         Accept: "application/json",

package/dist/integration.d.ts

@@ -770,8 +770,8 @@ export declare const IntegrationDefSchema: z.ZodObject<{
         slug: z.ZodString;
         name: z.ZodString;
         httpMethod: z.ZodEnum<{
-            GET: "GET";
             POST: "POST";
+            GET: "GET";
             PATCH: "PATCH";
             DELETE: "DELETE";
             PUT: "PUT";

package/dist/integrationSpec.d.ts

@@ -160,8 +160,8 @@ export declare const IntegrationSpecSchema: z.ZodObject<{
             slug: z.ZodString;
             name: z.ZodString;
             httpMethod: z.ZodEnum<{
-                GET: "GET";
                 POST: "POST";
+                GET: "GET";
                 PATCH: "PATCH";
                 DELETE: "DELETE";
                 PUT: "PUT";

package/dist/workerSchema.d.ts

@@ -27,8 +27,8 @@ export declare const WorkerDefSchema: z.ZodObject<{
         input: z.ZodAny;
         output: z.ZodAny;
         method: z.ZodOptional<z.ZodEnum<{
-            GET: "GET";
             POST: "POST";
+            GET: "GET";
             PATCH: "PATCH";
             DELETE: "DELETE";
             PUT: "PUT";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.8.14",
+  "version": "0.8.17",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {
@@ -27,6 +27,10 @@
     "./events": {
       "import": "./dist/events.js",
       "types": "./dist/events.d.ts"
+    },
+    "./connections": {
+      "import": "./dist/connections.js",
+      "types": "./dist/connections.d.ts"
     }
   },
   "files": [