@contractspec/integration.runtime 2.10.0 → 3.1.1

package/dist/node/transport/auth-resolver.js

@@ -0,0 +1,51 @@
+// src/transport/auth-resolver.ts
+import { findAuthConfig } from "@contractspec/lib.contracts-integrations/integrations/auth";
+import {
+  buildAuthHeaders,
+  refreshOAuth2Token,
+  isOAuth2TokenExpired
+} from "@contractspec/lib.contracts-integrations/integrations/auth-helpers";
+async function resolveAuth(options) {
+  const authConfig = findAuthConfig(options.supportedAuthMethods, options.activeAuthMethod);
+  if (!authConfig) {
+    return { headers: {}, tokenRefreshed: false };
+  }
+  if (authConfig.type === "oauth2" && options.oauth2State) {
+    if (isOAuth2TokenExpired(options.oauth2State)) {
+      const clientId = options.secrets.clientId ?? "";
+      const clientSecret = options.secrets.clientSecret ?? "";
+      try {
+        const newState = await refreshOAuth2Token(authConfig, options.oauth2State, { clientId, clientSecret }, options.fetchFn);
+        const mergedSecrets2 = {
+          ...options.secrets,
+          accessToken: newState.accessToken
+        };
+        return {
+          headers: buildAuthHeaders(authConfig, mergedSecrets2),
+          tokenRefreshed: true,
+          updatedOAuth2State: newState
+        };
+      } catch {
+        return {
+          headers: buildAuthHeaders(authConfig, options.secrets),
+          tokenRefreshed: false
+        };
+      }
+    }
+    const mergedSecrets = {
+      ...options.secrets,
+      accessToken: options.oauth2State.accessToken
+    };
+    return {
+      headers: buildAuthHeaders(authConfig, mergedSecrets),
+      tokenRefreshed: false
+    };
+  }
+  return {
+    headers: buildAuthHeaders(authConfig, options.secrets),
+    tokenRefreshed: false
+  };
+}
+export {
+  resolveAuth
+};

package/dist/node/transport/index.js

