@smartsamurai/krapi-sdk/src/client.ts

KRAPI TypeScript SDK - Easy-to-use client SDK for connecting to self-hosted KRAPI servers (like Appwrite SDK)

/**
 * KRAPI Client SDK
 *
 * A simple, easy-to-use client SDK for React, Vue, Angular, and other frontend frameworks.
 * Similar to Appwrite SDK - just import and use!
 *
 * This is an alternative client interface for frontend applications. For most use cases,
 * the main `krapi` singleton (from '@smartsamurai/krapi-sdk') is recommended as it provides
 * perfect client/server parity.
 *
 * **When to use KrapiClient:**
 * - You need a client-only SDK (no server mode support)
 * - You prefer a class-based API over a singleton
 * - You're building a simple frontend-only application
 *
 * **When to use krapi singleton:**
 * - You want the same code to work in both frontend and backend
 * - You need server mode (direct database access)
 * - You want the recommended, fully-featured SDK
 *
 * @module client
 * @example
 * ```typescript
 * import { KrapiClient } from '@smartsamurai/krapi-sdk/client';
 *
 * // Create client instance
 * const krapi = new KrapiClient({
 *   endpoint: 'http://localhost:3470', // Your KRAPI server URL
 *   apiKey: 'your-api-key' // Optional: API key for authentication
 * });
 *
 * // Use it!
 * const projects = await krapi.projects.getAll();
 * const documents = await krapi.collections.documents.list('project-id', 'collection-name');
 *
 * // Set session token for authenticated requests
 * krapi.auth.setSessionToken('session-token');
 * const user = await krapi.auth.getCurrentUser();
 * ```
 *
 * @example React Usage
 * ```typescript
 * import { KrapiClient } from '@smartsamurai/krapi-sdk/client';
 * import { useEffect, useState } from 'react';
 *
 * function App() {
 *   const [projects, setProjects] = useState([]);
 *
 *   useEffect(() => {
 *     const krapi = new KrapiClient({
 *       endpoint: process.env.REACT_APP_KRAPI_ENDPOINT || 'http://localhost:3470',
 *       apiKey: process.env.REACT_APP_KRAPI_API_KEY
 *     });
 *
 *     krapi.projects.getAll().then(setProjects);
 *   }, []);
 *
 *   return <div>{/* render projects *\/}</div>;
 * }
 * ```
 */

import { BackupApiManager } from "./client/backup-api-manager";
import { CollectionsApiManager } from "./client/collections-api-manager";
import { ProjectApiManager } from "./client/project-api-manager";
import { ServiceClientManager } from "./client/service-client-manager";
import { AdminHttpClient } from "./http-clients/admin-http-client";
import { AuthHttpClient } from "./http-clients/auth-http-client";
import { HttpClientConfig } from "./http-clients/base-http-client";
import { CollectionsHttpClient } from "./http-clients/collections-http-client";
import { EmailHttpClient } from "./http-clients/email-http-client";
import { HealthHttpClient } from "./http-clients/health-http-client";
import { StorageHttpClient } from "./http-clients/storage-http-client";
import { ApiResponse } from "./types";

// Re-export for backward compatibility
export type { ApiResponse };

export interface KrapiClientConfig {
  endpoint: string;
  apiKey?: string;
  sessionToken?: string;
  projectId?: string;
  timeout?: number;
  headers?: Record<string, string>;
}

/**
 * KRAPI Client SDK
 *
 * Simple, unified client for interacting with KRAPI backend.
 * Works exactly like Appwrite SDK - import and use!
 *
 * @class KrapiClient
 * @example
 * const client = new KrapiClient({
 *   endpoint: 'https://api.example.com/krapi/k1',
 *   apiKey: 'your-api-key'
 * });
 * const projects = await client.projects.list();
 */
export class KrapiClient {
  private serviceClientManager: ServiceClientManager;
  private projectApiManager: ProjectApiManager;
  private collectionsApiManager: CollectionsApiManager;
  private backupApiManager: BackupApiManager;

  // Service clients (delegated from ServiceClientManager)
  public auth: AuthHttpClient;
  public storage: StorageHttpClient;
  public admin: AdminHttpClient;
  public email: EmailHttpClient;
  public health: HealthHttpClient;

