monday-cli 0.2.0

package/dist/api/errors.js

@@ -0,0 +1,434 @@
+/**
+ * Monday API → CLI error code mapper (`v0.1-plan.md` §3 M2,
+ * `cli-design.md` §2.5 / §6.5).
+ *
+ * The transport layer (`src/api/transport.ts`) already maps the
+ * lowest-level failures it sees: `fetch` exceptions → `network_error`,
+ * `AbortSignal.timeout` → `timeout`, malformed JSON →
+ * `network_error`. Everything else — HTTP status codes, GraphQL
+ * `errors[]` payloads, Monday's own application-level codes that
+ * arrive on `200 OK` — is interpreted *here* against the response
+ * body the transport hands back.
+ *
+ * Two consumers:
+ *
+ *  - `api/client.ts` calls `mapResponse(transportResponse)` on every
+ *    request. A non-error response returns `{ ok: true, data }`; an
+ *    error becomes `ApiError(<code>, ..., { httpStatus, mondayCode,
+ *    retryAfterSeconds, details })` for the retry layer to inspect.
+ *  - The retry layer (`api/retry.ts`) reads `error.retryable` and
+ *    `error.retryAfterSeconds` to decide.
+ *
+ * **No English-message keying.** Monday's error code dictionary is
+ * unstable across API versions; we extract the structured signals
+ * (`extensions.code`, `extensions.error_code`, HTTP status,
+ * `retry_in_seconds` / `Retry-After` headers) and ignore the prose.
+ */
+import { ApiError } from '../utils/errors.js';
+/**
+ * Reads the `Retry-After` header per RFC 7231 — either delta-seconds
+ * (an integer) or an HTTP-date. We accept the integer form only;
+ * date-form retries are rare in practice and computing the delta
+ * client-side hides clock-skew bugs.
+ */
+const parseRetryAfterHeader = (headers) => {
+    const lower = {};
+    for (const [k, v] of Object.entries(headers)) {
+        lower[k.toLowerCase()] = v;
+    }
+    const raw = lower['retry-after'];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n >= 0) {
+        return n;
+    }
+    return undefined;
+};
+const extractRetryInSeconds = (err) => {
+    if (err === undefined) {
+        return undefined;
+    }
+    const ext = err.extensions ?? {};
+    // Monday spells this several ways across versions.
+    const candidates = [
+        'retry_in_seconds',
+        'retryInSeconds',
+        'reset_in_seconds',
+        'resetInSeconds',
+    ];
+    for (const key of candidates) {
+        const v = ext[key];
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 0) {
+            return v;
+        }
+    }
+    return undefined;
+};
+/**
+ * Reads the `extensions.code` (preferred) or `extensions.error_code`
+ * field as a string, lower-casing for case-insensitive comparison.
+ * Returns undefined when the GraphQL error doesn't carry one.
+ */
+const extractMondayCode = (err) => {
+    if (err === undefined) {
+        return undefined;
+    }
+    const ext = err.extensions ?? {};
+    for (const key of ['code', 'error_code', 'errorCode']) {
+        const v = ext[key];
+        if (typeof v === 'string' && v.length > 0) {
+            return v;
+        }
+    }
+    return undefined;
+};
+/**
+ * Heuristic match of a single GraphQL error against Monday's
+ * documented application-level codes. The mapping intentionally
+ * looks at:
+ *   - `extensions.code` (Monday's structured channel)
+ *   - the bare error message (substring, case-insensitive) as a
+ *     fallback for older API versions or proxies that strip
+ *     extensions
+ *
+ * Returns `undefined` when no specific code matches; the caller
+ * decides whether to fall back to `validation_failed` /
+ * `internal_error`.
+ */
+const matchKnownGraphqlCode = (err) => {
+    const code = extractMondayCode(err)?.toUpperCase() ?? '';
+    const message = err.message.toLowerCase();
+    if (code === 'COMPLEXITYEXCEPTION' ||
+        message.includes('complexity budget exhausted') ||
+        message.includes('query has complexity')) {
+        return 'complexity_exceeded';
+    }
+    if (code === 'RATE_LIMIT_EXCEEDED' ||
+        code === 'MINUTE_LIMIT_EXCEEDED' ||
+        message.includes('minute limit rate exceeded')) {
+        return 'rate_limited';
+    }
+    if (code === 'DAILY_LIMIT_EXCEEDED' ||
+        message.includes('daily limit')) {
+        return 'daily_limit_exceeded';
+    }
+    if (code === 'CONCURRENCY_LIMIT_EXCEEDED' ||
+        code === 'CONCURRENCYLIMITEXCEEDED' ||
+        message.includes('concurrency limit')) {
+        return 'concurrency_exceeded';
+    }
+    if (code === 'IP_RATE_LIMIT_EXCEEDED' ||
+        message.includes('ip rate limit')) {
+        return 'ip_rate_limited';
+    }
+    if (code === 'UNAUTHORIZED' ||
+        code === 'AUTHENTICATION_ERROR' ||
+        message.includes('not authenticated') ||
+        message.includes('invalid token') ||
+        message.includes('invalid api token')) {
+        return 'unauthorized';
+    }
+    if (code === 'FORBIDDEN' ||
+        code === 'PERMISSION_DENIED' ||
+        code === 'NOT_AUTHORIZED' ||
+        message.includes('permission denied') ||
+        message.includes('not allowed')) {
+        return 'forbidden';
+    }
+    if (code === 'RESOURCE_NOT_FOUND' ||
+        code === 'NOT_FOUND' ||
+        code === 'INVALIDBOARDIDEXCEPTION' ||
+        code === 'INVALIDITEMIDEXCEPTION') {
+        return 'not_found';
+    }
+    if (code === 'RESOURCE_LOCKED' ||
+        code === 'INUSE') {
+        return 'resource_locked';
+    }
+    if (code === 'INVALID_CURSOR_EXCEPTION' ||
+        code === 'CURSOREXPIREDEXCEPTION' ||
+        message.includes('cursor expired') ||
+        message.includes('invalid cursor')) {
+        return 'stale_cursor';
+    }
+    if (code === 'COLUMNVALUEEXCEPTION' ||
+        code === 'INVALIDARGUMENTEXCEPTION' ||
+        code === 'INVALIDCOLUMNIDEXCEPTION' ||
+        code === 'VALIDATION_ERROR' ||
+        code === 'BAD_USER_INPUT') {
+        return 'validation_failed';
+    }
+    return undefined;
+};
+/**
+ * Default human-readable message per CLI code, used when the upstream
+ * error body has nothing prose-worthy to say. Frozen so a stray
+ * mutation can't reshape the surface mid-process.
+ */
+const DEFAULT_MESSAGE_FOR_CODE = Object.freeze({
+    unauthorized: 'Monday rejected the API token (unauthorized)',
+    forbidden: 'Monday refused the request (forbidden)',
+    rate_limited: 'Monday rate-limit hit — wait before retrying',
+    complexity_exceeded: 'Monday complexity budget exceeded — wait before retrying',
+    daily_limit_exceeded: 'Monday daily call limit exceeded',
+    concurrency_exceeded: 'Monday concurrency limit exceeded — too many in-flight requests',
+    ip_rate_limited: 'Monday IP rate-limit hit — wait before retrying',
+    resource_locked: 'Monday reported the resource is locked (HTTP 423)',
+    validation_failed: 'Monday rejected the request payload as invalid',
+    not_found: 'Monday could not find the requested resource',
+    stale_cursor: 'Pagination cursor expired (60-minute lifetime)',
+});
+const messageForCode = (code, err) => {
+    if (err !== undefined) {
+        return err.message;
+    }
+    return DEFAULT_MESSAGE_FOR_CODE[code] ?? 'Monday API error';
+};
+/**
+ * Maps Monday's top-level `error_code` (present on some non-200
+ * responses, parallel to `extensions.code` on the GraphQL path) to
+ * a CLI code. Used as a higher-priority signal than the bare HTTP
+ * status — a 429 carrying `error_code: "IP_RATE_LIMIT_EXCEEDED"`
+ * is `ip_rate_limited`, not the generic `rate_limited` the status
+ * alone would suggest. (Codex M2 review §3.)
+ */
+const mapTopLevelErrorCode = (code) => {
+    if (code === undefined)
+        return undefined;
+    const upper = code.toUpperCase();
+    if (upper === 'IP_RATE_LIMIT_EXCEEDED')
+        return 'ip_rate_limited';
+    if (upper === 'RATE_LIMIT_EXCEEDED' || upper === 'MINUTE_LIMIT_EXCEEDED') {
+        return 'rate_limited';
+    }
+    if (upper === 'DAILY_LIMIT_EXCEEDED')
+        return 'daily_limit_exceeded';
+    if (upper === 'CONCURRENCY_LIMIT_EXCEEDED')
+        return 'concurrency_exceeded';
+    if (upper === 'COMPLEXITYEXCEPTION')
+        return 'complexity_exceeded';
+    if (upper === 'UNAUTHORIZED' || upper === 'AUTHENTICATION_ERROR') {
+        return 'unauthorized';
+    }
+    if (upper === 'FORBIDDEN' || upper === 'PERMISSION_DENIED') {
+        return 'forbidden';
+    }
+    return undefined;
+};
+/**
+ * Maps an HTTP status (with no usable GraphQL `errors`) to a CLI
+ * error code. Used when Monday returns a non-200 with no structured
+ * payload — usually proxies or load balancers between us and the
+ * GraphQL server.
+ */
+const mapHttpStatus = (status) => {
+    if (status === 401)
+        return 'unauthorized';
+    if (status === 403)
+        return 'forbidden';
+    if (status === 404)
+        return 'not_found';
+    if (status === 423)
+        return 'resource_locked';
+    if (status === 429)
+        return 'rate_limited';
+    if (status >= 500 && status < 600)
+        return 'network_error';
+    if (status >= 400 && status < 500)
+        return 'validation_failed';
+    return undefined;
+};
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const asGraphQlBody = (body) => {
+    if (!isObject(body)) {
+        return undefined;
+    }
+    // Structural read: the consumer reads `data` / `errors` / `extensions`
+    // / top-level `error_*` slots; nothing here is asserted past
+    // `unknown` until the per-field guards downstream.
+    return body;
+};
+const collectGraphqlErrors = (body) => {
+    if (body === undefined)
+        return [];
+    if (!Array.isArray(body.errors))
+        return [];
+    const out = [];
+    for (const item of body.errors) {
+        if (!isObject(item))
+            continue;
+        const message = typeof item.message === 'string' ? item.message : '';
+        const extensions = isObject(item.extensions) ? item.extensions : undefined;
+        const path = Array.isArray(item.path)
+            ? item.path.filter((p) => typeof p === 'string' || typeof p === 'number')
+            : undefined;
+        out.push({
+            message,
+            ...(extensions === undefined ? {} : { extensions }),
+            ...(path === undefined ? {} : { path }),
+        });
+    }
+    return out;
+};
+const detailsForGraphqlError = (err) => {
+    const details = {};
+    if (err.extensions !== undefined) {
+        details.extensions = err.extensions;
+    }
+    if (err.path !== undefined && err.path.length > 0) {
+        details.path = err.path;
+    }
+    return details;
+};
+/**
+ * Maps a transport response to either a parsed `data` payload or an
+ * `ApiError`. The caller (`api/client.ts`) typically destructures:
+ *
+ *   const result = mapResponse<MyShape>(resp);
+ *   if (!result.ok) throw result.error;
+ *   return result.data;
+ *
+ * Throwing here would force every caller to have its own try/catch;
+ * returning a tagged result keeps the retry layer's loop linear.
+ */
+export const mapResponse = (input) => {
+    const body = asGraphQlBody(input.body);
+    const errors = collectGraphqlErrors(body);
+    const httpRetryAfter = parseRetryAfterHeader(input.headers);
+    // 1. HTTP 423 always maps to resource_locked (Monday's documented
+    //    contract — `cli-design.md` §2.5). This wins over any GraphQL
+    //    error array because 423 is a load-balancer / coordination
+    //    signal, not an application-level failure.
+    if (input.status === 423) {
+        const firstErr = errors[0];
+        const lockOpts = {
+            httpStatus: input.status,
+            details: {
+                ...(firstErr === undefined ? {} : detailsForGraphqlError(firstErr)),
+                ...(httpRetryAfter === undefined ? {} : { retry_after_seconds: httpRetryAfter }),
+            },
+        };
+        const lockMondayCode = firstErr === undefined ? undefined : extractMondayCode(firstErr);
+        if (lockMondayCode !== undefined) {
+            lockOpts.mondayCode = lockMondayCode;
+        }
+        if (httpRetryAfter !== undefined) {
+            lockOpts.retryAfterSeconds = httpRetryAfter;
+        }
+        return {
+            ok: false,
+            error: new ApiError('resource_locked', firstErr?.message ?? 'Monday reported the resource is locked (HTTP 423)', lockOpts),
+        };
+    }
+    // 2. GraphQL `errors[]` — present on most Monday application
+    //    failures, including ones that arrive on HTTP 200.
+    const [first] = errors;
+    if (first !== undefined) {
+        const matched = matchKnownGraphqlCode(first);
+        let code;
+        if (matched !== undefined) {
+            code = matched;
+        }
+        else {
+            // Last-resort fallback. Most unmapped Monday errors are
+            // user-input validation failures (bad column id, missing
+            // argument). Validation surfaces as exit 2 / non-retryable,
+            // matching the §6.5 contract.
+            code = 'validation_failed';
+        }
+        const retryInSeconds = extractRetryInSeconds(first) ?? httpRetryAfter;
+        const mondayCode = extractMondayCode(first);
+        const details = {
+            ...detailsForGraphqlError(first),
+        };
+        if (errors.length > 1) {
+            details.additional_errors = errors.slice(1).map((e) => ({
+                message: e.message,
+                ...(e.extensions === undefined ? {} : { extensions: e.extensions }),
+                ...(e.path === undefined || e.path.length === 0 ? {} : { path: e.path }),
+            }));
+        }
+        if (retryInSeconds !== undefined) {
+            details.retry_after_seconds = retryInSeconds;
+        }
+        return {
+            ok: false,
+            error: new ApiError(code, messageForCode(code, first), {
+                httpStatus: input.status,
+                ...(mondayCode === undefined ? {} : { mondayCode }),
+                ...(retryInSeconds === undefined ? {} : { retryAfterSeconds: retryInSeconds }),
+                details,
+            }),
+        };
+    }
+    // 3. Non-success HTTP without GraphQL errors. Treat the body as
+    //    opaque (it might be an HTML error page from a proxy).
+    if (input.status < 200 || input.status >= 300) {
+        // The body's top-level `error_code` is more specific than the
+        // HTTP status — a 429 carrying `IP_RATE_LIMIT_EXCEEDED` is
+        // `ip_rate_limited`, not `rate_limited` (Codex M2 review §3).
+        // Fall back to the status when the body has no error_code or
+        // it doesn't match a known signal.
+        const topLevelErrorCode = typeof body?.error_code === 'string' ? body.error_code : undefined;
+        const fallback = mapTopLevelErrorCode(topLevelErrorCode) ??
+            mapHttpStatus(input.status) ??
+            'network_error';
+        const details = {};
+        // Monday occasionally returns top-level `error_code` /
+        // `error_message` for non-200s.
+        if (body?.error_code !== undefined) {
+            details.error_code = body.error_code;
+        }
+        if (body?.error_message !== undefined) {
+            details.error_message = body.error_message;
+        }
+        if (httpRetryAfter !== undefined) {
+            details.retry_after_seconds = httpRetryAfter;
+        }
+        const errOpts = {
+            httpStatus: input.status,
+            details,
+        };
+        if (httpRetryAfter !== undefined) {
+            errOpts.retryAfterSeconds = httpRetryAfter;
+        }
+        if (typeof body?.error_code === 'string' && body.error_code.length > 0) {
+            errOpts.mondayCode = body.error_code;
+        }
+        return {
+            ok: false,
+            error: new ApiError(fallback, body?.error_message !== undefined && body.error_message.length > 0
+                ? body.error_message
+                : `Monday API returned HTTP ${String(input.status)}`, errOpts),
+        };
+    }
+    // 4. Success path. `body.data` may legitimately be `null` (Monday
+    //    returns `null` for missing-by-id queries with no errors); we
+    //    pass it through and the command-level zod parser is the next
+    //    line of defence.
+    const data = (body?.data ?? null);
+    return {
+        ok: true,
+        data,
+        ...(body?.extensions === undefined ? { extensions: undefined } : { extensions: body.extensions }),
+    };
+};
+/**
+ * Re-maps an unknown error caught around a transport call to a typed
+ * `MondayCliError`. The transport already throws `ApiError` for
+ * network/timeout failures; anything else (a bug in the SDK, a
+ * malformed cassette, a future SDK retry layer leaking a custom
+ * error type) falls through to `internal_error` so the runner's
+ * envelope still carries something agents can act on.
+ */
+export const wrapTransportError = (err) => {
+    if (err instanceof ApiError) {
+        return err;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const opts = { cause: err };
+    return new ApiError('internal_error', `unexpected transport error: ${message}`, opts);
+};
+//# sourceMappingURL=errors.js.map

package/dist/api/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"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"}