@@ -0,0 +1,162 @@
+// src/transport/transport-factory.ts
+import { findTransportConfig } from "@contractspec/lib.contracts-integrations/integrations/transport";
+
+class RestTransportClient {
+  config;
+  authHeaders;
+  fetchFn;
+  type = "rest";
+  constructor(config, authHeaders = {}, fetchFn = globalThis.fetch) {
+    this.config = config;
+    this.authHeaders = authHeaders;
+    this.fetchFn = fetchFn;
+  }
+  async request(method, path, options) {
+    const url = new URL(path, this.config.baseUrl ?? "https://localhost");
+    if (options?.queryParams) {
+      for (const [key, value] of Object.entries(options.queryParams)) {
+        url.searchParams.set(key, value);
+      }
+    }
+    const headers = {
+      ...this.config.defaultHeaders,
+      ...this.authHeaders,
+      ...options?.headers
+    };
+    if (options?.body && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await this.fetchFn(url.toString(), {
+      method,
+      headers,
+      body: options?.body ? JSON.stringify(options.body) : undefined,
+      signal: options?.signal
+    });
+    const responseHeaders = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+    const data = await response.json().catch(() => null);
+    let rateLimitRemaining;
+    let rateLimitReset;
+    if (this.config.rateLimitHeaders) {
+      const remaining = responseHeaders[this.config.rateLimitHeaders.remaining];
+      const reset = responseHeaders[this.config.rateLimitHeaders.reset];
+      if (remaining)
+        rateLimitRemaining = Number(remaining);
+      if (reset)
+        rateLimitReset = Number(reset);
+    }
+    return {
+      data,
+      status: response.status,
+      headers: responseHeaders,
+      rateLimitRemaining,
+      rateLimitReset
+    };
+  }
+}
+function createTransportClient(transports, targetType, authHeaders = {}, fetchFn) {
+  const config = findTransportConfig(transports, targetType);
+  if (!config)
+    return;
+  switch (config.type) {
+    case "rest":
+      return new RestTransportClient(config, authHeaders, fetchFn);
+    case "mcp":
+    case "webhook":
+    case "sdk":
+      return;
+    default:
+      return;
+  }
+}
+
+// src/transport/auth-resolver.ts
+import { findAuthConfig } from "@contractspec/lib.contracts-integrations/integrations/auth";
+import {
+  buildAuthHeaders,
+  refreshOAuth2Token,
+  isOAuth2TokenExpired
+} from "@contractspec/lib.contracts-integrations/integrations/auth-helpers";
+async function resolveAuth(options) {
+  const authConfig = findAuthConfig(options.supportedAuthMethods, options.activeAuthMethod);
+  if (!authConfig) {
+    return { headers: {}, tokenRefreshed: false };
+  }
+  if (authConfig.type === "oauth2" && options.oauth2State) {
+    if (isOAuth2TokenExpired(options.oauth2State)) {
+      const clientId = options.secrets.clientId ?? "";
+      const clientSecret = options.secrets.clientSecret ?? "";
+      try {
+        const newState = await refreshOAuth2Token(authConfig, options.oauth2State, { clientId, clientSecret }, options.fetchFn);
+        const mergedSecrets2 = {
+          ...options.secrets,
+          accessToken: newState.accessToken
+        };
+        return {
+          headers: buildAuthHeaders(authConfig, mergedSecrets2),
+          tokenRefreshed: true,
+          updatedOAuth2State: newState
+        };
+      } catch {
+        return {
+          headers: buildAuthHeaders(authConfig, options.secrets),
+          tokenRefreshed: false
+        };
+      }
+    }
+    const mergedSecrets = {
+      ...options.secrets,
+      accessToken: options.oauth2State.accessToken
+    };
+    return {
+      headers: buildAuthHeaders(authConfig, mergedSecrets),
+      tokenRefreshed: false
+    };
+  }
+  return {
+    headers: buildAuthHeaders(authConfig, options.secrets),
+    tokenRefreshed: false
+  };
+}
+
+// src/transport/version-negotiator.ts
+import {
+  resolveApiVersion,
+  isVersionDeprecated
+} from "@contractspec/lib.contracts-integrations/integrations/versioning";
+function negotiateVersion(policy, connectionOverride) {
+  if (!policy) {
+    return {
+      resolvedVersion: undefined,
+      deprecated: false,
+      versionHeaders: {},
+      versionQueryParams: {}
+    };
+  }
+  const version = resolveApiVersion(policy, connectionOverride);
+  const deprecated = version ? isVersionDeprecated(policy, version) : false;
+  const versionHeaders = {};
+  const versionQueryParams = {};
+  if (version) {
+    if (policy.versionHeader) {
+      versionHeaders[policy.versionHeader] = version;
+    }
+    if (policy.versionQueryParam) {
+      versionQueryParams[policy.versionQueryParam] = version;
+    }
+  }
+  return {
+    resolvedVersion: version,
+    deprecated,
+    versionHeaders,
+    versionQueryParams
+  };
+}
+export {
+  resolveAuth,
+  negotiateVersion,
+  createTransportClient,
+  RestTransportClient
+};

package/dist/node/transport/transport-factory.js

@@ -0,0 +1,77 @@
+// src/transport/transport-factory.ts
+import { findTransportConfig } from "@contractspec/lib.contracts-integrations/integrations/transport";
+
+class RestTransportClient {
+  config;
+  authHeaders;
+  fetchFn;
+  type = "rest";
+  constructor(config, authHeaders = {}, fetchFn = globalThis.fetch) {
+    this.config = config;
+    this.authHeaders = authHeaders;
+    this.fetchFn = fetchFn;
+  }
+  async request(method, path, options) {
+    const url = new URL(path, this.config.baseUrl ?? "https://localhost");
+    if (options?.queryParams) {
+      for (const [key, value] of Object.entries(options.queryParams)) {
+        url.searchParams.set(key, value);
+      }
+    }
+    const headers = {
+      ...this.config.defaultHeaders,
+      ...this.authHeaders,
+      ...options?.headers
+    };
+    if (options?.body && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await this.fetchFn(url.toString(), {
+      method,
+      headers,
+      body: options?.body ? JSON.stringify(options.body) : undefined,
+      signal: options?.signal
+    });
+    const responseHeaders = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+    const data = await response.json().catch(() => null);
+    let rateLimitRemaining;
+    let rateLimitReset;
+    if (this.config.rateLimitHeaders) {
+      const remaining = responseHeaders[this.config.rateLimitHeaders.remaining];
+      const reset = responseHeaders[this.config.rateLimitHeaders.reset];
+      if (remaining)
+        rateLimitRemaining = Number(remaining);
+      if (reset)
+        rateLimitReset = Number(reset);
+    }
+    return {
+      data,
+      status: response.status,
+      headers: responseHeaders,
+      rateLimitRemaining,
+      rateLimitReset
+    };
+  }
+}
+function createTransportClient(transports, targetType, authHeaders = {}, fetchFn) {
+  const config = findTransportConfig(transports, targetType);
+  if (!config)
+    return;
+  switch (config.type) {
+    case "rest":
+      return new RestTransportClient(config, authHeaders, fetchFn);
+    case "mcp":
+    case "webhook":
+    case "sdk":
+      return;
+    default:
+      return;
+  }
+}
+export {
+  createTransportClient,
+  RestTransportClient
+};

package/dist/node/transport/version-negotiator.js

@@ -0,0 +1,36 @@
+// src/transport/version-negotiator.ts
+import {
+  resolveApiVersion,
+  isVersionDeprecated
+} from "@contractspec/lib.contracts-integrations/integrations/versioning";
+function negotiateVersion(policy, connectionOverride) {
+  if (!policy) {
+    return {
+      resolvedVersion: undefined,
+      deprecated: false,
+      versionHeaders: {},
+      versionQueryParams: {}
+    };
+  }
+  const version = resolveApiVersion(policy, connectionOverride);
+  const deprecated = version ? isVersionDeprecated(policy, version) : false;
+  const versionHeaders = {};
+  const versionQueryParams = {};
+  if (version) {
+    if (policy.versionHeader) {
+      versionHeaders[policy.versionHeader] = version;
+    }
+    if (policy.versionQueryParam) {
+      versionQueryParams[policy.versionQueryParam] = version;
+    }
+  }
+  return {
+    resolvedVersion: version,
+    deprecated,
+    versionHeaders,
+    versionQueryParams
+  };
+}
+export {
+  negotiateVersion
+};

package/dist/runtime.d.ts

@@ -101,3 +101,19 @@ export declare function resolveHealthStrategyOrder(options?: HealthRuntimeStrate
 export declare function isUnofficialHealthProviderAllowed(providerKey: string, options?: HealthRuntimeStrategyOptions): boolean;
 export declare function ensureConnectionReady(integration: ResolvedIntegration): void;
 export declare function connectionStatusLabel(status: ConnectionStatus): string;
+/**
+ * Optional Composio fallback configuration.
+ * When present, the IntegrationProviderFactory will delegate unsupported
+ * integration keys to Composio's 850+ toolkit catalog.
+ */
+export interface ComposioRuntimeConfig {
+    apiKey: string;
+    baseUrl?: string;
+    preferredTransport?: 'mcp' | 'sdk';
+}
+export interface IntegrationRuntimeConfig {
+    secretProvider: SecretProvider;
+    telemetry?: IntegrationTelemetryEmitter;
+    healthStrategy?: HealthRuntimeStrategyOptions;
+    composio?: ComposioRuntimeConfig;
+}

package/dist/runtime.health.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transport/auth-resolver.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolves authentication credentials for an integration connection.
+ */
+import type { IntegrationAuthConfig, IntegrationAuthType, OAuth2TokenState } from '@contractspec/lib.contracts-integrations/integrations/auth';
+export interface AuthResolutionResult {
+    headers: Record<string, string>;
+    tokenRefreshed: boolean;
+    updatedOAuth2State?: OAuth2TokenState;
+}
+export interface AuthResolverOptions {
+    supportedAuthMethods: IntegrationAuthConfig[];
+    activeAuthMethod: IntegrationAuthType;
+    secrets: Record<string, string>;
+    oauth2State?: OAuth2TokenState;
+    fetchFn?: typeof globalThis.fetch;
+}
+/**
+ * Resolve auth headers, refreshing OAuth2 tokens if needed.
+ */
+export declare function resolveAuth(options: AuthResolverOptions): Promise<AuthResolutionResult>;

package/dist/transport/auth-resolver.js

@@ -0,0 +1,52 @@
+// @bun
+// src/transport/auth-resolver.ts
+import { findAuthConfig } from "@contractspec/lib.contracts-integrations/integrations/auth";
+import {
+  buildAuthHeaders,
+  refreshOAuth2Token,
+  isOAuth2TokenExpired
+} from "@contractspec/lib.contracts-integrations/integrations/auth-helpers";
+async function resolveAuth(options) {
+  const authConfig = findAuthConfig(options.supportedAuthMethods, options.activeAuthMethod);
+  if (!authConfig) {
+    return { headers: {}, tokenRefreshed: false };
+  }
+  if (authConfig.type === "oauth2" && options.oauth2State) {
+    if (isOAuth2TokenExpired(options.oauth2State)) {
+      const clientId = options.secrets.clientId ?? "";
+      const clientSecret = options.secrets.clientSecret ?? "";
+      try {
+        const newState = await refreshOAuth2Token(authConfig, options.oauth2State, { clientId, clientSecret }, options.fetchFn);
+        const mergedSecrets2 = {
+          ...options.secrets,
+          accessToken: newState.accessToken
+        };
+        return {
+          headers: buildAuthHeaders(authConfig, mergedSecrets2),
+          tokenRefreshed: true,
+          updatedOAuth2State: newState
+        };
+      } catch {
+        return {
+          headers: buildAuthHeaders(authConfig, options.secrets),
+          tokenRefreshed: false
+        };
+      }
+    }
+    const mergedSecrets = {
+      ...options.secrets,
+      accessToken: options.oauth2State.accessToken
+    };
+    return {
+      headers: buildAuthHeaders(authConfig, mergedSecrets),
+      tokenRefreshed: false
+    };
+  }
+  return {
+    headers: buildAuthHeaders(authConfig, options.secrets),
+    tokenRefreshed: false
+  };
+}
+export {
+  resolveAuth
+};

package/dist/transport/index.d.ts

@@ -0,0 +1,3 @@
+export * from './transport-factory';
+export * from './auth-resolver';
+export * from './version-negotiator';

package/dist/transport/index.js

@@ -0,0 +1,163 @@
+// @bun
+// src/transport/transport-factory.ts
+import { findTransportConfig } from "@contractspec/lib.contracts-integrations/integrations/transport";
+
+class RestTransportClient {
+  config;
+  authHeaders;
+  fetchFn;
+  type = "rest";
+  constructor(config, authHeaders = {}, fetchFn = globalThis.fetch) {
+    this.config = config;
+    this.authHeaders = authHeaders;
+    this.fetchFn = fetchFn;
+  }
+  async request(method, path, options) {
+    const url = new URL(path, this.config.baseUrl ?? "https://localhost");
+    if (options?.queryParams) {
+      for (const [key, value] of Object.entries(options.queryParams)) {
+        url.searchParams.set(key, value);
+      }
+    }
+    const headers = {
+      ...this.config.defaultHeaders,
+      ...this.authHeaders,
+      ...options?.headers
+    };
+    if (options?.body && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await this.fetchFn(url.toString(), {
+      method,
+      headers,
+      body: options?.body ? JSON.stringify(options.body) : undefined,
+      signal: options?.signal
+    });
+    const responseHeaders = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+    const data = await response.json().catch(() => null);
+    let rateLimitRemaining;
+    let rateLimitReset;
+    if (this.config.rateLimitHeaders) {
+      const remaining = responseHeaders[this.config.rateLimitHeaders.remaining];
+      const reset = responseHeaders[this.config.rateLimitHeaders.reset];
+      if (remaining)
+        rateLimitRemaining = Number(remaining);
+      if (reset)
+        rateLimitReset = Number(reset);
+    }
+    return {
+      data,
+      status: response.status,
+      headers: responseHeaders,
+      rateLimitRemaining,
+      rateLimitReset
+    };
+  }
+}
+function createTransportClient(transports, targetType, authHeaders = {}, fetchFn) {
+  const config = findTransportConfig(transports, targetType);
+  if (!config)
+    return;
+  switch (config.type) {
+    case "rest":
+      return new RestTransportClient(config, authHeaders, fetchFn);
+    case "mcp":
+    case "webhook":
+    case "sdk":
+      return;
+    default:
+      return;
+  }
+}
+
+// src/transport/auth-resolver.ts
+import { findAuthConfig } from "@contractspec/lib.contracts-integrations/integrations/auth";
+import {
+  buildAuthHeaders,
+  refreshOAuth2Token,
+  isOAuth2TokenExpired
+} from "@contractspec/lib.contracts-integrations/integrations/auth-helpers";
+async function resolveAuth(options) {
+  const authConfig = findAuthConfig(options.supportedAuthMethods, options.activeAuthMethod);
+  if (!authConfig) {
+    return { headers: {}, tokenRefreshed: false };
+  }
+  if (authConfig.type === "oauth2" && options.oauth2State) {
+    if (isOAuth2TokenExpired(options.oauth2State)) {
+      const clientId = options.secrets.clientId ?? "";
+      const clientSecret = options.secrets.clientSecret ?? "";
+      try {
+        const newState = await refreshOAuth2Token(authConfig, options.oauth2State, { clientId, clientSecret }, options.fetchFn);
+        const mergedSecrets2 = {
+          ...options.secrets,
+          accessToken: newState.accessToken
+        };
+        return {
+          headers: buildAuthHeaders(authConfig, mergedSecrets2),
+          tokenRefreshed: true,
+          updatedOAuth2State: newState
+        };
+      } catch {
+        return {
+          headers: buildAuthHeaders(authConfig, options.secrets),
+          tokenRefreshed: false
+        };
+      }
+    }
+    const mergedSecrets = {
+      ...options.secrets,
+      accessToken: options.oauth2State.accessToken
+    };
+    return {
+      headers: buildAuthHeaders(authConfig, mergedSecrets),
+      tokenRefreshed: false
+    };
+  }
+  return {
+    headers: buildAuthHeaders(authConfig, options.secrets),
+    tokenRefreshed: false
+  };
+}
+
+// src/transport/version-negotiator.ts
+import {
+  resolveApiVersion,
+  isVersionDeprecated
+} from "@contractspec/lib.contracts-integrations/integrations/versioning";
+function negotiateVersion(policy, connectionOverride) {
+  if (!policy) {
+    return {
+      resolvedVersion: undefined,
+      deprecated: false,
+      versionHeaders: {},
+      versionQueryParams: {}
+    };
+  }
+  const version = resolveApiVersion(policy, connectionOverride);
+  const deprecated = version ? isVersionDeprecated(policy, version) : false;
+  const versionHeaders = {};
+  const versionQueryParams = {};
+  if (version) {
+    if (policy.versionHeader) {
+      versionHeaders[policy.versionHeader] = version;
+    }
+    if (policy.versionQueryParam) {
+      versionQueryParams[policy.versionQueryParam] = version;
+    }
+  }
+  return {
+    resolvedVersion: version,
+    deprecated,
+    versionHeaders,
+    versionQueryParams
+  };
+}
+export {
+  resolveAuth,
+  negotiateVersion,
+  createTransportClient,
+  RestTransportClient
+};

package/dist/transport/transport-factory.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Factory for creating transport clients from integration transport configs.
+ */
+import type { IntegrationTransportConfig, IntegrationTransportType, RestTransportConfig } from '@contractspec/lib.contracts-integrations/integrations/transport';
+export interface TransportClient {
+    readonly type: IntegrationTransportType;
+    request<T>(method: string, path: string, options?: TransportRequestOptions): Promise<TransportResponse<T>>;
+}
+export interface TransportRequestOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+    queryParams?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface TransportResponse<T> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+    rateLimitRemaining?: number;
+    rateLimitReset?: number;
+}
+export declare class RestTransportClient implements TransportClient {
+    private readonly config;
+    private readonly authHeaders;
+    private readonly fetchFn;
+    readonly type: "rest";
+    constructor(config: RestTransportConfig, authHeaders?: Record<string, string>, fetchFn?: typeof globalThis.fetch);
+    request<T>(method: string, path: string, options?: TransportRequestOptions): Promise<TransportResponse<T>>;
+}
+export declare function createTransportClient(transports: IntegrationTransportConfig[], targetType: IntegrationTransportType, authHeaders?: Record<string, string>, fetchFn?: typeof globalThis.fetch): TransportClient | undefined;