import { ConflictReport } from "./types.js";

//#region src/lib/errors.d.ts

/**
 * Every code a {@link PlatformError} can carry. Stable identifiers — consumers can rely on
 * these for `instanceof PlatformError && err.code === ErrorCode.…` style checks instead of
 * matching on free-text messages.
 *
 * Grouped by source:
 * - `PLATFORM_INVALID_CONFIG` — `defineConfig` / `configSchema` rejected the input.
 * - `PLATFORM_MISSING_CONTEXT` — no project / branch context could be resolved.
 * - `PLATFORM_PUSH_CONFLICT` — local config conflicts with remote and the caller did not
 *   opt in to apply.
 * - `PLATFORM_CONFIG_LOAD_FAILED` — `neon.ts` could not be found or evaluated.
 * - `PLATFORM_MISSING_API_KEY` — no `NEON_API_KEY` and no explicit `apiKey` was provided.
 * - `PLATFORM_MISSING_PARENT_BRANCH` — push tried to create a child of a non-existent
 *   branch.
 * - `PLATFORM_PARTIAL_BRANCH_CREATE` — `createBranch` created the branch but failed to
 *   apply its policy, so the branch exists without its declared settings.
 * - `PLATFORM_UNAUTHORIZED` / `PLATFORM_FORBIDDEN` / `PLATFORM_NOT_FOUND` /
 *   `PLATFORM_CONFLICT` / `PLATFORM_RATE_LIMITED` / `PLATFORM_LOCKED` /
 *   `PLATFORM_SERVER_ERROR` — wrappings of Neon HTTP failures.
 * - `PLATFORM_NETWORK_ERROR` — transport-level failure (no HTTP response at all).
 * - `PLATFORM_INTERNAL_ERROR` — invariant violations. Should never happen in production;
 *   if you see one, please open an issue.
 */
declare const ErrorCode: {
  readonly InvalidConfig: "PLATFORM_INVALID_CONFIG";
  readonly EnvNotInjected: "PLATFORM_ENV_NOT_INJECTED";
  readonly MissingContext: "PLATFORM_MISSING_CONTEXT";
  readonly PushConflict: "PLATFORM_PUSH_CONFLICT";
  readonly PushAborted: "PLATFORM_PUSH_ABORTED";
  readonly ConfigLoadFailed: "PLATFORM_CONFIG_LOAD_FAILED";
  readonly MissingApiKey: "PLATFORM_MISSING_API_KEY";
  readonly AmbiguousBranchAuth: "PLATFORM_AMBIGUOUS_BRANCH_AUTH";
  readonly BranchNotFound: "PLATFORM_BRANCH_NOT_FOUND";
  readonly FeatureUnavailable: "PLATFORM_FEATURE_UNAVAILABLE";
  readonly MissingParentBranch: "PLATFORM_MISSING_PARENT_BRANCH";
  readonly PartialBranchCreate: "PLATFORM_PARTIAL_BRANCH_CREATE";
  readonly Unauthorized: "PLATFORM_UNAUTHORIZED";
  readonly Forbidden: "PLATFORM_FORBIDDEN";
  readonly NotFound: "PLATFORM_NOT_FOUND";
  readonly Conflict: "PLATFORM_CONFLICT";
  readonly RateLimited: "PLATFORM_RATE_LIMITED";
  readonly Locked: "PLATFORM_LOCKED";
  readonly ServerError: "PLATFORM_SERVER_ERROR";
  readonly NetworkError: "PLATFORM_NETWORK_ERROR";
  readonly InternalError: "PLATFORM_INTERNAL_ERROR";
};
type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
/**
 * Base class for all errors thrown by `@neon/config`. Always extend this so callers
 * can catch every package-thrown error with a single `instanceof` check.
 *
 * Optional `details` carries structured context that the CLI prints under `--debug` and
 * that programmatic consumers can read (e.g. `details.status` for HTTP wrappings,
 * `details.requestId` for Neon API failures).
 */
declare class PlatformError extends Error {
  readonly name: string;
  readonly code: string;
  readonly details: Readonly<Record<string, unknown>>;
  constructor(code: string, message: string, options?: {
    cause?: unknown;
    details?: Record<string, unknown>;
  });
}
/**
 * Structural check for a {@link PlatformError}.
 *
 * Prefer this over a bare `instanceof PlatformError` whenever the error may have crossed a
 * module-realm boundary. A `neon.ts` loaded through jiti imports its *own* copy of this
 * package, so a `PlatformError` thrown while evaluating it has a different class identity
 * than ours and fails `instanceof` — but its stable string `code` (always prefixed
 * `PLATFORM_`) survives the boundary intact, which is what we match on here.
 */