package/dist/api/filters.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Filter DSL parser (`cli-design.md` §5.5, `v0.1-plan.md` §3 M4).
+ *
+ * Two surfaces, one for each `monday item list` knob:
+ *
+ *   - `--where <token><op><val>` (repeatable) → parsed against §5.5's
+ *     allowlist (`=`, `!=`, `~=`, `<`, `<=`, `>`, `>=`, `:is_empty`,
+ *     `:is_not_empty`) and emitted as a Monday `query_params.rules`
+ *     object. Multiple `--where` flags are AND'd. Token resolution
+ *     reuses the M3 column read-resolver (`api/columns.ts`) so the
+ *     same NFC + case-fold rules apply across read and write surfaces.
+ *
+ *   - `--filter-json <json>` is the literal Monday `query_params`
+ *     object — never re-parsed. Power users / agents needing OR /
+ *     nested groups / `within_last(7d)` use this. v0.1's `--where`
+ *     surface is intentionally narrow; `--filter-json` is the escape
+ *     hatch.
+ *
+ * `--where` and `--filter-json` are **mutually exclusive**. Combining
+ * them would either force a merge rule (extra contract surface) or
+ * silently let one win — both are worse than failing fast with a
+ * `usage_error` and asking the agent to pick.
+ *
+ * **Operator-in-title trap.** When a column title contains an
+ * operator (`Plan A=B`), the implicit-resolution path can't
+ * disambiguate — `--where Plan A=B=approved` splits on the *first*
+ * `=` per §5.3 step 2.b, so the token resolves as `Plan A` and the
+ * value is `B=approved`. This is documented behaviour, not a bug.
+ * The `title:`/`id:` prefix doesn't help here either — `parseWhereSyntax`
+ * splits on the first operator before `parseColumnTokenPrefix`
+ * sees the token, so `title:Plan A=B=approved` still cleaves at
+ * the first `=`. The supported escape hatch for operator-in-title
+ * columns is `--filter-json`, where the agent passes the literal
+ * Monday `query_params` JSON; the rule's `column_id` is unambiguous
+ * and the value carries through verbatim. Codex M4 pass-2 §4
+ * surfaced this as a documentation backfill item — logged in
+ * v0.1-plan.md §3 M4 spec-gaps. The unit suite asserts the
+ * documented split verbatim so a future "be clever about it"
+ * patch fails loudly.
+ *
+ * **`me` sugar.** Per §5.5 + §5.3, `--where owner=me` against a
+ * `people` column resolves through the directory cache to the
+ * current user's ID. The resolution is a separate `whoami` query
+ * the parser issues on demand; tests inject a stub via the
+ * `resolveMe` callback so the pure-syntax layer stays
+ * unit-testable.
+ *
+ * **Result-type meta surface (§14 M3 prophylactic).** Even though
+ * filter parsing produces no network-derived data of its own
+ * (resolution is delegated to columns.ts + a `me`-resolver
+ * callback), the result type carries `warnings` from day one. The
+ * meta-source / cache-age / complexity slots travel through the
+ * board-metadata loader the caller has already opened — surfacing
+ * them again here would be redundant.
+ */
+import type { BoardMetadata } from './board-metadata.js';
+import type { Warning } from '../utils/output/envelope.js';
+/**
+ * Full set of `--where` operators per §5.5. The string is the source
+ * literal the user types; the kind is the AST tag downstream code
+ * consumes.
+ */
+export type FilterOperatorKind = 'equals' | 'not_equals' | 'contains_text' | 'lower_than' | 'lower_than_or_equals' | 'greater_than' | 'greater_than_or_equals' | 'is_empty' | 'is_not_empty';
+export interface FilterOperator {
+    readonly kind: FilterOperatorKind;
+    /** The literal operator string the user typed. */
+    readonly literal: string;
+    /**
+     * Whether the operator carries a value (`=`, `!=`, `~=`, `<`, `<=`,
+     * `>`, `>=`) or is a unary suffix (`:is_empty`, `:is_not_empty`).
+     * Drives the parser's value-extraction step.
+     */
+    readonly arity: 'unary' | 'binary';
+}
+/**
+ * Result of parsing one `--where` argument's *syntax*: the column
+ * token, operator, and (optional) value. No semantic resolution
+ * happens here — that's `buildFilterRules`'s job. Pure / synchronous
+ * by design so the unit suite can drive every adversarial input
+ * without a network mock.
+ */
+export interface WhereClause {
+    readonly token: string;
+    readonly operator: FilterOperator;
+    readonly value: string | undefined;
+    /** The original raw `--where` argument, kept for error messages. */
+    readonly raw: string;
+}
+/**
+ * Splits one raw `--where` argument into a {@link WhereClause}.
+ *
+ * Algorithm (left-to-right, longest-match-at-position):
+ *
+ *  1. Match `:is_not_empty` / `:is_empty` suffix on the right (with
+ *     `:is_not_empty` checked first so it doesn't get truncated to
+ *     the shorter form).
+ *  2. Otherwise scan position-by-position from index 1 (token must
+ *     be non-empty), trying each binary operator at that position.
+ *     The first match wins — earliest-leftmost-with-longest-tie-break.
+ *  3. If no operator is found, raise `UsageError`.
+ *
+ * Per §5.3 step 2.b, the split happens on the *first* operator
+ * occurrence — a column title containing an operator (`Plan A=B`)
+ * needs the explicit `title:` prefix or `--filter-json` to round-trip.
+ */
+export declare const parseWhereSyntax: (raw: string) => WhereClause;
+/**
+ * Filter rule emitted to Monday's `query_params.rules` array. The
+ * rule shape is intentionally weak (`compare_value: unknown`) — the
+ * v0.1 surface only types what we actually check; future operators
+ * (between, within_last) ride through `--filter-json` until M5b
+ * needs them.
+ */
+export interface FilterRule {
+    readonly column_id: string;
+    readonly operator: string;
+    readonly compare_value?: unknown;
+}
+export interface QueryParams {
+    readonly rules: readonly FilterRule[];
+}
+export interface BuildFilterRulesInputs {
+    readonly metadata: BoardMetadata;
+    /**
+     * Resolves the `me` token to the current user's ID. Async because
+     * the production path issues a `me { id }` query; tests stub it
+     * synchronously. Called at most once per build call regardless of
+     * how many `me` tokens appear in the clauses.
+     */
+    readonly resolveMe: () => Promise<string>;
+    readonly clauses: readonly WhereClause[];
+    /**
+     * Optional cache-miss refresh callback — when provided, the parser
+     * fires it once on the first `column_not_found` to retry the
+     * resolution against fresh metadata (Codex M4 §1: filters must
+     * honour §5.3 step 5). Caller should plumb `refreshBoardMetadata`
+     * here when the metadata came from cache; pass `undefined` when
+     * the metadata was already live (no refresh would help).
+     */
+    readonly onColumnNotFound?: () => Promise<BoardMetadata>;
+}
+export interface BuildFilterRulesResult {
+    readonly queryParams: QueryParams | undefined;
+    readonly warnings: readonly Warning[];
+    /**
+     * `true` when `onColumnNotFound` fired — caller flips
+     * `meta.source` to `'mixed'` and emits a `stale_cache_refreshed`
+     * warning per §5.3 step 5.
+     */
+    readonly refreshed: boolean;
+}
+/**
+ * Resolves each parsed `WhereClause` against the board metadata and
+ * emits the Monday `query_params` payload. Empty `clauses` →
+ * `queryParams: undefined` (caller omits the variable from the
+ * GraphQL request). Multiple clauses are AND'd by Monday's default
+ * rule-array semantics — no nested groups in v0.1.
+ *
+ * Throws `ApiError` (`column_not_found` / `ambiguous_column`) when
+ * column resolution fails — same shape `--set` will surface in M5b
+ * so agents key off the same code regardless of the read vs write
+ * channel.
+ */
+export declare const buildFilterRules: (inputs: BuildFilterRulesInputs) => Promise<BuildFilterRulesResult>;
+/**
+ * Validates a raw `--filter-json` string into a `query_params`-shaped
+ * object. Per §5.5, the payload is "never parsed; passed through as
+ * the GraphQL var" — the JSON.parse here is just a syntax check so a
+ * malformed input produces `usage_error` instead of a server-side
+ * parse error. Field-level shape validation stays on Monday's side.
+ */
+export declare const parseFilterJson: (raw: string) => Readonly<Record<string, unknown>>;
+/**
+ * Top-level helper for command actions. Consumes the two raw inputs
+ * (repeatable `--where` strings + optional `--filter-json` string)
+ * and returns a single `queryParams` object suitable for splatting
+ * into the GraphQL variables.
+ *
+ * The two inputs are mutually exclusive: passing both raises
+ * `usage_error`. Either one can be empty / undefined; both empty →
+ * `queryParams: undefined`.
+ */
+export interface BuildQueryParamsInputs {
+    readonly metadata: BoardMetadata;
+    readonly resolveMe: () => Promise<string>;
+    readonly whereClauses: readonly string[];
+    readonly filterJson: string | undefined;
+    /** Forwarded to `buildFilterRules` — see that interface. */
+    readonly onColumnNotFound?: () => Promise<BoardMetadata>;
+}
+export interface BuildQueryParamsResult {
+    readonly queryParams: Readonly<Record<string, unknown>> | undefined;
+    readonly warnings: readonly Warning[];
+    /** Forwarded from `buildFilterRules`. */
+    readonly refreshed: boolean;
+}
+export declare const buildQueryParams: (inputs: BuildQueryParamsInputs) => Promise<BuildQueryParamsResult>;
+//# sourceMappingURL=filters.d.ts.map

package/dist/api/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/api/filters.ts"],"names":[],"mappings":"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"}