monday-cli 0.2.0

package/dist/api/client.js

@@ -0,0 +1,205 @@
+/**
+ * Monday GraphQL client over the injected `Transport`
+ * (`v0.1-plan.md` §3 M2).
+ *
+ * Why not the SDK's `ApiClient`. The plan's wording is
+ * "wraps `@mondaydotcomorg/api`'s `ApiClient`" but the SDK's
+ * `request()` doesn't accept an external `AbortSignal` — it builds
+ * its own controller per-call, which means the runner's SIGINT-ware
+ * abort can't cancel an in-flight request. Tests also need to swap
+ * the network stack without monkey-patching SDK internals (Codex
+ * review §2 of M0). Both problems are solved by the existing
+ * `Transport` interface, so the client routes every call through
+ * `transport.request()` and uses the SDK only for *types* — `Account`,
+ * `User`, `Complexity`, `Version`, `CURRENT_VERSION`.
+ *
+ * Header injection (`Authorization`, `API-Version`, `Content-Type`)
+ * lives in `FetchTransport` and is locked down (Codex review M0 §1
+ * follow-up). Caller-supplied headers can't override it; this client
+ * passes only operation-name and any future trace headers.
+ *
+ * Internal callers see `Record<string, unknown>` for variables. The
+ * SDK's `QueryVariables = Record<string, any>` boundary leak is
+ * contained at this module's edge — no `any` flows into `commands/*`.
+ */
+import { AvailableVersions } from '@mondaydotcomorg/api';
+import { mapResponse, wrapTransportError } from './errors.js';
+import { withRetry } from './retry.js';
+import { injectComplexity, parseComplexity } from './complexity.js';
+/**
+ * The Monday API version pinned to the SDK install. Re-exported so
+ * the production runner and `monday account version` read the same
+ * source of truth — bumping the SDK is the only way this changes.
+ */
+export const PINNED_API_VERSION = AvailableVersions.CURRENT_VERSION;
+const ME_QUERY = `
+  query Whoami {
+    me {
+      id
+      name
+      email
+      account {
+        id
+        name
+        slug
+      }
+    }
+  }
+`;
+const ACCOUNT_QUERY = `
+  query AccountInfo {
+    account {
+      id
+      name
+      slug
+      country_code
+      first_day_of_the_week
+      active_members_count
+      logo
+      plan {
+        version
+        tier
+        max_users
+        period
+      }
+    }
+  }
+`;
+const VERSIONS_QUERY = `
+  query Versions {
+    versions {
+      display_name
+      kind
+      value
+    }
+  }
+`;
+const COMPLEXITY_PROBE_QUERY = `
+  query ComplexityProbe {
+    complexity {
+      before
+      after
+      query
+      reset_in_x_seconds
+    }
+  }
+`;
+/**
+ * Returns `data` with any top-level `complexity` field removed.
+ * Used in `--verbose` mode where the injected selection lands in
+ * the data object alongside the typed leaf — the per-command
+ * outputSchema (strict) doesn't model it.
+ *
+ * Non-mutating: `data` is returned unchanged when no field is
+ * present, otherwise a shallow copy minus the field.
+ */
+const stripComplexity = (data) => {
+    if (data === null ||
+        typeof data !== 'object' ||
+        Array.isArray(data) ||
+        !('complexity' in data)) {
+        return data;
+    }
+    const { complexity: _complexity, ...rest } = data;
+    return rest;
+};
+export class MondayClient {
+    transport;
+    signal;
+    retries;
+    verbose;
+    retrySleep;
+    retryRandom;
+    constructor(config) {
+        this.transport = config.transport;
+        this.signal = config.signal;
+        this.retries = config.retries;
+        this.verbose = config.verbose;
+        this.retrySleep = config.retrySleep;
+        this.retryRandom = config.retryRandom;
+    }
+    /**
+     * Low-level escape hatch (`v0.1-plan.md` §3 M2 deliverable).
+     * `commands/raw` (M6) calls this directly; M2 commands use the
+     * typed wrappers. Returns the parsed `data` plus the per-request
+     * complexity meta and retry stats.
+     *
+     * Variables are typed `Record<string, unknown>` rather than the
+     * SDK's `any`-laced `QueryVariables` so the surface stays sealed.
+     */
+    raw = async (query, variables, options = {}) => {
+        // Only the verbose path injects the `complexity { ... }`
+        // selection at the operation root. We track whether we actually
+        // *added* it (vs the query already having it as a deliberate
+        // selection — e.g. `account complexity` queries the field as
+        // its only payload) so we know whether to strip it from `data`
+        // afterwards.
+        const injection = this.verbose
+            ? injectComplexity(query)
+            : { query, injected: false };
+        const finalQuery = injection.query;
+        const operationName = options.operationName;
+        const result = await withRetry(async () => {
+            try {
+                const response = await this.transport.request({
+                    query: finalQuery,
+                    ...(variables === undefined ? {} : { variables }),
+                    ...(operationName === undefined ? {} : { operationName }),
+                    signal: this.signal,
+                });
+                const mapped = mapResponse({
+                    status: response.status,
+                    headers: response.headers,
+                    body: response.body,
+                });
+                if (!mapped.ok) {
+                    throw mapped.error;
+                }
+                // Parse complexity off the *original* body — not the
+                // mapped data, which is shaped to the typed leaf.
+                const complexity = this.verbose
+                    ? parseComplexity(response.body)
+                    : null;
+                // Strip the `complexity` field from `data` *only* if we
+                // injected it ourselves — Monday returns the selection
+                // adjacent to whatever the operation requested, and the
+                // per-command outputSchema (strict) doesn't model it.
+                // When the caller's own query selects `complexity`
+                // directly (e.g. `account complexity`), leave it in
+                // place so the typed leaf survives.
+                let cleanedData = mapped.data;
+                if (injection.injected && complexity !== null) {
+                    cleanedData = stripComplexity(mapped.data);
+                }
+                return { data: cleanedData, complexity };
+            }
+            catch (err) {
+                // ApiError passes through unchanged; anything else (a bug
+                // in the transport, a rogue throw from a future SDK retry
+                // layer) becomes internal_error with cause set. The retry
+                // layer reads .retryable to decide.
+                throw wrapTransportError(err);
+            }
+        }, {
+            retries: this.retries,
+            signal: this.signal,
+            ...(this.retrySleep === undefined ? {} : { sleep: this.retrySleep }),
+            ...(this.retryRandom === undefined ? {} : { random: this.retryRandom }),
+        });
+        return {
+            data: result.value.data,
+            complexity: result.value.complexity,
+            stats: result.stats,
+        };
+    };
+    whoami = () => this.raw(ME_QUERY, undefined, { operationName: 'Whoami' });
+    account = () => this.raw(ACCOUNT_QUERY, undefined, { operationName: 'AccountInfo' });
+    versions = () => this.raw(VERSIONS_QUERY, undefined, { operationName: 'Versions' });
+    /**
+     * Cheapest possible call: just selects the `complexity` field with
+     * no payload. Used by `monday account complexity` to probe the
+     * budget without any other side-effect.
+     */
+    complexityProbe = () => this.raw(COMPLEXITY_PROBE_QUERY, undefined, { operationName: 'ComplexityProbe' });
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

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

package/dist/api/column-mapping.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `--columns-mapping <json>` parser (M11 — `monday item move`).
+ *
+ * The cross-board `item move` accepts a JSON object mapping source
+ * column IDs to target column IDs:
+ *
+ *   monday item move 12345 --to-group g --to-board 67890 \
+ *     --columns-mapping '{"status_4": "status_42", "due": "deadline"}'
+ *
+ * Maps directly to Monday's `move_item_to_board(columns_mapping:
+ * [ColumnMappingInput!])` parameter where `ColumnMappingInput =
+ * { source: ID!, target?: ID }` (verifiable in the SDK at
+ * `node_modules/@mondaydotcomorg/api/dist/esm/index.d.ts:551`) — the
+ * cli-side `{<src>: <target>}` shape transposes one-for-one onto the
+ * wire array `[{source: <src>, target: <target>}, ...]`.
+ *
+ * **What lives here.** Argv-time JSON parse + zod validation of the
+ * shape (object whose keys + values are non-empty strings).
+ * `usage_error` on any parse failure so agents see exit 1 with a
+ * useful detail decoration, not exit 2 `internal_error` from a bare
+ * ZodError.
+ *
+ * **What lives at the call site (`commands/item/move.ts`).** The
+ * unmatched-column check (whether each source ID exists on target,
+ * either via verbatim match or via the mapping). That's per-board
+ * metadata work — the parse boundary doesn't see metadata.
+ *
+ * **Value-overrides deferred to v0.3.** v0.2-plan §3 M11 mentioned
+ * accepting a richer `{<src>: { id: <target>, value: <override> }}`
+ * form whose `value` would re-run through M5a/M8's translator on
+ * target metadata. Monday's `ColumnMappingInput` doesn't carry a
+ * value slot, so the only way to ship value-overrides would be a
+ * non-atomic post-move `change_multiple_column_values` mutation —
+ * which adds partial-failure semantics with no precedent. Deferred;
+ * agents fire `monday item set <iid> <target>=<value>` post-move
+ * when they need value overrides. The simple form is enough for
+ * the M11 surface. v0.2-plan §15 captures the SDK-shape discovery.
+ *
+ * The argv layer in `commands/item/move.ts` calls
+ * `parseColumnMappingJson(rawString)` before the command's zod
+ * `inputSchema` runs; the schema then sees a typed `ColumnMapping`
+ * (not a JSON-blob string), keeping the schema narrow.
+ */
+/**
+ * The validated mapping shape. Keys are source column IDs (slugs),
+ * values are target column IDs (slugs). Empty `{}` is valid — the
+ * explicit "drop everything (Monday's permissive default)" opt-in
+ * per cli-design §8 decision 5.
+ */
+export type ColumnMapping = Readonly<Record<string, string>>;
+/**
+ * Parses + validates the raw `--columns-mapping <json>` argv value.
+ * Throws `UsageError` (exit 1) on any failure so agents see a useful
+ * decoration on the envelope rather than the runner's generic
+ * `internal_error`.
+ *
+ * Failure modes (all `usage_error`):
+ *   - Argv didn't supply a string (commander quirk, defensive).
+ *   - Empty string.
+ *   - Malformed JSON.
+ *   - JSON root isn't an object (`null`, array, primitive).
+ *   - Any value isn't a non-empty string (e.g. `{src: 42}`,
+ *     `{src: {id: "tgt"}}` — the latter is the v0.2-plan rich form
+ *     deferred to v0.3; we reject loudly so agents reading the error
+ *     know to omit the `value` slot for now).
+ */
+export declare const parseColumnMappingJson: (raw: unknown) => ColumnMapping;
+//# sourceMappingURL=column-mapping.d.ts.map

package/dist/api/column-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.d.ts","sourceRoot":"","sources":["../../src/api/column-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAe7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,GAAI,KAAK,OAAO,KAAG,aAoErD,CAAC"}

package/dist/api/column-mapping.js

@@ -0,0 +1,117 @@
+/**
+ * `--columns-mapping <json>` parser (M11 — `monday item move`).
+ *
+ * The cross-board `item move` accepts a JSON object mapping source
+ * column IDs to target column IDs:
+ *
+ *   monday item move 12345 --to-group g --to-board 67890 \
+ *     --columns-mapping '{"status_4": "status_42", "due": "deadline"}'
+ *
+ * Maps directly to Monday's `move_item_to_board(columns_mapping:
+ * [ColumnMappingInput!])` parameter where `ColumnMappingInput =
+ * { source: ID!, target?: ID }` (verifiable in the SDK at
+ * `node_modules/@mondaydotcomorg/api/dist/esm/index.d.ts:551`) — the
+ * cli-side `{<src>: <target>}` shape transposes one-for-one onto the
+ * wire array `[{source: <src>, target: <target>}, ...]`.
+ *
+ * **What lives here.** Argv-time JSON parse + zod validation of the
+ * shape (object whose keys + values are non-empty strings).
+ * `usage_error` on any parse failure so agents see exit 1 with a
+ * useful detail decoration, not exit 2 `internal_error` from a bare
+ * ZodError.
+ *
+ * **What lives at the call site (`commands/item/move.ts`).** The
+ * unmatched-column check (whether each source ID exists on target,
+ * either via verbatim match or via the mapping). That's per-board
+ * metadata work — the parse boundary doesn't see metadata.
+ *
+ * **Value-overrides deferred to v0.3.** v0.2-plan §3 M11 mentioned
+ * accepting a richer `{<src>: { id: <target>, value: <override> }}`
+ * form whose `value` would re-run through M5a/M8's translator on
+ * target metadata. Monday's `ColumnMappingInput` doesn't carry a
+ * value slot, so the only way to ship value-overrides would be a
+ * non-atomic post-move `change_multiple_column_values` mutation —
+ * which adds partial-failure semantics with no precedent. Deferred;
+ * agents fire `monday item set <iid> <target>=<value>` post-move
+ * when they need value overrides. The simple form is enough for
+ * the M11 surface. v0.2-plan §15 captures the SDK-shape discovery.
+ *
+ * The argv layer in `commands/item/move.ts` calls
+ * `parseColumnMappingJson(rawString)` before the command's zod
+ * `inputSchema` runs; the schema then sees a typed `ColumnMapping`
+ * (not a JSON-blob string), keeping the schema narrow.
+ */
+import { z } from 'zod';
+import { UsageError } from '../utils/errors.js';
+const columnMappingSchema = z.record(z.string().min(1, { message: 'expected a non-empty source column ID' }), z.string().min(1, { message: 'expected a non-empty target column ID' }));
+const summariseIssues = (err) => err.issues.map((issue) => ({
+    path: issue.path.map((p) => String(p)).join('.'),
+    message: issue.message,
+}));
+/**
+ * Parses + validates the raw `--columns-mapping <json>` argv value.
+ * Throws `UsageError` (exit 1) on any failure so agents see a useful
+ * decoration on the envelope rather than the runner's generic
+ * `internal_error`.
+ *
+ * Failure modes (all `usage_error`):
+ *   - Argv didn't supply a string (commander quirk, defensive).
+ *   - Empty string.
+ *   - Malformed JSON.
+ *   - JSON root isn't an object (`null`, array, primitive).
+ *   - Any value isn't a non-empty string (e.g. `{src: 42}`,
+ *     `{src: {id: "tgt"}}` — the latter is the v0.2-plan rich form
+ *     deferred to v0.3; we reject loudly so agents reading the error
+ *     know to omit the `value` slot for now).
+ */
+export const parseColumnMappingJson = (raw) => {
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new UsageError('--columns-mapping requires a non-empty JSON object literal', {
+            details: {
+                hint: "example: --columns-mapping '{\"status_4\": \"status_42\"}'; " +
+                    "use '{}' to accept Monday's permissive default (drop unmatched).",
+            },
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new UsageError(`--columns-mapping value isn't valid JSON: ${err instanceof Error ? err.message : String(err)}`, {
+            cause: err,
+            details: {
+                hint: "example: --columns-mapping '{\"status_4\": \"status_42\"}' " +
+                    '(quote the JSON in your shell to escape spaces and braces).',
+            },
+        });
+    }
+    // JSON.parse returns `unknown`; the zod schema rejects any non-
+    // object root (arrays + primitives). z.record's "expected object"
+    // path/code combination tells the agent the root shape was wrong.
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new UsageError('--columns-mapping must be a JSON object (e.g. {"status_4": "status_42"})', {
+            details: {
+                received_kind: parsed === null ? 'null' : Array.isArray(parsed) ? 'array' : typeof parsed,
+                hint: "use {} to accept Monday's permissive default (drop unmatched columns silently); " +
+                    'rich {id, value?} forms for cross-board value-overrides are deferred to v0.3.',
+            },
+        });
+    }
+    const result = columnMappingSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new UsageError(`--columns-mapping shape rejected: ${summariseIssues(result.error)
+            .map((i) => (i.path.length > 0 ? `${i.path}: ${i.message}` : i.message))
+            .join('; ')}`, {
+            cause: result.error,
+            details: {
+                issues: summariseIssues(result.error),
+                hint: 'expected {"<source_col_id>": "<target_col_id>", ...}; ' +
+                    'rich {id, value?} forms for value-overrides are deferred to v0.3 — fire ' +
+                    '`monday item set <iid> <target>=<value>` post-move when you need them.',
+            },
+        });
+    }
+    return result.data;
+};
+//# sourceMappingURL=column-mapping.js.map

