/** A minted child-app credential and the moment it stops being usable. */
export interface AppToken {
    /** The bare id token to send as `Authorization: Bearer <token>`. */
    token: string;
    /** Epoch milliseconds at which the token expires. */
    expiresAtMs: number;
    /** The child app the token is pinned to. */
    appId: string;
}
/** Why an exchange stopped trying. Recorded, never retried past this point. */
export interface AppTokenGiveUp {
    appId: string;
    /** HTTP status of the last attempt, or null for a transport failure. */
    status: number | null;
    /** Machine-readable reason: the issuer's `error` field where it sent one. */
    reason: string;
    attempts: number;
}
export interface ExchangeAppTokenOptions {
    /**
     * Origin of the Bounded Auth issuer that serves `/app-token/exchange` - the
     * resolved `humanAuthApiUrl` for your network. A path suffix is tolerated.
     */
    authApiUrl: string;
    /** The child app to mint a token for. */
    appId: string;
    /** The signed-in PARENT app's id token (e.g. the venue session's). */
    parentToken: string;
    /** HTTP attempts, including the first. Default 3, clamped to 1..5. */
    maxAttempts?: number;
    /** Called once when an exchange stops trying. Defaults to a console warning. */
    onGiveUp?: (info: AppTokenGiveUp) => void;
    /** Test seam; defaults to the global fetch. */
    fetchImpl?: typeof fetch;
}
/** Thrown when an exchange stops trying. `giveUp` carries the recorded reason. */
export declare class AppTokenExchangeError extends Error {
    readonly giveUp: AppTokenGiveUp;
    constructor(giveUp: AppTokenGiveUp);
}
/**
 * Get a child-app id token for the human the parent token belongs to, from cache
 * when one is still comfortably fresh and otherwise by exchanging once.
 *
 * Concurrent callers for the same (parent credential, appId) share one exchange.
 * On give-up this rejects with {@link AppTokenExchangeError} and caches nothing.
 */
export declare function exchangeAppToken(options: ExchangeAppTokenOptions): Promise<AppToken>;
/**
 * Drop cached child-app tokens. Call this on sign-out; an identity change needs
 * no call, because the cache key is the exact parent credential.
 *
 * With no argument every entry goes. `appId` narrows to one child app, and
 * `parentToken` narrows to one session's entries.
 */
export declare function clearAppTokenCache(scope?: {
    appId?: string;
    parentToken?: string;
}): void;
export interface AppTokenAuthHeadersOptions extends Omit<ExchangeAppTokenOptions, 'parentToken'> {
    /**
     * The CURRENT parent-app credential, read on every call so a refreshed session
     * is picked up and a signed-out one degrades the instance to anonymous.
     * Return the bare id token, or null/undefined when signed out.
     */
    parentToken: () => string | null | undefined | Promise<string | null | undefined>;
}
/**
 * Build the `getAuthHeaders` a scoped `createClient({ appId, getAuthHeaders })`
 * instance authenticates with, backed by {@link exchangeAppToken}.
 *
 * Signed out (`parentToken()` yields nothing) returns NO headers, which leaves
 * the scoped instance anonymous - the public read lane - instead of failing. A
 * give-up on the exchange itself rejects, so a broken exchange surfaces as an
 * error rather than as silently unauthenticated reads.
 */
export declare function createAppTokenAuthHeaders(options: AppTokenAuthHeadersOptions): () => Promise<Record<string, string>>;