@barndoor-ai/sdk 0.2.0

package/src/config.ts

@@ -0,0 +1,402 @@
+/**
+ * Configuration management for the Barndoor SDK.
+ *
+ * This module provides unified configuration that mirrors the Python SDK's
+ * configuration system, supporting environment-specific defaults and
+ * dynamic organization ID substitution.
+ */
+
+import { ConfigurationError } from './exceptions';
+
+/**
+ * Environment detection utilities
+ *
+ * Improved detection that works correctly under bundlers where process gets shimmed.
+ * We check for window first since that's the most reliable browser indicator.
+ */
+export const isBrowser: boolean =
+  typeof window !== 'undefined' && typeof window.document !== 'undefined';
+export const isNode: boolean =
+  typeof window === 'undefined' &&
+  typeof process !== 'undefined' &&
+  process.versions != null &&
+  process.versions.node != null;
+
+/**
+ * Browser window with optional ENV object for environment variables.
+ */
+declare global {
+  interface Window {
+    ENV?: Record<string, string>;
+  }
+}
+
+/**
+ * Configuration options for BarndoorConfig constructor.
+ */
+export interface BarndoorConfigOptions {
+  /** Auth0 domain */
+  authDomain?: string;
+  /** OAuth client ID */
+  clientId?: string;
+  /** OAuth client secret */
+  clientSecret?: string;
+  /** API audience identifier */
+  apiAudience?: string;
+  /** API base URL template */
+  apiBaseUrl?: string;
+  /** MCP base URL template */
+  mcpBaseUrl?: string;
+  /** Environment name */
+  environment?: string;
+  /** Whether to prompt for login */
+  promptForLogin?: boolean;
+  /** Whether to skip login in local environment */
+  skipLoginLocal?: boolean;
+}
+
+/**
+ * Get environment variable value (works in both Node.js and browser)
+ */
+function getEnvVar(name: string, defaultValue = ''): string {
+  if (isNode) {
+    return process.env[name] ?? defaultValue;
+  } else if (isBrowser && window.ENV) {
+    // Browser environment with injected ENV object
+    return window.ENV[name] ?? defaultValue;
+  }
+  return defaultValue;
+}
+
+/**
+ * Unified configuration for the Barndoor SDK.
+ *
+ * Mirrors the Python SDK's BarndoorConfig class with environment-specific
+ * defaults and support for organization ID templating.
+ */
+export class BarndoorConfig {
+  /** Auth0 domain */
+  public authDomain: string;
+  /** OAuth client ID */
+  public clientId: string;
+  /** OAuth client secret */
+  public clientSecret: string;
+  /** API audience identifier */
+  public apiAudience: string;
+  /** API base URL template */
+  public apiBaseUrl: string;
+  /** MCP base URL template */
+  public mcpBaseUrl: string;
+  /** Environment name */
+  public environment: string;
+  /** Whether to prompt for login */
+  public promptForLogin: boolean;
+  /** Whether to skip login in local environment */
+  public skipLoginLocal: boolean;
+
+  /**
+   * Create a new BarndoorConfig instance.
+   * @param options - Configuration options
+   */
+  constructor(options: BarndoorConfigOptions = {}) {
+    // Authentication settings
+    this.authDomain = options.authDomain ?? (getEnvVar('AUTH_DOMAIN') || 'auth.barndoor.ai');
+    this.clientId = options.clientId ?? (getEnvVar('AGENT_CLIENT_ID') || '');
+    this.clientSecret = options.clientSecret ?? (getEnvVar('AGENT_CLIENT_SECRET') || '');
+    this.apiAudience = options.apiAudience ?? (getEnvVar('API_AUDIENCE') || 'https://barndoor.ai/');
+
+    // Environment settings
+    this.environment =
+      options.environment ?? (getEnvVar('MODE') || getEnvVar('BARNDOOR_ENV') || 'production');
+
+    // Runtime settings
+    this.promptForLogin = options.promptForLogin ?? false;
+    this.skipLoginLocal = options.skipLoginLocal ?? false;
+
+    // Initialize URL properties (will be set by _setEnvironmentDefaults)
+    this.apiBaseUrl = '';
+    this.mcpBaseUrl = '';
+
+    // Set environment-specific defaults
+    this._setEnvironmentDefaults(options);
+  }
+
+  /**
+   * Set environment-specific default URLs.
+   * @private
+   */
+  private _setEnvironmentDefaults(options: BarndoorConfigOptions): void {
+    const env = this.environment.toLowerCase();
+
+    if (env === 'localdev' || env === 'local') {
+      this.authDomain = this.authDomain || 'localhost:3001';
+      this.apiBaseUrl =
+        options.apiBaseUrl ?? (getEnvVar('BARNDOOR_API') || 'http://localhost:8000');
+      this.mcpBaseUrl =
+        options.mcpBaseUrl ??
+        (getEnvVar('BARNDOOR_MCP') || getEnvVar('BARNDOOR_URL') || 'http://localhost:8000');
+    } else if (env === 'development' || env === 'dev') {
+      this.apiBaseUrl =
+        options.apiBaseUrl ?? (getEnvVar('BARNDOOR_API') || 'https://api.barndoordev.com');
+      this.mcpBaseUrl =
+        options.mcpBaseUrl ??
+        (getEnvVar('BARNDOOR_MCP') ||
+          getEnvVar('BARNDOOR_URL') ||
+          'https://{organization_id}.mcp.barndoordev.com');
+    } else {
+      // production
+      this.apiBaseUrl =
+        options.apiBaseUrl ?? (getEnvVar('BARNDOOR_API') || 'https://api.barndoor.ai');
+      this.mcpBaseUrl =
+        options.mcpBaseUrl ??
+        (getEnvVar('BARNDOOR_MCP') ||
+          getEnvVar('BARNDOOR_URL') ||
+          'https://{organization_id}.mcp.barndoor.ai');
+    }
+  }
+
+  /**
+   * Get static configuration (without organization ID substitution).
+   * @returns Static configuration instance
+   */
+  public static getStaticConfig(): BarndoorConfig {
+    return new BarndoorConfig();
+  }
+
+  /**
+   * Get dynamic configuration with organization ID substituted.
+   * @param jwtToken - JWT token to extract organization ID from
+   * @param options - Configuration options
+   * @returns Dynamic configuration instance
+   */
+  public static getDynamicConfig(
+    jwtToken: string,
+    options: {
+      /** Whether to throw error for tokens without organization info */
+      requireOrganization?: boolean;
+      /** Fallback organization ID to use if none found in token */
+      fallbackOrganizationId?: string;
+    } = {}
+  ): BarndoorConfig {
+    const { requireOrganization = true, fallbackOrganizationId } = options;
+    const config = new BarndoorConfig();
+
+    // Try to extract organization ID safely
+    const orgResult = extractOrganizationIdSafe(jwtToken);
+
+    if (orgResult.hasOrganization) {
+      // Organization found - validate and substitute in URLs
+      const raw = String(orgResult.organizationId ?? '')
+        .trim()
+        .toLowerCase();
+      const safe = /^[a-z0-9-]+$/.test(raw);
+      if (!safe) {
+        throw new ConfigurationError('Invalid organization ID format from token');
+      }
+      config.apiBaseUrl = config.apiBaseUrl.replace('{organization_id}', raw);
+      config.mcpBaseUrl = config.mcpBaseUrl.replace('{organization_id}', raw);
+      return config;
+    }
+
+    // No organization found - handle based on options
+    if (fallbackOrganizationId) {
+      // Use fallback organization ID
+      config.apiBaseUrl = config.apiBaseUrl.replace('{organization_id}', fallbackOrganizationId);
+      config.mcpBaseUrl = config.mcpBaseUrl.replace('{organization_id}', fallbackOrganizationId);
+      return config;
+    }
+
+    if (requireOrganization) {
+      // Throw error with helpful message
+      const errorMessage = orgResult.error || 'No organization information found in token';
+      throw new ConfigurationError(
+        `Failed to extract organization ID from token: ${errorMessage}. ` +
+          'This token may be for a personal account or may be missing organization claims. ' +
+          'Consider using getStaticConfig() for organization-independent operations or ' +
+          'provide a fallbackOrganizationId in the options.'
+      );
+    }
+
+    // Return config without organization substitution (URLs will contain {organization_id} placeholder)
+    return config;
+  }
+
+  /**
+   * Validate the configuration.
+   * @throws ConfigurationError if configuration is invalid
+   */
+  public validate(): void {
+    if (!this.authDomain || this.authDomain.trim() === '') {
+      throw new ConfigurationError('authDomain is required');
+    }
+
+    if (!this.apiAudience || this.apiAudience.trim() === '') {
+      throw new ConfigurationError('apiAudience is required');
+    }
+
+    if (!this.apiBaseUrl || this.apiBaseUrl.trim() === '') {
+      throw new ConfigurationError('apiBaseUrl is required');
+    }
+
+    if (!this.mcpBaseUrl || this.mcpBaseUrl.trim() === '') {
+      throw new ConfigurationError('mcpBaseUrl is required');
+    }
+  }
+}
+
+/**
+ * JWT payload interface for organization extraction.
+ */
+interface JWTPayload {
+  user?: {
+    organization_name?: string;
+    organization_slug?: string;
+  };
+  'https://barndoor.ai/organization_slug'?: string;
+  organization_slug?: string;
+  org_slug?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Cross-platform base64 decode function.
+ * @param str - Base64 string to decode
+ * @returns Decoded string
+ */
+function base64Decode(str: string): string {
+  if (typeof globalThis !== 'undefined' && globalThis.atob) {
+    return globalThis.atob(str);
+  } else if (typeof Buffer !== 'undefined') {
+    return Buffer.from(str, 'base64').toString('utf-8');
+  } else {
+    throw new Error('No base64 decode function available');
+  }
+}
+
+/**
+ * Result of organization ID extraction from JWT token.
+ */
+interface OrganizationExtractionResult {
+  /** Organization ID if found */
+  organizationId?: string;
+  /** Whether organization ID was found */
+  hasOrganization: boolean;
+  /** Error message if extraction failed */
+  error?: string;
+}
+
+/**
+ * Extract organization ID from JWT token with graceful fallback.
+ * @param jwtToken - JWT token
+ * @returns Organization extraction result
+ */
+function extractOrganizationIdSafe(jwtToken: string): OrganizationExtractionResult {
+  try {
+    const parts = jwtToken.split('.');
+    if (parts.length !== 3) {
+      return {
+        hasOrganization: false,
+        error: 'Invalid JWT format - expected 3 parts separated by dots',
+      };
+    }
+
+    let payload: JWTPayload;
+    try {
+      payload = JSON.parse(
+        base64Decode(parts[1]!.replace(/-/g, '+').replace(/_/g, '/'))
+      ) as JWTPayload;
+    } catch (_parseError) {
+      return {
+        hasOrganization: false,
+        error: 'Failed to parse JWT payload - token may be corrupted',
+      };
+    }
+
+    // Try multiple possible locations for organization information
+    let orgSlug: string | undefined;
+
+    // Check user object first (most common location)
+    if (payload.user && typeof payload.user === 'object') {
+      orgSlug = payload.user.organization_name ?? payload.user.organization_slug;
+    }
+
+    // Check custom claims and standard locations
+    if (!orgSlug) {
+      const customClaimSlug = payload['https://barndoor.ai/organization_slug'];
+      const customClaimId = payload['https://barndoor.ai/organization_id'];
+      const orgSlugClaim = payload.organization_slug;
+      const orgSlugShort = payload.org_slug;
+      const orgIdClaim = payload['org_id'];
+      const organizationIdClaim = payload['organization_id'];
+
+      orgSlug =
+        (typeof customClaimSlug === 'string' ? customClaimSlug : undefined) ??
+        (typeof customClaimId === 'string' ? customClaimId : undefined) ??
+        (typeof orgSlugClaim === 'string' ? orgSlugClaim : undefined) ??
+        (typeof orgSlugShort === 'string' ? orgSlugShort : undefined) ??
+        (typeof orgIdClaim === 'string' ? orgIdClaim : undefined) ??
+        (typeof organizationIdClaim === 'string' ? organizationIdClaim : undefined);
+    }
+
+    if (!orgSlug || typeof orgSlug !== 'string' || orgSlug.trim() === '') {
+      return {
+        hasOrganization: false,
+        error:
+          'No organization information found in token. This token may be for a personal account or may be missing organization claims.',
+      };
+    }
+
+    return {
+      organizationId: orgSlug.trim(),
+      hasOrganization: true,
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      hasOrganization: false,
+      error: `Failed to decode JWT token: ${errorMessage}`,
+    };
+  }
+}
+
+/**
+ * Get static configuration instance.
+ * @returns Static configuration instance
+ */
+export function getStaticConfig(): BarndoorConfig {
+  return BarndoorConfig.getStaticConfig();
+}
+
+/**
+ * Get dynamic configuration with organization ID substituted.
+ * @param jwtToken - JWT token
+ * @param options - Configuration options
+ * @returns Dynamic configuration instance
+ */
+export function getDynamicConfig(
+  jwtToken: string,
+  options?: {
+    requireOrganization?: boolean;
+    fallbackOrganizationId?: string;
+  }
+): BarndoorConfig {
+  return BarndoorConfig.getDynamicConfig(jwtToken, options);
+}
+
+/**
+ * Check if a JWT token contains organization information.
+ * @param jwtToken - JWT token to check
+ * @returns Object with organization info and any error details
+ */
+export function checkTokenOrganization(jwtToken: string): OrganizationExtractionResult {
+  return extractOrganizationIdSafe(jwtToken);
+}
+
+/**
+ * Check if a JWT token has organization information (simple boolean check).
+ * @param jwtToken - JWT token to check
+ * @returns True if token contains organization information
+ */
+export function hasOrganizationInfo(jwtToken: string): boolean {
+  return extractOrganizationIdSafe(jwtToken).hasOrganization;
+}

package/src/exceptions/index.ts

@@ -0,0 +1,205 @@
+/**
+ * Exception classes for the Barndoor SDK.
+ *
+ * This module provides a complete hierarchy of error classes that mirror
+ * the Python SDK exceptions exactly, ensuring API compatibility.
+ */
+
+/**
+ * Base exception for all Barndoor SDK errors.
+ */
+export class BarndoorError extends Error {
+  /**
+   * Create a new BarndoorError.
+   * @param message - Error message
+   */
+  constructor(message: string) {
+    super(message);
+    // Avoid relying on constructor.name (can be minified in builds)
+    this.name = 'BarndoorError';
+  }
+}
+
+/**
+ * Raised when authentication fails.
+ */
+export class AuthenticationError extends BarndoorError {
+  /** Optional error code for specific authentication failures */
+  public readonly errorCode: string | null;
+
+  /**
+   * Create a new AuthenticationError.
+   * @param message - Error message
+   * @param errorCode - Optional error code
+   */
+  constructor(message: string, errorCode: string | null = null) {
+    super(message);
+    this.name = 'AuthenticationError';
+    this.errorCode = errorCode;
+  }
+}
+
+/**
+ * Raised when token operations fail.
+ */
+export class TokenError extends AuthenticationError {
+  /** Optional help text for resolving the error */
+  public readonly helpText: string | null;
+
+  /**
+   * Create a new TokenError.
+   * @param message - Error message
+   * @param helpText - Optional help text
+   */
+  constructor(message: string, helpText: string | null = null) {
+    let fullMessage = message;
+    if (helpText) {
+      fullMessage += ` ${helpText}`;
+    } else {
+      fullMessage += " Run 'barndoor-login' to authenticate.";
+    }
+
+    super(fullMessage);
+    this.name = 'TokenError';
+    this.helpText = helpText;
+  }
+}
+
+/**
+ * Raised when a token has expired.
+ */
+export class TokenExpiredError extends TokenError {}
+
+/**
+ * Raised when token validation fails.
+ */
+export class TokenValidationError extends TokenError {}
+
+/**
+ * Raised when unable to connect to the Barndoor API.
+ */
+export class ConnectionError extends BarndoorError {
+  /** The URL that failed to connect */
+  public readonly url: string;
+  /** The original error that caused the connection failure */
+  public readonly originalError: Error;
+
+  /**
+   * Create a new ConnectionError.
+   * @param url - The URL that failed to connect
+   * @param originalError - The original error that caused the failure
+   */
+  constructor(url: string, originalError: Error) {
+    let userMessage: string;
+    const errorStr = originalError.toString().toLowerCase();
+
+    if (errorStr.includes('timeout')) {
+      userMessage = `Connection to ${url} timed out. Please check your internet connection and try again.`;
+    } else if (errorStr.includes('connection refused')) {
+      userMessage = `Could not connect to ${url}. The service may be unavailable.`;
+    } else if (errorStr.includes('name resolution') || errorStr.includes('getaddrinfo')) {
+      userMessage = `Could not resolve hostname for ${url}. Please check the URL and your DNS settings.`;
+    } else {
+      userMessage = `Failed to connect to ${url}. Please check your internet connection.`;
+    }
+
+    super(userMessage);
+    this.url = url;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Raised for HTTP error responses.
+ */
+export class HTTPError extends BarndoorError {
+  /** HTTP status code */
+  public readonly statusCode: number;
+  /** Raw response body */
+  public readonly responseBody: string | null;
+
+  /**
+   * Create a new HTTPError.
+   * @param statusCode - HTTP status code
+   * @param message - Error message
+   * @param responseBody - Raw response body
+   */
+  constructor(statusCode: number, message: string, responseBody: string | null = null) {
+    const userMessage = HTTPError._createUserFriendlyMessage(statusCode, message, responseBody);
+    super(userMessage);
+    this.name = 'HTTPError';
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+
+  /**
+   * Create a user-friendly error message based on HTTP status code.
+   * @private
+   */
+  private static _createUserFriendlyMessage(
+    statusCode: number,
+    message: string,
+    _responseBody: string | null
+  ): string {
+    const baseMessage = `Request failed (HTTP ${statusCode})`;
+
+    if (statusCode === 400) {
+      return `${baseMessage}: Invalid request. Please check your input parameters.`;
+    } else if (statusCode === 401) {
+      return `${baseMessage}: Authentication failed. Please check your token or re-authenticate.`;
+    } else if (statusCode === 403) {
+      return `${baseMessage}: Access denied. You don't have permission for this operation.`;
+    } else if (statusCode === 404) {
+      return `${baseMessage}: Resource not found. Please check the server ID or URL.`;
+    } else if (statusCode === 429) {
+      return `${baseMessage}: Rate limit exceeded. Please wait before making more requests.`;
+    } else if (statusCode >= 500 && statusCode < 600) {
+      return `${baseMessage}: Server error. Please try again later or contact support.`;
+    } else {
+      return `${baseMessage}: ${message}`;
+    }
+  }
+}
+
+/**
+ * Raised when a requested server is not found.
+ */
+export class ServerNotFoundError extends BarndoorError {
+  /** The server identifier that was not found */
+  public readonly serverIdentifier: string;
+  /** List of available servers, if provided */
+  public readonly availableServers: string[] | null;
+
+  /**
+   * Create a new ServerNotFoundError.
+   * @param serverIdentifier - The server identifier that was not found
+   * @param availableServers - Optional list of available servers
+   */
+  constructor(serverIdentifier: string, availableServers: string[] | null = null) {
+    let message = `Server '${serverIdentifier}' not found`;
+    if (availableServers) {
+      message += `. Available servers: ${availableServers.join(', ')}`;
+    } else {
+      message += '. Use listServers() to see available servers.';
+    }
+
+    super(message);
+    this.serverIdentifier = serverIdentifier;
+    this.availableServers = availableServers;
+  }
+}
+
+/**
+ * Raised when OAuth authentication fails.
+ */
+export class OAuthError extends AuthenticationError {}
+
+/**
+ * Raised when there's an issue with SDK configuration.
+ */
+export class ConfigurationError extends BarndoorError {}
+
+/**
+ * Raised when an operation times out.
+ */
+export class TimeoutError extends BarndoorError {}