@barndoor-ai/sdk 0.2.0

package/src/http/client.ts

@@ -0,0 +1,272 @@
+/**
+ * HTTP client with retry logic and error handling.
+ *
+ * This module provides a robust HTTP client that mirrors the Python SDK's
+ * HTTP client functionality, including automatic retries, timeout handling,
+ * and proper error conversion.
+ */
+
+import { HTTPError, ConnectionError, TimeoutError } from '../exceptions';
+
+/**
+ * HTTP request options interface.
+ */
+export interface HTTPRequestOptions {
+  /** Request headers */
+  headers?: Record<string, string>;
+  /** JSON body to send */
+  json?: unknown;
+  /** Query parameters */
+  params?: Record<string, string | number | boolean>;
+  /** Additional fetch options */
+  [key: string]: unknown;
+}
+
+/**
+ * Timeout configuration for HTTP requests.
+ */
+export class TimeoutConfig {
+  /** Read timeout in milliseconds */
+  public readonly read: number;
+  /** Connect timeout in milliseconds */
+  public readonly connect: number;
+
+  /**
+   * Create a new TimeoutConfig.
+   * @param read - Read timeout in seconds
+   * @param connect - Connect timeout in seconds
+   */
+  constructor(read = 30, connect = 10) {
+    this.read = read * 1000; // Convert to milliseconds
+    this.connect = connect * 1000; // Convert to milliseconds
+  }
+}
+
+/**
+ * HTTP client with automatic retries and error handling.
+ *
+ * Provides a consistent interface for making HTTP requests with proper
+ * error handling, timeout management, and retry logic.
+ */
+export class HTTPClient {
+  /** Timeout configuration */
+  private readonly timeoutConfig: TimeoutConfig;
+  /** Maximum number of retries */
+  private readonly maxRetries: number;
+  /** Whether the client has been closed */
+  public closed: boolean;
+
+  /**
+   * Create a new HTTPClient.
+   * @param timeoutConfig - Timeout configuration
+   * @param maxRetries - Maximum number of retries
+   */
+  constructor(timeoutConfig = new TimeoutConfig(), maxRetries = 3) {
+    this.timeoutConfig = timeoutConfig;
+    this.maxRetries = maxRetries;
+    this.closed = false;
+  }
+
+  /**
+   * Make an HTTP request with retry logic.
+   * @param method - HTTP method
+   * @param url - Request URL
+   * @param options - Request options
+   * @returns Response data
+   */
+  public async request(
+    method: string,
+    url: string,
+    options: HTTPRequestOptions = {}
+  ): Promise<unknown> {
+    if (this.closed) {
+      throw new Error('HTTP client has been closed');
+    }
+
+    const { headers = {}, json, params, ...fetchOptions } = options;
+
+    // Build URL with query parameters
+    const requestUrl = this._buildUrl(url, params);
+
+    // Prepare request options
+    const requestOptions: RequestInit = {
+      method: method.toUpperCase(),
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'barndoor-js-sdk/0.1.0',
+        ...headers,
+      },
+      ...fetchOptions,
+    };
+
+    // Add request body if provided
+    if (json) {
+      requestOptions.body = JSON.stringify(json);
+    }
+
+    let lastError: Error | undefined;
+
+    // Retry loop
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      // Create fresh AbortController and timeout for each attempt
+      const controller = new AbortController();
+
+      // Set up overall request timeout (covers both connection and read)
+      const totalTimeout = this.timeoutConfig.connect + this.timeoutConfig.read;
+      const timeoutId = setTimeout(() => controller.abort(), totalTimeout);
+
+      // Update signal for this attempt
+      const attemptOptions = { ...requestOptions, signal: controller.signal };
+
+      try {
+        const response = await globalThis.fetch!(requestUrl, attemptOptions as RequestInit);
+        clearTimeout(timeoutId);
+
+        // Handle HTTP errors
+        if (!response.ok) {
+          let responseText = '';
+          try {
+            const respAny: any = response as any;
+            if (typeof respAny.text === 'function') {
+              responseText = await respAny.text();
+            } else if (typeof respAny.json === 'function') {
+              // Fallback to JSON serialization if text() is not available on mocks
+              responseText = JSON.stringify(await respAny.json());
+            }
+          } catch {
+            // ignore parse errors, keep empty responseText
+          }
+          throw new HTTPError(response.status, response.statusText, responseText);
+        }
+
+        // Parse response based on Content-Type with robust fallbacks for test mocks
+        let contentType = '';
+        const respAny: any = response as any;
+        const headersObj: any = respAny && respAny.headers;
+        if (headersObj) {
+          if (typeof headersObj.get === 'function') {
+            contentType = headersObj.get('content-type') || headersObj.get('Content-Type') || '';
+          } else if (typeof headersObj === 'object') {
+            contentType = headersObj['content-type'] || headersObj['Content-Type'] || '';
+          }
+        }
+
+        let responseData: unknown;
+        if (
+          contentType.includes('application/json') ||
+          (!contentType && typeof respAny.json === 'function')
+        ) {
+          responseData = await response.json();
+        } else if (
+          contentType.includes('text/') ||
+          (!contentType && typeof respAny.text === 'function')
+        ) {
+          responseData = await response.text();
+        } else if (typeof respAny.arrayBuffer === 'function') {
+          // For binary data or unknown types, return as ArrayBuffer
+          responseData = await response.arrayBuffer();
+        } else {
+          // Last resort: return the raw response object
+          responseData = response as unknown;
+        }
+
+        return responseData;
+      } catch (error: unknown) {
+        clearTimeout(timeoutId);
+
+        // Handle different types of errors
+        if (error instanceof Error && error.name === 'AbortError') {
+          const totalTimeout = this.timeoutConfig.connect + this.timeoutConfig.read;
+          lastError = new TimeoutError(
+            `Request to ${requestUrl} timed out after ${totalTimeout}ms`
+          );
+        } else if (error instanceof HTTPError) {
+          // Distinguish retryable 5xx from non-retryable 4xx errors
+          if (error.statusCode >= 400 && error.statusCode < 500) {
+            // 4xx errors are client errors - don't retry
+            throw error;
+          } else if (error.statusCode >= 500 && error.statusCode < 600) {
+            // Retry 5xx errors only for idempotent methods (GET, HEAD, OPTIONS)
+            const methodUpper = method.toUpperCase();
+            const isIdempotent =
+              methodUpper === 'GET' || methodUpper === 'HEAD' || methodUpper === 'OPTIONS';
+            if (isIdempotent) {
+              lastError = error;
+            } else {
+              throw error;
+            }
+          } else {
+            // Other HTTP errors - don't retry
+            throw error;
+          }
+        } else if (
+          error instanceof Error &&
+          error.name === 'TypeError' &&
+          error.message.includes('fetch')
+        ) {
+          lastError = new ConnectionError(requestUrl, error);
+        } else {
+          lastError = error instanceof Error ? error : new Error(String(error));
+        }
+
+        // Don't retry on the last attempt
+        if (attempt === this.maxRetries) {
+          break;
+        }
+
+        // Wait before retrying (exponential backoff)
+        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
+        await this._sleep(delay);
+      }
+    }
+
+    // Ensure we always have an error to throw
+    if (!lastError) {
+      lastError = new Error(
+        `Request to ${requestUrl} failed after ${this.maxRetries + 1} attempts with no specific error`
+      );
+    }
+    throw lastError;
+  }
+
+  /**
+   * Build URL with query parameters.
+   * @private
+   */
+  private _buildUrl(baseUrl: string, params?: Record<string, string | number | boolean>): string {
+    if (!params || Object.keys(params).length === 0) {
+      return baseUrl;
+    }
+
+    const url = new URL(baseUrl);
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== null && value !== undefined) {
+        url.searchParams.append(key, String(value));
+      }
+    });
+
+    return url.toString();
+  }
+
+  /**
+   * Sleep for the specified number of milliseconds.
+   * @private
+   */
+  private _sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Close the HTTP client and clean up resources.
+   */
+  public async close(): Promise<void> {
+    this.closed = true;
+  }
+
+  /**
+   * Alias for close() to match Python SDK naming.
+   */
+  public async aclose(): Promise<void> {
+    await this.close();
+  }
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * Barndoor SDK - JavaScript client for the Barndoor Platform API.
+ *
+ * The Barndoor SDK provides a simple, async interface for interacting with
+ * the Barndoor platform, including:
+ *
+ * - User authentication and token management
+ * - MCP server discovery and connection
+ * - OAuth flow handling for third-party integrations
+ * - Agent credential exchange
+ *
+ * Quick Start
+ * -----------
+ * ```javascript
+ * import { BarndoorSDK } from '@barndoor/sdk';
+ *
+ * const sdk = new BarndoorSDK('https://api.barndoor.host', {
+ *   token: 'your_token'
+ * });
+ * const servers = await sdk.listServers();
+ * ```
+ *
+ * For interactive login:
+ * ```javascript
+ * import { loginInteractive } from '@barndoor/sdk';
+ *
+ * const sdk = await loginInteractive();
+ * ```
+ */
+
+// Main SDK class
+export { BarndoorSDK } from './client';
+
+// Exception classes
+export {
+  BarndoorError,
+  AuthenticationError,
+  TokenError,
+  TokenExpiredError,
+  TokenValidationError,
+  ConnectionError,
+  HTTPError,
+  ServerNotFoundError,
+  OAuthError,
+  ConfigurationError,
+  TimeoutError,
+} from './exceptions';
+
+// Data models
+export { ServerSummary, ServerDetail, AgentToken } from './models';
+
+// Quick-start helpers
+export {
+  loginInteractive,
+  ensureServerConnected,
+  makeMcpConnectionParams,
+  makeMcpClient,
+} from './quickstart';
+
+// Authentication utilities
+export {
+  PKCEManager,
+  startLocalCallbackServer,
+  loadUserToken,
+  saveUserToken,
+  clearCachedToken,
+  verifyJWTLocal,
+  JWTVerificationResult,
+  isTokenActive,
+  isTokenActiveWithRefresh,
+  validateToken,
+  TokenManager,
+  setTokenLogger,
+} from './auth';
+
+// Configuration
+export {
+  BarndoorConfig,
+  getStaticConfig,
+  getDynamicConfig,
+  checkTokenOrganization,
+  hasOrganizationInfo,
+  isBrowser,
+  isNode,
+} from './config';
+
+// Logging
+export { setLogger, getLogger, createScopedLogger, debug, info, warn, error } from './logging';
+export type { Logger } from './logging';
+
+// Version
+export { version } from './version';

