/**
 * Copyright (c) 2026, Salesforce, Inc.,
 * All rights reserved.
 * For full license text, see the LICENSE.txt file
 */
/**
 * Library helpers that close two correctness gaps in any consumer
 * (CLI, MCP intent layer, eval harness) that turns a typed JSON spec
 * into a GraphQL operation:
 *
 *   - `promoteVariables` finds `$varName` string leaves anywhere in
 *     a filter / orderBy / scope value, infers each one's GraphQL
 *     type from the schema, and registers it on the session so the
 *     rendered operation declares the variables it references.
 *
 *   - `normalizeOrderBy` collapses an array-shaped orderBy input to
 *     a singleton object, matching Salesforce's connection-field
 *     `<Object>_OrderBy` schema. Tolerating the array shape is
 *     necessary for clients (and earlier MCP versions) that inferred
 *     a list type.
 *
 * Both are pure (or session-mutating but otherwise pure) and have no
 * dependency on the MCP server, the CLI, or any I/O. They live next
 * to `path-selection.ts` as the second piece of the "what every
 * graphiti consumer needs" library surface.
 */
import { type GraphQLSchema } from "graphql";
import { type QuerySession } from "./session.js";
/**
 * Recursively walks `value` looking for `$varName` string leaves. For
 * each one, infers the GraphQL type at that input path via
 * `inferTypeFromArgsPath` and calls `addVariable(session, name, type)`.
 * Promoted variables strip a trailing `!` (query variables are
 * nullable by convention; callers requiring NonNull use the `var`
 * command directly).
 *
 * If type inference throws — for example because the input path
 * doesn't exist on the schema — the helper falls back to `String`
 * rather than failing the whole render. A wrong-type variable is
 * easier for a user to debug than a hard error before they see their
 * query.
 *
 * @param session         Session to add variables to.
 * @param schema          The loaded GraphQL schema.
 * @param fieldSchemaPath Path of the field whose argument we are
 *                        promoting against (e.g. `["uiapi", "query",
 *                        "Account"]`).
 * @param argName         The argument name (`"where"`, `"orderBy"`,
 *                        `"scope"`).
 * @param value           The argument value — can be a primitive,
 *                        array, or nested object.
 * @param warnings        Optional warnings sink. Strings starting with
 *                        `$` that don't form a valid GraphQL Name
 *                        (e.g. `$1var`, `$foo-bar`) push a warning
 *                        here so callers see the typo instead of
 *                        silently rendering the literal.
 */
export declare function promoteVariables(session: QuerySession, schema: GraphQLSchema, fieldSchemaPath: string[], argName: string, value: unknown, warnings?: string[]): void;
/**
 * Result of promoting one whole argument. `rendered` is what the caller
 * hands to `deepSetArg`: the raw `$var` reference when the entire argument
 * was a single `$varName` string, or the JSON-stringified value otherwise.
 */
export interface ArgPromotion {
    rendered: string;
}
/**
 * Promote a `where` / `orderBy` argument that may be EITHER a normal
 * object (whose `$varName` leaves promote via `promoteVariables`) OR a
 * single top-level `$varName` string standing in for the whole argument.
 *
 * The whole-argument form is the idiomatic UIAPI pattern for an
 * optionally-applied filter: a `null`-bound `where` means "no constraint →
 * all rows", which a nullable leaf cannot express. When `value` is a
 * whole-arg placeholder we infer the argument's own input type
 * (e.g. `Case_Filter`, `Case_OrderBy`), declare one nullable variable, and
 * return its `$ref` so the caller renders `where: $filter` directly.
 *
 * Type inference for a real `where`/`orderBy` argument effectively never
 * fails, but if it does we still emit the variable as `String` and push a
 * loud warning — a best-effort query the user can debug beats a hard error
 * before they see anything.
 */
export declare function promoteArg(session: QuerySession, schema: GraphQLSchema, fieldSchemaPath: string[], argName: string, value: unknown, warnings?: string[]): ArgPromotion;
/**
 * Collapses an array-shaped orderBy input to its first element, so
 * callers can pass either shape without knowing Salesforce's
 * connection-field schema requires a singleton `<Object>_OrderBy`.
 *
 * - `[{Name: "ASC"}, ...]`  → `{Name: "ASC"}`
 * - `[]`                    → `undefined`
 * - `{Name: "ASC"}`         → unchanged
 * - `undefined`             → `undefined`
 */
export declare function normalizeOrderBy<T>(orderBy: T | T[] | undefined): T | undefined;