@newhomestar/sdk 0.5.1 → 0.6.5

package/dist/credentials.d.ts

@@ -0,0 +1,99 @@
+import { type SupabaseClient } from "@supabase/supabase-js";
+import https from "node:https";
+export type AuthMode = "standard" | "client_credentials" | "mtls";
+export interface ResolvedCredentials {
+    /** Bearer access token for API calls */
+    accessToken: string;
+    /** When the token expires */
+    expiresAt: Date;
+    /** The app_integrations.id UUID */
+    integrationId: string;
+    /** Auth mode used */
+    authMode: AuthMode;
+    /** mTLS agent (if auth_mode = 'mtls') — use for ALL API requests to that provider */
+    httpsAgent?: https.Agent;
+}
+export interface IntegrationConfig {
+    id: string;
+    slug: string;
+    name: string;
+    auth_mode: AuthMode;
+    client_id: string | null;
+    client_secret_vault_id: string | null;
+    token_endpoint: string | null;
+    mtls_cert_vault_id: string | null;
+    mtls_key_vault_id: string | null;
+    is_active: boolean;
+}
+export declare class IntegrationNotFoundError extends Error {
+    constructor(slug: string);
+}
+export declare class IntegrationDisabledError extends Error {
+    constructor(slug: string);
+}
+export declare class CredentialsNotConfiguredError extends Error {
+    constructor(slug: string, detail: string);
+}
+export declare class ConnectionNotFoundError extends Error {
+    constructor(slug: string, userId: string);
+}
+export declare class TokenExchangeError extends Error {
+    constructor(slug: string, detail: string);
+}
+/**
+ * Creates / returns the singleton Platform DB client.
+ * Reads from PLATFORM_SUPABASE_URL + PLATFORM_SUPABASE_SERVICE_ROLE_KEY.
+ */
+export declare function createPlatformClient(): SupabaseClient;
+/**
+ * Resolves an access token for an integration, handling all auth modes.
+ *
+ * Flow:
+ * 1. Look up integration config from app_integrations (by slug)
+ * 2. Check auth_mode → route to server or user flow
+ * 3. Check in-memory cache → DB (user_app_connections) → exchange if needed
+ * 4. Cache the result and return
+ *
+ * @param platformDB  - Platform Supabase client (project-starfleet-auth)
+ * @param slug        - Integration slug (e.g., 'adp', 'salesforce')
+ * @param userId      - User ID for standard OAuth; optional for server flows
+ */
+export declare function resolveCredentials(platformDB: SupabaseClient, slug: string, userId?: string): Promise<ResolvedCredentials>;
+/**
+ * Generic mTLS-aware fetch for integration API calls.
+ * If the resolved credentials include an httpsAgent (mTLS), uses node:https.
+ * Otherwise, uses global fetch().
+ *
+ * Works with ANY integration — not ADP-specific.
+ */
+export declare function integrationFetch(url: string, credentials: ResolvedCredentials, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}): Promise<Response>;
+/**
+ * Emit a PGMQ event to the platform database.
+ * Used for cross-service communication (e.g., sync complete, webhook received).
+ */
+export declare function emitPlatformEvent(platformDB: SupabaseClient, topic: string, integrationSlug: string, payload: Record<string, unknown>): Promise<void>;
+/**
+ * Resolve credentials for an integration using the HTTP callback strategy.
+ *
+ * This is the main entry point for Strategy B. It:
+ * 1. Checks the in-memory cache
+ * 2. Fetches decrypted credentials from the auth server via HTTP
+ * 3. Performs the OAuth token exchange (client_credentials or mTLS)
+ * 4. Caches the resulting access token in memory
+ *
+ * @param authBaseUrl - Auth server base URL
+ * @param slug        - Integration slug
+ * @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>;
+/**
+ * Detect which credential resolution strategy to use.
+ * Returns 'db' if PLATFORM_SUPABASE_* are available, 'http' if AUTH_ISSUER_BASE_URL
+ * is set, or 'none' if neither is configured.
+ */
+export declare function detectCredentialStrategy(): "db" | "http" | "none";