using PowderCoating.Application.DTOs.Columbia;

namespace PowderCoating.Application.Interfaces;

/// <summary>
/// Typed client for the Columbia Coatings product catalog API (<c>/wp-json/cca/v1</c>).
/// Read-only: lists products via the paged <c>GET /products</c> endpoint.
/// <para>
/// We deliberately page <c>/products</c> rather than using the bulk <c>export.json</c> download:
/// the export returns a temporary <c>download_url</c> to a static file under <c>/wp-content/uploads</c>,
/// which sits behind Cloudflare bot protection and 403s for non-browser clients. The
/// <c>/wp-json</c> API routes are allowlisted via the API key, so paging is the only path that
/// works reliably from a server.
/// </para>
/// </summary>
public interface IColumbiaCoatingsApiClient
{
    /// <summary>
    /// True when an API key is configured (<c>Columbia:ApiKey</c>). When false, callers should
    /// skip the sync entirely rather than issue unauthenticated requests.
    /// </summary>
    bool IsConfigured { get; }

    /// <summary>
    /// Retrieves a single page of products. <paramref name="perPage"/> is capped at 100 by the API.
    /// </summary>
    Task<ColumbiaProductsResponse> GetProductsPageAsync(int page, int perPage, CancellationToken cancellationToken = default);

    /// <summary>
    /// Pages through the entire catalog and returns every product. Honors rate limiting
    /// (429 / Retry-After). THROWS if any page fails after retries — callers must treat an
    /// exception as "incomplete pull" and NOT run discontinuation logic against a partial set.
    /// </summary>
    Task<IReadOnlyList<ColumbiaProduct>> GetAllProductsAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Fetches a single product by exact SKU (<c>GET /products?sku=...</c>), or null if not found.
    /// For ad-hoc refresh of one record without pulling the whole catalog.
    /// </summary>
    Task<ColumbiaProduct?> GetProductBySkuAsync(string sku, CancellationToken cancellationToken = default);

    /// <summary>
    /// Fetches a single product by WooCommerce product ID (<c>GET /products/{id}</c>), or null if
    /// not found. Useful when we already store the catalog product's ID and want to refresh it.
    /// </summary>
    Task<ColumbiaProduct?> GetProductByIdAsync(int id, CancellationToken cancellationToken = default);
}