package/src/logging.ts

@@ -0,0 +1,111 @@
+/**
+ * Unified logging system for the Barndoor SDK.
+ *
+ * This module provides a centralized logging interface that can be configured
+ * by SDK consumers to integrate with their preferred logging systems.
+ */
+
+/**
+ * Logger interface for SDK consumers to plug their own logger.
+ */
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Default console logger implementation.
+ */
+const defaultLogger: Logger = {
+  debug: (message: string, ...args: unknown[]) => {
+    if (typeof console !== 'undefined' && console.debug) {
+      console.debug(message, ...args);
+    }
+  },
+  info: (message: string, ...args: unknown[]) => {
+    if (typeof console !== 'undefined' && console.info) {
+      console.info(message, ...args);
+    }
+  },
+  warn: (message: string, ...args: unknown[]) => {
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn(message, ...args);
+    }
+  },
+  error: (message: string, ...args: unknown[]) => {
+    if (typeof console !== 'undefined' && console.error) {
+      console.error(message, ...args);
+    }
+  },
+};
+
+// Global logger instance that can be configured
+let _logger: Logger = defaultLogger;
+
+/**
+ * Set a custom logger for the entire SDK.
+ * @param logger - Custom logger implementation
+ */
+export function setLogger(logger: Logger): void {
+  _logger = logger;
+}
+
+/**
+ * Get the current logger instance.
+ * @returns Current logger
+ */
+export function getLogger(): Logger {
+  return _logger;
+}
+
+/**
+ * Create a scoped logger with a prefix for better organization.
+ * @param scope - Scope name (e.g., 'client', 'auth', 'http')
+ * @returns Scoped logger
+ */
+export function createScopedLogger(scope: string): Logger {
+  return {
+    debug: (message: string, ...args: unknown[]) => {
+      _logger.debug(`[${scope}] ${message}`, ...args);
+    },
+    info: (message: string, ...args: unknown[]) => {
+      _logger.info(`[${scope}] ${message}`, ...args);
+    },
+    warn: (message: string, ...args: unknown[]) => {
+      _logger.warn(`[${scope}] ${message}`, ...args);
+    },
+    error: (message: string, ...args: unknown[]) => {
+      _logger.error(`[${scope}] ${message}`, ...args);
+    },
+  };
+}
+
+/**
+ * Convenience function to log debug messages.
+ */
+export function debug(message: string, ...args: unknown[]): void {
+  _logger.debug(message, ...args);
+}
+
+/**
+ * Convenience function to log info messages.
+ */
+export function info(message: string, ...args: unknown[]): void {
+  _logger.info(message, ...args);
+}
+
+/**
+ * Convenience function to log warning messages.
+ */
+export function warn(message: string, ...args: unknown[]): void {
+  _logger.warn(message, ...args);
+}
+
+/**
+ * Convenience function to log error messages.
+ */
+export function error(message: string, ...args: unknown[]): void {
+  _logger.error(message, ...args);
+}

