/**
 * @fileoverview Remote app list fetching — wires the API client to the cache layer.
 *
 * Why a separate module: `app list` and `app pull` both need to fetch remote apps
 * with caching. Putting the fetch + cache logic here keeps those commands focused
 * on their specific concerns (building the output, deciding scope).
 *
 * Cache fallback behavior: if a remote fetch fails and a cached result exists,
 * the cached result is returned silently. This is intentional — `app list` should
 * work even when offline, showing stale data rather than failing completely.
 * `app pull --no-cache` bypasses this fallback.
 */
import { type RemoteAppItem } from "../../core/api-client.js";
export type { RemoteAppItem };
/**
 * The result of a successful app list fetch, including provenance metadata.
 *
 * Why `source`: callers need to display where the data came from ("Loaded from cache"
 * vs "Fetched from remote") so users understand staleness. `app list` and `app pull`
 * both surface this in their output.
 */
export interface RemoteAppListResult {
    /** App items returned by the source. */
    items: RemoteAppItem[];
    /** Where the data came from. */
    source: "remote" | "cache" | "mock";
    /** ISO timestamp of when this result was fetched (null for empty cache). */
    fetchedAt: string | null;
    /** Absolute path to the cache file, or null if no caching occurred. */
    cachePath: string | null;
}
/**
 * Returns `true` when the mock data source should be used instead of the real API.
 *
 * Why product env lookup: downstream builds can change the main env prefix in
 * `PRODUCT_CONFIG` while still keeping optional legacy prefixes for migration.
 */
export declare function shouldUseMockRemoteApps(): boolean;
/**
 * Fetches app items from the appropriate source (mock or real API).
 *
 * @returns Raw `RemoteAppItem[]` from the selected source.
 * @throws Propagates errors from `getMyApps()` on network/API failure.
 */
export declare function getRemoteAppItems(): Promise<RemoteAppItem[]>;
/**
 * Fetches the remote app list with cache support.
 *
 * Resolution order:
 * 1. `localOnly` → return cached data only (never hits the network)
 * 2. Try remote → on success, write to cache
 * 3. On failure + cached data exists → return stale cache (with `source: "cache"`)
 * 4. On failure + no cache → propagate the error
 *
 * @param options.env        - Target environment
 * @param options.accessKey  - Access key for cache file naming (omit to skip caching)
 * @param options.localOnly - If true, never fetch remotely
 * @param options.noCache   - If true, skip cache fallback on network failure
 * @returns `RemoteAppListResult` with items, source, and metadata
 */
export declare function getRemoteAppList(options: {
    env: "production" | "development" | "daily";
    accessKey?: string;
    localOnly?: boolean;
    noCache?: boolean;
}): Promise<RemoteAppListResult>;