/**
 * `cleo cloud whoami|devices|projects`: read-only Cleo Nexus reads with the
 * device credential (cleo-nexus device contract v2.15, §4.2 E2, E5, E13, E14,
 * E15; CLI mapping §4.4).
 *
 * - Every request is a `GET`. Nothing here writes to the server or to a
 *   project store. The one side effect is the one every device-credential
 *   command has: {@link ensureNexusDeviceCredential} retries unsettled
 *   logouts and upgrades a 9.24 session once (§3.4, §3.5).
 * - Lists follow `nextCursor` (§4.0.3) with the largest page the server takes,
 *   up to a page budget, and report the server's `truncated` flags.
 * - Failures are mapped by {@link nexusApiErrorToAccountError}, whose table
 *   lives in `@cleocode/contracts` (§4.0.4).
 *
 * No function here logs, and no result or error carries a token.
 *
 * @task T12871
 * @epic T12323
 */
import type { CloudDevicesResult, CloudPaging, CloudProjectShowResult, CloudProjectsResult, CloudRetiredReplica, CloudWarning, CloudWhoamiResult, NexusCloudReplica, NexusDeviceListState, NexusProjectLink } from '@cleocode/contracts';
import { type ResponseSchema } from './http.js';
import { NexusDeviceStore, type SealedNexusDevice } from './nexus-device.js';
import { type NexusDeviceCredentialOptions } from './nexus-enrol.js';
/** Timeout of one `cleo cloud` request. */
export declare const NEXUS_CLOUD_TIMEOUT_MS = 15000;
/** Warning code for a non-fatal problem met while getting the device credential. */
export declare const W_NEXUS_CREDENTIAL = "W_NEXUS_CREDENTIAL";
/** Warning code: a list stopped at its page budget while the server had more. */
export declare const W_NEXUS_PAGE_LIMIT = "W_NEXUS_PAGE_LIMIT";
/** Warning code: a server ceiling cut a list (§4.0.3 `truncated`). */
export declare const W_NEXUS_TRUNCATED = "W_NEXUS_TRUNCATED";
/** Options shared by every `cleo cloud` read; all optional (tests inject them). */
export interface NexusCloudOptions extends NexusDeviceCredentialOptions {
    /** Project root; defaults to the current project (when there is one). */
    projectRoot?: string;
    /** Per-request timeout; default {@link NEXUS_CLOUD_TIMEOUT_MS}. */
    timeoutMs?: number;
    /** Most pages a list follows; default {@link NEXUS_CLOUD_MAX_PAGES}. */
    maxPages?: number;
    /** Page size sent as `limit`; default {@link NEXUS_PAGE_LIMIT_MAX}. */
    pageLimit?: number;
}
/** A signed-in, read-only connection to the API. Holds the bearer inside {@link Http} only. */
export interface NexusCloudConnection {
    /** API origin. */
    readonly apiUrl: string;
    /** The device entry whose credential the requests carry. */
    readonly device: SealedNexusDevice;
    /** Warnings from getting the credential. */
    readonly warnings: CloudWarning[];
    /** `GET path`, parsed against `schema`; failures mapped per §4.0.4. */
    get<T>(path: string, schema: ResponseSchema<T>): Promise<T>;
    /** {@link NexusCloudConnection.get}, but a 404 `E_NOT_FOUND` answers `null`. */
    find<T>(path: string, schema: ResponseSchema<T>): Promise<T | null>;
}
/** The current CLEO project, as far as the cloud reads need it. */
export interface NexusCloudProject {
    /** Project root. */
    readonly root: string;
    /** The tracked project id (`.cleo/project.json`, legacy `.cleo/project-id`). */
    readonly projectId: string;
    /** The `.cleo/nexus-link.json` entry for the origin, if any. */
    readonly link: NexusProjectLink | null;
    /** Path of `.cleo/nexus-link.json` (whether or not it exists). */
    readonly linkPath: string;
}
/**
 * Refuse with `E_NEXUS_DEVICE_REQUIRED` when device credentials are off
 * (`CLEO_NEXUS_DEVICE=0`): the cloud reads never fall back to a 9.24 session.
 *
 * @throws {NexusAccountError} `E_NEXUS_DEVICE_REQUIRED`.
 */
export declare function assertNexusCloudDeviceMode(): void;
/** Wrap credential warnings (plain strings) as envelope warnings. */
export declare function nexusCredentialWarnings(warnings: readonly string[]): CloudWarning[];
/**
 * Open a read-only connection with this machine's device credential.
 *
 * @param opts - API URL, account, stores and test overrides.
 * @returns The connection.
 * @throws {NexusAccountError} `E_NEXUS_DEVICE_REQUIRED`, `E_NEXUS_NOT_SIGNED_IN`,
 *   `E_NEXUS_ACCOUNT_AMBIGUOUS`, or an upgrade failure.
 */