package/src/models/index.ts

@@ -0,0 +1,156 @@
+/**
+ * Data models for the Barndoor SDK.
+ *
+ * This module defines the data models used for API requests and responses,
+ * providing type safety and validation that mirrors the Python SDK's Pydantic models.
+ */
+
+/**
+ * Connection status for MCP servers.
+ */
+export type ConnectionStatus = 'available' | 'pending' | 'connected';
+
+/**
+ * Raw server data from API responses.
+ */
+export interface ServerSummaryData {
+  /** Unique identifier (UUID) for the server */
+  id: string;
+  /** Human-readable name of the server */
+  name: string;
+  /** URL-friendly identifier used in API paths */
+  slug: string;
+  /** Third-party provider name (e.g., "github", "slack") */
+  provider?: string | null;
+  /** Current connection status */
+  connection_status: ConnectionStatus;
+}
+
+/**
+ * Summary information about an MCP server.
+ *
+ * Represents basic server information as returned by the list servers
+ * endpoint. This is a lightweight representation suitable for listing
+ * many servers at once.
+ */
+export class ServerSummary {
+  /** Unique identifier (UUID) for the server */
+  public readonly id: string;
+  /** Human-readable name of the server */
+  public readonly name: string;
+  /** URL-friendly identifier used in API paths */
+  public readonly slug: string;
+  /** Third-party provider name (e.g., "github", "slack") */
+  public readonly provider: string | null;
+  /** Current connection status */
+  public readonly connection_status: ConnectionStatus;
+
+  /**
+   * Create a new ServerSummary instance.
+   * @param data - Server data from API response
+   */
+  constructor(data: ServerSummaryData) {
+    this.id = data.id;
+    this.name = data.name;
+    this.slug = data.slug;
+    this.provider = data.provider ?? null;
+    this.connection_status = data.connection_status;
+
+    // Validate required fields
+    if (!this.id || !this.name || !this.slug || !this.connection_status) {
+      throw new Error('ServerSummary missing required fields');
+    }
+  }
+
+  /**
+   * Create a ServerSummary from API response data.
+   * @param data - Raw API response data
+   * @returns ServerSummary instance
+   */
+  public static fromApiResponse(data: unknown): ServerSummary {
+    return new ServerSummary(data as ServerSummaryData);
+  }
+}
+
+/**
+ * Raw server detail data from API responses.
+ */
+export interface ServerDetailData extends ServerSummaryData {
+  /** MCP base URL from the server directory */
+  url?: string | null;
+}
+
+/**
+ * Detailed information about an MCP server.
+ *
+ * Extends ServerSummary with additional fields returned when fetching
+ * a single server's details.
+ */
+export class ServerDetail extends ServerSummary {
+  /** MCP base URL from the server directory */
+  public readonly url: string | null;
+
+  /**
+   * Create a new ServerDetail instance.
+   * @param data - Server data from API response
+   */
+  constructor(data: ServerDetailData) {
+    super(data);
+    this.url = data.url ?? null;
+  }
+
+  /**
+   * Create a ServerDetail from API response data.
+   * @param data - Raw API response data
+   * @returns ServerDetail instance
+   */
+  public static override fromApiResponse(data: unknown): ServerDetail {
+    return new ServerDetail(data as ServerDetailData);
+  }
+}
+
+/**
+ * Raw agent token data from API responses.
+ */
+export interface AgentTokenData {
+  /** The agent access token to use for agent operations */
+  agent_token: string;
+  /** Token lifetime in seconds */
+  expires_in: number;
+}
+
+/**
+ * Response from the agent token exchange endpoint.
+ *
+ * Contains the agent access token and expiration information returned
+ * when exchanging client credentials.
+ */
+export class AgentToken {
+  /** The agent access token to use for agent operations */
+  public readonly agent_token: string;
+  /** Token lifetime in seconds */
+  public readonly expires_in: number;
+
+  /**
+   * Create a new AgentToken instance.
+   * @param data - Token data from API response
+   */
+  constructor(data: AgentTokenData) {
+    this.agent_token = data.agent_token;
+    this.expires_in = data.expires_in;
+
+    // Validate required fields
+    if (!this.agent_token || typeof this.expires_in !== 'number') {
+      throw new Error('AgentToken missing required fields');
+    }
+  }
+
+  /**
+   * Create an AgentToken from API response data.
+   * @param data - Raw API response data
+   * @returns AgentToken instance
+   */
+  public static fromApiResponse(data: unknown): AgentToken {
+    return new AgentToken(data as AgentTokenData);
+  }
+}