// ── HTTP layer — configuration types ──────────────────────────────────────────
//
// Two mutually exclusive auth methods — pick exactly one:
//
//   Bearer (users)   → token | getToken   → Authorization: Bearer <jwt>
//   API key (agents) → apiKey             → X-Api-Key: kb_t_... | kb_s_...

/**
 * Configuration for the Kaiban SDK client.
 *
 * @example Browser — user identity (Firebase JWT, auto-refreshing):
 * ```ts
 * const client = new KaibanClient({
 *   tenant: "my-org",
 *   getToken: () => getAuth().currentUser?.getIdToken() ?? Promise.resolve(undefined),
 * });
 * ```
 *
 * @example Server / agent — API key (tenant-scoped or shared):
 * ```ts
 * const client = new KaibanClient({
 *   tenant: "my-org",
 *   apiKey: process.env.KAIBAN_API_KEY, // kb_t_... or kb_s_...
 * });
 * ```
 *
 * @example Static JWT (non-refreshing — useful in scripts / tests):
 * ```ts
 * const client = new KaibanClient({
 *   tenant: "my-org",
 *   token: "eyJ...",
 * });
 * ```
 */
export interface ClientConfig {
  /**
   * Tenant identifier — maps to the `x-tenant` header on every request.
   * In most deployments this is the organization slug.
   */
  tenant: string;

  // ── Auth — choose exactly one ──────────────────────────────────────────────

  /**
   * API key for service / agent identity.
   * Sent as `X-Api-Key: <apiKey>` on every request.
   * Format: `kb_t_{tenant}_{...}` (tenant-scoped) or `kb_s_{...}` (shared).
   *
   * Use this for agents, external integrations, and server-side automation
   * where no user Firebase session is available.
   */
  apiKey?: string;

  /**
   * Static bearer token (Firebase ID token or any JWT).
   * Sent as `Authorization: Bearer <token>` on every request.
   * Use `getToken` instead when the token can expire (e.g. Firebase sessions).
   *
   * Ignored when `apiKey` is set.
   */
  token?: string;

  /**
   * Async token factory — called before every request.
   * Return `undefined` to send the request without an Authorization header.
   * Takes precedence over `token` when both are provided.
   *
   * Ignored when `apiKey` is set.
   */
  getToken?: () => Promise<string | undefined>;

  // ── Infrastructure ─────────────────────────────────────────────────────────

  /**
   * Base URL for the API.
   * Defaults to `https://agi.kaiban.ai/api/v2`.
   */
  baseUrl?: string;

  /**
   * Request timeout in milliseconds.
   * Defaults to 30 000 ms (30 s).
   */
  timeoutMs?: number;

  /**
   * Custom `fetch` implementation.
   * Defaults to `globalThis.fetch`.
   * Inject `node-fetch` or `undici` for Node < 18 environments.
   */
  fetch?: typeof globalThis.fetch;
}

/** Per-request override options. */
export interface RequestOptions {
  /** Override the request timeout for this specific call. */
  timeoutMs?: number;
  /** AbortSignal to cancel the request from the caller. */
  signal?: AbortSignal;
  /** Extra headers to merge into this request. */
  headers?: Record<string, string>;
}