/**
 * Shared types for the OAuth provider extensibility layer.
 *
 * These types are consumed by the token persistence module and the
 * credential vault orchestrator.
 *
 * All provider configuration — protocol-level OAuth config (authorizeUrl,
 * tokenExchangeUrl, scopes, etc.) as well as behavioral config (identity
 * verification, injection templates, setup metadata) — is now stored
 * exclusively in the `oauth_providers` SQLite table and seeded on
 * startup via `seed-providers.ts`.
 */

// ---------------------------------------------------------------------------
// Available scopes
// ---------------------------------------------------------------------------

/** Informational scope metadata for the assistant. Either a structured list
 * of scopes with optional descriptions, or a URL to the provider's scope docs. */
export type AvailableScopes =
  | Array<{ scope: string; description?: string }>
  | string;

// ---------------------------------------------------------------------------
// Connect result
// ---------------------------------------------------------------------------

/** Outcome of an OAuth connect attempt. */
export type OAuthConnectResult =
  | OAuthConnectInteractiveResult
  | OAuthConnectDeferredResult
  | OAuthConnectErrorResult;

/** Successful interactive flow — tokens stored, ready to use. */
export interface OAuthConnectInteractiveResult {
  success: true;
  deferred: false;
  grantedScopes: string[];
  accountInfo?: string;
}

/** Successful deferred flow — auth URL returned for the user to open. */
export interface OAuthConnectDeferredResult {
  success: true;
  deferred: true;
  authorizeUrl: string;
  state: string;
  service: string;
}

/** Failed connect attempt. */
export interface OAuthConnectErrorResult {
  success: false;
  error: string;
  /**
   * When true, the error message is internally generated by the orchestrator
   * and safe to display to the user as-is (no secrets). When false or absent,
   * the error may contain raw provider response text and should be sanitized
   * before surfacing to the user or logging to non-redacted fields.
   */
  safeError?: boolean;
}