import type { Query } from '../../types/jupiterone.js';
import { type J1QLValidator } from '../../utils/j1ql-validator.js';
import type { ToolResult } from './types.js';
import { type WidgetContractCheck } from './widget-render-contract.js';
/**
 * The HTTP status of an upstream authentication/authorization rejection, or `null` for any other
 * error. An account can stay in `list-accounts` (membership) yet fail live authorization — revoked,
 * disabled, or gated behind SSO — so these need their own message, not a raw envelope. Rejections
 * arrive three ways: a real 401/403, a GraphQL `extensions.code` (FORBIDDEN/UNAUTHENTICATED) inside
 * an HTTP 200, or, failing both, an authz-shaped message. Code/message hits map to the equivalent
 * status so callers get a consistent access-denied frame.
 */
export declare function accessDeniedStatus(error: unknown): number | null;
/** How the current server instance is bound to an account, for access-denied phrasing. */
export interface AccessDeniedContext {
    /** Whether the `list-accounts` discovery tool is registered on this server instance. */
    hasAccountDiscovery: boolean;
    /** The fixed account this instance is bound to (URL subdomain / env config), when single-tenant. */
    pinnedAccountId?: string;
}
/**
 * Agent-facing message for an access-denied upstream response. Three shapes:
 * - pinned + discovery (remote with a URL-pinned account): the binding is the problem — name it,
 *   steer to list-accounts + fixing the connector URL. Re-authenticating cannot fix a bad binding.
 * - pinned, no discovery (stdio env account): point at the configured account and credentials.
 * - multi-tenant: per-call accountId — steer to list-accounts and a different accountId.
 */
export declare function accessDeniedMessage(statusCode: number, context: AccessDeniedContext): string;
export declare function accessDeniedResult(statusCode: number, context: AccessDeniedContext): ToolResult;
/**
 * Generic error envelope for a thrown handler. Upstream GraphQL errors are already sanitized at
 * the shared client (S9), so `error.message` is safe to surface here. Access-denied (401/403)
 * errors are framed by the registration chokepoint before this is reached.
 */
export declare function toErrorResponse(error: unknown, context: string): ToolResult;
/** One query the static parse gate refused, named as the caller labelled it. */
export interface QueryValidationFailure {
    queryName: string;
    error: string;
    suggestion: string;
}
/**
 * Statically validate each J1QL query in a rule/widget definition before the create/update call.
 * Local parse only (see J1QLValidator.validateQuery) — instant, no backend round-trips.
 *
 * A query object can carry a second query: `drilldownQuery` is J1QL the widget stores and runs when
 * a reader clicks a data point. An invalid one fails at that click, days later, with nothing in the
 * create response to point at it — and the parse is already loaded here, so it costs nothing.
 */
export declare function validateQueries(queries: Query[] | undefined, validator: J1QLValidator): QueryValidationFailure[];
/**
 * Tool result for an execute-j1ql-query call rejected by the static parse gate. States plainly
 * that nothing ran — retrying with a fixed query is free and instant.
 */
export declare function invalidQueryResponse(validation: {
    error?: string;
    suggestion?: string;
}): ToolResult;
/** Tool result returned (as a non-throwing outcome) when pre-create query validation fails. */
export declare function createValidationErrorResponse(validationResults: QueryValidationFailure[]): ToolResult;
/** Validator-aware error for execute-j1ql-query: maps execution errors to actionable suggestions. */
export declare function createQueryErrorResponse(error: unknown, query: string, validator: J1QLValidator): ToolResult;
/** A widget query whose RETURN columns cannot render in the chosen chart type. */
export interface WidgetContractViolation {
    queryName: string;
    check: WidgetContractCheck;
    /**
     * Set when the widget carries no runnable query at all, so there is no RETURN clause to fix.
     * `markdown` is the only widget type that renders without one.
     */
    queryless?: true;
}
/**
 * Check each widget query against its chart type's column contract, before the create/update call.
 *
 * The sibling of `validateQueries`: that one catches queries the parser rejects, this one catches
 * queries the parser accepts but the renderer cannot draw. Both are local — no backend round-trip.
 * Returns only violations; advisory gaps (`missingRecommended`) are reported by the post-create
 * render preflight instead, because they never justify refusing the widget.
 *
 * The whole array is what decides some of the contract, not each query in isolation: a pie's `name`
 * column is required on a lone query and irrelevant on several, since a multi-query chart labels
 * its slices by query name. Passing the count keeps that decision here, where the widget's shape is
 * known, rather than at every call site.
 */
export declare function checkWidgetQueries(chartType: string | undefined, queries: Query[] | undefined): WidgetContractViolation[];
/**
 * Advisory notes for widget queries that pass the gate but are shaped oddly for their chart type.
 *
 * EACH query on a `number` widget is documented to return a single `value`, and the field report
 * behind TD-9016 was that extras "can break" it — but nothing has confirmed what the current
 * renderer does with them, so this warns and does not block.
 *
 * The count of queries is not what is being judged. A number widget legitimately carries several —
 * that is how percentage mode divides one query's total by another's — so the note has to say
 * "columns" where it means columns, or it teaches an agent to collapse a correct widget.
 */
export declare function widgetAdvisoryNotes(chartType: string | undefined, queries: Query[] | undefined): string[];
/**
 * Tool result for a widget rejected by the column-contract gate.
 *
 * Recovery stays in-band: the widget was not created, and the response carries a ready-to-run
 * corrected query wherever one could be derived and re-verified — retrying is free and instant.
 */
export declare function widgetContractErrorResponse(chartType: string, violations: WidgetContractViolation[], operation?: 'create' | 'update'): ToolResult;
//# sourceMappingURL=errors.d.ts.map