package/dist/api/column-mapping.js.map

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

package/dist/api/column-mutation-result.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Live-mutation null-result projection for the M16 column lifecycle
+ * cluster (`v0.2-plan.md` §22 R45 lift).
+ *
+ * Three M16 verbs share a near-verbatim shape: null-check the wire
+ * payload, throw a typed ApiError on null carrying both
+ * `details.board_id` and `details.column_id` (the column-mutation
+ * wire signature is two-tuple — `create_column` carries
+ * `board_id` only pre-id, but the read-side projection always pairs
+ * the two), then parse through `columnProjectionSchema` to surface
+ * the §6.4 mutation envelope's `data: <projected snapshot>`.
+ *
+ * Lifted alongside the first M16 column verb commit (mirroring R39's
+ * "ship the projection helper alongside the first new mutation
+ * rather than as a follow-up R-class" precedent — the three M16
+ * verbs land in the same milestone, so adopting the helper from day
+ * one avoids three parallel inline implementations of the same
+ * shape). cf. R28 (`projectMutationItem`), R37 (`projectMutationUpdate`),
+ * R43 (`projectMutationBoard`); R45 ships the fourth per-noun
+ * helper at the same 3-consumer threshold.
+ *
+ * **Why parameterised on `errorCode` + `errorMessage`.** Like R28 /
+ * R37 / R43, the M16 verbs diverge in error semantics:
+ *   - `column-create` chose `internal_error` (every successful call
+ *     returns a Column — a null payload means Monday glitched server-
+ *     side, abnormal); the `details` carry `board_id` + `title` (no
+ *     column_id yet).
+ *   - `column-update` and `column-delete` chose `not_found`
+ *     (Monday's idiomatic null-for-missing-or-no-access response —
+ *     a typed agent-recovery story); both carry `board_id` +
+ *     `column_id`.
+ * The helper owns the boilerplate (null check, `details: { board_id,
+ * [columnIdKey]: columnIdValue }` envelope, the `unwrapOrThrow`
+ * schema parse); each call site supplies its own typed error parts.
+ *
+ * **`COLUMN_FIELDS_FRAGMENT` + `columnProjectionSchema` co-ship.**
+ * Mirrors R39's `WORKSPACE_FIELDS_FRAGMENT` + `workspaceProjection
+ * Schema` and R43's `BOARD_FIELDS_FRAGMENT` + `boardProjectionSchema`
+ * pattern. The schema mirrors the `columnSchema` already in
+ * `src/api/board-metadata.ts` (the read-side cache projection) but
+ * exists as an exported strict projection schema so M16's three
+ * mutation verbs share one source of truth for the on-the-wire
+ * Column shape.
+ *
+ * **What stays at the call site.** The wire-shape parse of the full
+ * mutation response (`responseSchema.safeParse(response.data)`) stays
+ * inline because each verb's response root key (`create_column` /
+ * `change_column_title` / `change_column_metadata` / `delete_column`)
+ * is per-verb. The missing-root-key check (schema-drift →
+ * `internal_error` with a `hint`) stays inline too — that's Codex
+ * M15 implementation round-2 F1's distinction between schema-drift
+ * and null-payload, deliberately preserved at each site. R42 would
+ * unify the missing-root-key check across all pre-M14 mutation verbs
+ * once scheduled.
+ */
+import { z } from 'zod';
+import { type ErrorCode } from '../utils/errors.js';
+/**
+ * Shared GraphQL selection set for the M16 column projection. 6-space
+ * continuation indent matches the column every consumer interpolates
+ * `${COLUMN_FIELDS_FRAGMENT}` at, so rendered query bytes stay
+ * stable across consumers. Mirrors `BOARD_FIELDS_FRAGMENT` (R43) and
+ * `WORKSPACE_FIELDS_FRAGMENT` (R39).
+ *
+ * Field set tracks `boardMetadataSchema.columns[*]` (the read-side
+ * cache projection) so a `board describe` after a successful column
+ * mutation returns the same JSON shape the mutation envelope did.
+ */
+export declare const COLUMN_FIELDS_FRAGMENT = "id\n      title\n      type\n      description\n      archived\n      settings_str\n      width";
+/**
+ * Strict zod schema for the column projection — the exact shape
+ * `COLUMN_FIELDS_FRAGMENT` selects from the wire. Shared by
+ * M16's `column-create` / `column-update` / `column-delete`; each
+ * verb's `CommandModule.outputSchema` aliases this so the schema-
+ * export pipeline emits one canonical shape.
+ *
+ * Mirrors `boardMetadataSchema.columns[*]` in `board-metadata.ts`
+ * verbatim — same fields, same nullability — so a `board describe`
+ * after a successful column mutation reads the same JSON shape the
+ * mutation envelope wrote.
+ */
+export declare const columnProjectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    archived: z.ZodNullable<z.ZodBoolean>;
+    settings_str: z.ZodNullable<z.ZodString>;
+    width: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export type ColumnProjection = z.infer<typeof columnProjectionSchema>;
+/**
+ * Column-mutation detail key — varies between create (`title` echo,
+ * since the new column id doesn't exist pre-call) and update / delete
+ * (`column_id`, since both operate on an existing column). All M16
+ * verbs additionally echo `board_id` because the column-mutation wire
+ * signature is two-tuple.
+ */
+export type ColumnMutationDetailKey = 'column_id' | 'title';
+export interface ProjectMutationColumnInputs {
+    readonly raw: unknown;
+    readonly errorCode: ErrorCode;
+    /**
+     * Full caller-formatted message for the null-payload throw — e.g.
+     * `"Monday returned no column payload from delete_column for board
+     * 12345 column status_4"`. Per-verb phrasing is preserved verbatim
+     * because agents key off the message text in error logs.
+     */
+    readonly errorMessage: string;
+    readonly boardId: string;
+    /**
+     * Whether the call site identifies the column by its already-known
+     * id (`column_id`, used by update / delete) or by the agent-supplied
+     * title (`title`, used by create — no id exists pre-call). The
+     * helper keys `details.<columnIdKey>` accordingly so agents key off
+     * the right field without having to switch on the verb.
+     */
+    readonly columnIdKey: ColumnMutationDetailKey;
+    readonly columnIdValue: string;
+}
+/**
+ * Parses + projects a live-mutation `Column` payload, throwing the
+ * supplied typed error on null/undefined. Caller owns the error code
+ * + message so create's `internal_error` / "no column payload from
+ * create_column for board <X> title <Y>" and update's / delete's
+ * `not_found` / "no column payload from <op> for board <X> column
+ * <Y>" both survive the lift byte-for-byte.
+ *
+ * `details: { board_id, [columnIdKey]: columnIdValue }` is supplied
+ * by the helper so every consumer carries the same envelope shape —
+ * agents key off `details.board_id` + `details.column_id` (or
+ * `details.title` on create's pre-id path) regardless of which verb
+ * threw (cli-design §6.5).
+ */
+export declare const projectMutationColumn: ({ raw, errorCode, errorMessage, boardId, columnIdKey, columnIdValue, }: ProjectMutationColumnInputs) => ColumnProjection;
+//# sourceMappingURL=column-mutation-result.d.ts.map

package/dist/api/column-mutation-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mutation-result.d.ts","sourceRoot":"","sources":["../../src/api/column-mutation-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,oGAMvB,CAAC;AAEb;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;kBAUxB,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,OAAO,CAAC;AAE5D,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,wEAOnC,2BAA2B,KAAG,gBAgBhC,CAAC"}