export declare function connectNexusCloud(opts?: NexusCloudOptions): Promise<NexusCloudConnection>;
/** A path with its query string; `undefined` values are left out. */
export declare function nexusQueryPath(path: string, query: Readonly<Record<string, string | number | undefined>>): string;
/** One page of a cursor-paged list. */
interface Page {
    readonly nextCursor: string | null;
    readonly truncated: boolean;
}
/**
 * Follow `nextCursor` until the server has no more or the budget is spent.
 *
 * @param fetchPage - Fetch the page after `cursor` (`null` for the first).
 * @param maxPages - Page budget (at least 1).
 * @returns Every page fetched and the paging facts.
 */
export declare function followNexusPages<P extends Page>(fetchPage: (cursor: string | null) => Promise<P>, maxPages: number): Promise<{
    pages: P[];
    paging: CloudPaging;
}>;
/** The warnings a list's paging facts call for. */
export declare function nexusPagingWarnings(what: string, paging: CloudPaging): CloudWarning[];
/**
 * The current CLEO project, or `null` outside one (or without a project id).
 *
 * @param apiUrl - API origin whose link entry to read.
 * @param projectRoot - Explicit project root; defaults to the current one.
 * @returns The project, its id and link entry, or `null`.
 */
export declare function currentNexusCloudProject(apiUrl: string, projectRoot?: string): NexusCloudProject | null;
/**
 * `cleo cloud whoami`: E2 `GET /v1/whoami`.
 *
 * @param opts - API URL, account, stores and test overrides.
 * @returns Who is calling: user, organizations, credential and device.
 */
export declare function nexusCloudWhoami(opts?: NexusCloudOptions): Promise<CloudWhoamiResult>;
/** Options for {@link listNexusCloudDevices}. */
export interface NexusCloudDevicesOptions extends NexusCloudOptions {
    /** `--state`; the server's default (`active` for device callers) when absent. */
    state?: NexusDeviceListState;
}
/**
 * `cleo cloud devices`: E5 `GET /v1/devices`, every page.
 *
 * @param opts - State filter, paging and test overrides.
 * @returns Every device, newest first, with paging facts.
 */
export declare function listNexusCloudDevices(opts?: NexusCloudDevicesOptions): Promise<CloudDevicesResult>;
/** Options for {@link listNexusCloudProjects}. */
export interface NexusCloudProjectsOptions extends NexusCloudOptions {
    /** `--org`: only this organization's projects. */
    organizationId?: string;
}
/**
 * `cleo cloud projects`: E13 `GET /v1/projects`, every page.
 *
 * @param opts - Organization filter, paging and test overrides.
 * @returns Every visible project, newest first, with paging facts.
 */
export declare function listNexusCloudProjects(opts?: NexusCloudProjectsOptions): Promise<CloudProjectsResult>;
/**
 * Every replica of a project from E15, following its cursors.
 *
 * @param conn - Connection.
 * @param projectId - Project id.
 * @param opts - Paging overrides.
 * @returns The replicas, oldest attachment first, and the paging facts.
 */
export declare function listNexusCloudReplicas(conn: NexusCloudConnection, projectId: string, opts?: Pick<NexusCloudOptions, 'maxPages' | 'pageLimit'>): Promise<{
    replicas: NexusCloudReplica[];
    paging: CloudPaging;
}>;
/** Options for {@link showNexusCloudProject}. */
export interface NexusCloudProjectShowOptions extends NexusCloudOptions {
    /** The project; defaults to the current project. */
    projectId?: string;
}
/**
 * `cleo cloud projects show [<id>]`: E14 `GET /v1/projects/:projectId`. When
 * E14 cut its replica list at 50, the full list is read from E15.
 *
 * @param opts - Project id (default: the current project), paging and test overrides.
 * @returns The project detail.
 * @throws {NexusAccountError} `E_NEXUS_NOT_A_PROJECT` with no id outside a
 *   project; `E_NEXUS_REQUEST_FAILED` for an unknown or invisible project.
 */
export declare function showNexusCloudProject(opts?: NexusCloudProjectShowOptions): Promise<CloudProjectShowResult>;
/**
 * Which of `replicaIds` this device retired, from its replica registry
 * (read-only; never mints a device id). A retired replica stays listed by the
 * server as history until S4 announces it (T13109).
 *
 * @param replicaIds - Replica ids a server listing returned.
 * @returns The retired ones, newest first.
 */
export declare function retiredReplicasAmong(replicaIds: readonly string[]): Promise<CloudRetiredReplica[]>;
/**
 * Earlier replicas of the project store at `projectRoot` that this device
 * retired, from its replica registry (read-only; T13109).
 *
 * @param projectRoot - Project root.
 * @returns The retired replicas of that store file, newest first.
 */
export declare function retiredReplicasOfProject(projectRoot: string): Promise<CloudRetiredReplica[]>;
/**
 * The device credential store's location, for reports (never its contents).
 *
 * @param store - The store in use, if injected.
 * @returns Absolute path of `nexus-device.json`.
 */
export declare function nexusCloudCredentialsPath(store?: NexusDeviceStore): string;
export {};
//# sourceMappingURL=nexus-cloud.d.ts.map