declare function isPlatformError(value: unknown): value is PlatformError;
/**
 * Append a "report-a-bug" footer to an error message. Used only on truly unreachable
 * internal errors — never on user-facing validation / configuration errors where the user
 * is supposed to fix something on their end.
 */
declare function bugReportFooter(): string;
/**
 * Thrown by {@link defineConfig} when the user-provided configuration object is invalid.
 *
 * The class collects every validation failure rather than throwing on the first one so that
 * users get a complete picture of what is wrong with their `neon.ts`.
 */
declare class ConfigValidationError extends PlatformError {
  readonly name = "ConfigValidationError";
  readonly issues: readonly string[];
  constructor(issues: readonly string[]);
}
/**
 * Thrown when the package cannot resolve which Neon project to operate on.
 *
 * Per the package's read-only-filesystem contract, we never create a `.neon` context file;
 * callers must either pass `projectId`/`orgId` explicitly or rely on an existing context file
 * (`.neon/project.json` or neonctl's `.neon`).
 */
declare class MissingContextError extends PlatformError {
  readonly name = "MissingContextError";
  constructor(message: string);
}
/**
 * Thrown by {@link pushConfig} when it detects differences between the local config and
 * the remote project that the caller hasn't opted in to apply.
 *
 * The message lists every conflict with both the current and desired value plus a
 * per-conflict hint. Mutable branch drift is applied by passing `updateExisting: true`.
 */
declare class PushConflictError extends PlatformError {
  readonly name = "PushConflictError";
  readonly conflicts: readonly ConflictReport[];
  constructor(conflicts: readonly ConflictReport[]);
}
/**
 * Thrown by {@link pushConfig} when the caller-supplied `confirm` callback declines a
 * push that requires confirmation (protected branch and/or mutable drift overriding
 * existing remote settings).
 *
 * The CLI maps this to a non-zero exit so users see "aborted" rather than a stack trace.
 */
declare class PushAbortedError extends PlatformError {
  readonly name = "PushAbortedError";
  readonly branchName: string;
  readonly reasons: readonly ("protected-branch" | "override-updates")[];
  constructor(branchName: string, reasons: readonly ("protected-branch" | "override-updates")[]);
}
/**
 * Thrown by `createBranch` when the branch was created but pushing its `neon.ts` policy onto
 * it failed — e.g. the API rejected a declared compute setting, or a service could not be
 * provisioned. The branch is **real**: it exists with its creation-time `parent` but without
 * the rest of its declared settings.
 *
 * The created branch's id/name are carried on the error so callers can keep it usable (pin it,
 * report it) instead of leaving a branch behind that no one knows diverges from the policy.
 * Nothing re-applies a policy to an *existing* branch implicitly, so recovering takes an
 * explicit apply with `updateExisting: true` (SDK) / `--update-existing` (CLI).
 */
declare class PartialBranchCreateError extends PlatformError {
  readonly name = "PartialBranchCreateError";
  readonly branchId: string;
  readonly branchName: string;
  /**
   * Why the policy failed, taken from the underlying error — what Neon actually rejected.
   * Exposed separately from {@link message} so a caller that has already reported the created
   * branch can show just the reason.
   */
  readonly reason: string;
  constructor(branchId: string, branchName: string, cause: unknown);
}
/**
 * Structural check for a {@link PartialBranchCreateError}, matching on the stable `code` and
 * the branch fields rather than class identity — same realm-crossing rationale as
 * {@link isPlatformError}.
 */
declare function isPartialBranchCreateError(value: unknown): value is PartialBranchCreateError;
/**
 * Thrown when the SDK fails to find or load a `neon.ts` config file.
 */
declare class ConfigLoadError extends PlatformError {
  readonly name = "ConfigLoadError";
  constructor(message: string, options?: {
    cause?: unknown;
  });
}
//#endregion
export { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, bugReportFooter, isPartialBranchCreateError, isPlatformError };
//# sourceMappingURL=errors.d.ts.map