/**
 * useApi wraps authenticated HTTP calls, URL resolution, and optional response caching for runtime services.
 *
 * Caching contract for the `cache` parameter on get / getPromise / post / postPromise:
 *
 *   - `false` (default)             — no caching, every call hits the network.
 *   - `true`                        — cache the response for 5 minutes (legacy default; preserved
 *                                     for back-compat). Prefer `{ ttlSeconds }` for new code.
 *   - `{ ttlSeconds: 5 }`           — cache for exactly 5 seconds. PREFERRED form.
 *   - `{ ttlMs: 5000 }`             — same, expressed in milliseconds.
 *   - `number` (legacy)             — DEPRECATED. Treated by an undocumented size-based
 *                                     heuristic where values <= 60 are read as MINUTES and
 *                                     values > 60 as SECONDS. Emits a console warning the
 *                                     first time a session sees this form. Migrate to
 *                                     `{ ttlSeconds }` / `{ ttlMs }` to remove the warning
 *                                     and get unambiguous behaviour.
 *
 * Mutations that change resources read by a cached query should call
 * `useApi().invalidate(prefix)` so the next read fetches fresh data. Without that,
 * cached entries stay valid until their TTL expires — `localStorage` survives reloads,
 * so users can see stale empty / outdated lists for the full TTL window even after
 * creating data themselves.
 *
 * Idempotency: every authenticated POST (REST and GraphQL via useGraphQl()) automatically
 * receives an `Idempotency-Key` HTTP header. The value is computed client-side as
 *
 *   SHA-256(`${floor(Date.now()/1000)}|${username}|${stableStringify(body ?? {})}`)
 *
 * in lowercase hex. The recipe is intentionally identical to the backend's server-side
 * fallback in rama-spring-starter's @IdempotentMutation aspect, so a header-present and
 * a header-absent request from the same user with the same body within the same wall-clock
 * second resolve to the same dedup signature.
 *
 * Per-call escape hatch: pass `{ idempotent: false }` in the options argument to skip
 * injection for a single call (e.g. a long-running mutation the caller wants to retry
 * intentionally with the same body). A caller-supplied `Idempotency-Key` in
 * `options.headers` always wins and is never overwritten.
 *
 * Configuration (consumer's `nuxt.config` `runtimeConfig.public`, mirroring the
 * unprefixed `WS_API` / `WS_GRAPHQL` precedent):
 *   - IDEMPOTENCY_HEADER (default 'Idempotency-Key') — must match the backend's
 *     `rama.idempotency.header-name` setting if the consumer overrides it there.
 *   - IDEMPOTENCY_ENABLED (default true) — global kill switch.
 *
 * This doc block is consumed by vue-docgen for generated API documentation.
 */
import type { UseFetchOptions } from 'nuxt/app';
import type { SearchParameters } from 'ofetch';
/**
 * Explicit cache options. Use this in new code instead of passing a bare number.
 *  - `ttlSeconds`: cache lifetime in seconds. Mutually exclusive with `ttlMs`.
 *  - `ttlMs`     : cache lifetime in milliseconds. Mutually exclusive with `ttlSeconds`.
 */
export type CacheOption = boolean | number | {
    ttlSeconds: number;
} | {
    ttlMs: number;
};
/**
 * Per-call options accepted by useApi alongside Nuxt's UseFetchOptions.
 *
 * `idempotent: false` skips Idempotency-Key header injection for this single call.
 * Default is `true`. See the useApi() docblock for the full idempotency contract.
 */
export interface ApiIdempotencyOption {
    idempotent?: boolean;
}
export type ApiFetchOptions = UseFetchOptions<unknown> & ApiIdempotencyOption;
export declare function _resetLegacyHeuristicWarning(): void;
/**
 * Resolve a cache option to seconds. Pure function, exported for tests.
 *
 *  - false / 0 / null / undefined → 0 (no cache)
 *  - true                         → DEFAULT_TTL_SECONDS_FOR_TRUE
 *  - { ttlSeconds: n }            → n  (clamped to >= 0, floored)
 *  - { ttlMs: n }                 → ceil(n / 1000)
 *  - number (legacy)              → heuristic + warn
 */
export declare function resolveCacheTtlSeconds(cache: CacheOption | undefined | null): number;
/**
 * Drop every `api-cache-*` localStorage entry whose stored URL contains `prefix`.
 * Pass `undefined` (or no arg) to drop ALL api-cache entries.
 *
 * Recommended invalidation path after a mutation:
 *
 *   await useApi().postPromise('/model/resource/create', input)
 *   useApi().invalidate('/model/resource')   // drops list + lookup caches
 *
 * Returns the number of entries removed. Safe to call when the cache is empty.
 */
declare function invalidateCache(prefix?: string): number;
export declare function useApi(): {
    urlBuilder: (url: string | string[]) => string;
    get: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
    getPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
    post: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
    postPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
    hashKey: (data: any) => Promise<string>;
    invalidate: typeof invalidateCache;
};
export {};
