/**
 * Core type definitions for pi-credential-vault.
 *
 * The CredentialBackend interface is the primary extension point.
 * All credential storage implementations must conform to it.
 */

// ---------------------------------------------------------------------------
// Credential entries
// ---------------------------------------------------------------------------

export interface ApiKeyEntry {
	readonly type: "api_key";
	readonly key: string;
}

export interface OAuthEntry {
	readonly type: "oauth";
	readonly access: string;
	readonly refresh: string;
	readonly expires: number;
	readonly accountId?: string;
}

export type CredentialEntry = ApiKeyEntry | OAuthEntry;

// ---------------------------------------------------------------------------
// Backend interface
// ---------------------------------------------------------------------------

export interface BackendStatus {
	readonly available: boolean;
	readonly error?: string;
	readonly detail?: string;
}

/**
 * Pluggable credential storage backend.
 *
 * Implementations handle the physical storage of credentials.
 * The extension core handles provider override wiring and OAuth flow
 * interception -- backends only need to implement CRUD.
 */
export interface CredentialBackend {
	/** Human-readable backend name for display. */
	readonly name: string;

	/** Retrieve a credential entry for a provider. */
	get(provider: string): Promise<CredentialEntry | undefined>;

	/** Store a credential entry for a provider. */
	set(provider: string, entry: CredentialEntry): Promise<void>;

	/** Remove a credential entry for a provider. */
	remove(provider: string): Promise<void>;

	/** List all provider IDs that have stored credentials. */
	list(): Promise<string[]>;

	/** Check whether the backend is available and healthy. */
	check(): Promise<BackendStatus>;
}

// ---------------------------------------------------------------------------
// Configuration
// ---------------------------------------------------------------------------

export type BackendType = "age" | "keychain" | "passthrough";

export interface AgeBackendConfig {
	/** Path to the encrypted vault file. Default: ~/.pi/agent/vault.age.json */
	readonly vaultPath?: string;

	/** Path to the age identity (secret key) file. Default: ~/.config/pi-vault/age.txt */
	readonly identityPath?: string;

	/**
	 * Additional age recipients (public keys) for multi-machine setups.
	 * The local identity's public key is always included.
	 */
	readonly recipients?: readonly string[];
}

export interface KeychainBackendConfig {
	/** Service name for keychain entries. Default: pi-credential-vault */
	readonly service?: string;
}

export interface VaultConfig {
	/** Active backend type. Default: age */
	readonly backend: BackendType;

	/**
	 * Which providers to manage.
	 * "all" manages every provider that has credentials.
	 * An array manages only the listed provider IDs.
	 * Default: "all"
	 */
	readonly managedProviders: "all" | readonly string[];

	/**
	 * Provider IDs to exclude from management.
	 * Useful with managedProviders: "all" to skip providers handled
	 * by other extensions (e.g., multicodex handling openai-codex).
	 */
	readonly excludeProviders?: readonly string[];

	/** Age backend configuration. */
	readonly age?: AgeBackendConfig;

	/** Keychain backend configuration. */
	readonly keychain?: KeychainBackendConfig;
}

// ---------------------------------------------------------------------------
// Extension API (for inter-extension communication)
// ---------------------------------------------------------------------------

/**
 * Public API surface exposed via pi.events EventBus.
 * Other extensions (e.g., multicodex) can retrieve the API with:
 *
 * ```typescript
 * pi.events.emit("credential-vault:get-api", (api: VaultExtensionApi) => {
 *   const backend = api.getBackend();
 * });
 * ```
 *
 * Backend plugins register via:
 * ```typescript
 * pi.events.emit("credential-vault:register-backend", {
 *   type: "bitwarden",
 *   backend: new BitwardenBackend(),
 * });
 * ```
 */
export interface VaultExtensionApi {
	/** Get the active credential backend instance. */
	getBackend(): CredentialBackend;

	/** Get the current resolved config. */
	getConfig(): VaultConfig;

	/**
	 * Register an external backend.
	 * Reserved for future plugin API (v0.3.0+).
	 */
	// registerBackend(type: string, backend: CredentialBackend): void;
}