  // API managers
  public projects: ProjectApiManager;
  public collections: CollectionsApiManager;
  public backup: BackupApiManager;

  /**
   * Create a new KrapiClient instance
   *
   * @param {KrapiClientConfig} config - Client configuration
   * @param {string} config.endpoint - API endpoint URL
   * @param {string} [config.apiKey] - API key for authentication
   * @param {string} [config.sessionToken] - Session token for authentication
   * @param {string} [config.projectId] - Default project ID
   * @param {number} [config.timeout] - Request timeout in milliseconds (default: 30000)
   * @param {Record<string, string>} [config.headers] - Additional HTTP headers
   *
   * @example
   * const client = new KrapiClient({
   *   endpoint: 'https://api.example.com/krapi/k1',
   *   apiKey: 'pk_...',
   *   timeout: 60000
   * });
   */
  constructor(config: KrapiClientConfig) {
    // Initialize service client manager (handles HTTP clients)
    this.serviceClientManager = new ServiceClientManager(config);

    // Delegate service clients from manager
    this.auth = this.serviceClientManager.auth;
    this.storage = this.serviceClientManager.storage;
    this.admin = this.serviceClientManager.admin;
    this.email = this.serviceClientManager.email;
    this.health = this.serviceClientManager.health;

    // Initialize API managers
    const axiosInstance = this.serviceClientManager
      .getHttpClientManager()
      .getAxiosInstance();
    this.projectApiManager = new ProjectApiManager(axiosInstance);
    const collectionsHttpConfig: HttpClientConfig = {
      baseUrl: config.endpoint.replace(/\/$/, ""),
    };

    // Only add defined properties to avoid type issues
    if (config.apiKey !== undefined)
      collectionsHttpConfig.apiKey = config.apiKey;
    if (config.sessionToken !== undefined)
      collectionsHttpConfig.sessionToken = config.sessionToken;
    if (config.projectId !== undefined)
      collectionsHttpConfig.projectId = config.projectId;
    if (config.timeout !== undefined)
      collectionsHttpConfig.timeout = config.timeout;

    this.collectionsApiManager = new CollectionsApiManager(
      axiosInstance,
      new CollectionsHttpClient(collectionsHttpConfig)
    );
    this.backupApiManager = new BackupApiManager(axiosInstance);

    // Expose API managers as public properties
    this.projects = this.projectApiManager;
    this.collections = this.collectionsApiManager;
    this.backup = this.backupApiManager;
  }

  /**
   * Set API key for authentication
   *
   * Updates the API key used for authenticating requests.
   * This will override any existing session token.
   *
   * @param {string} apiKey - API key to use for authentication
   * @returns {void}
   *
   * @example
   * client.setApiKey('pk_live_...');
   */
  setApiKey(apiKey: string): void {
    this.serviceClientManager.setApiKey(apiKey);
  }

  /**
   * Set session token for authentication
   *
   * Updates the session token used for authenticating requests.
   * This will override any existing API key.
   *
   * @param {string} token - Session token to use for authentication
   * @returns {void}
   *
   * @example
   * client.setSessionToken('session_token_...');
   */
  setSessionToken(token: string): void {
    this.serviceClientManager.setSessionToken(token);
  }

  /**
   * Set project ID for project-specific operations
   *
   * Sets the project ID that will be conditionally added as X-Project-ID header
   * only for project-scoped routes (e.g., /projects/{id}/...).
   * The header will NOT be added for list/create operations (e.g., /projects).
   *
   * @param {string} projectId - Project ID to use
   * @returns {void}
   *
   * @example
   * client.setProjectId('project-id');
   */
  setProjectId(projectId: string): void {
    this.serviceClientManager.setProjectId(projectId);
  }

  /**
   * Get current configuration
   *
   * Returns a copy of the current client configuration.
   *
   * @returns {KrapiClientConfig} Current configuration
   *
   * @example
   * const config = client.getConfig();
   * console.log(config.endpoint, config.projectId);
   */
  getConfig(): KrapiClientConfig {
    return this.serviceClientManager.getConfig();
  }
}

// Default export for easy importing
export default KrapiClient;