monday-cli 0.3.0 → 0.5.0

package/README.md

@@ -49,41 +49,91 @@ Requires **Node.js ≥ 22**.
 #    Get one at https://<your-org>.monday.com/admin/integrations/api
 #
 #    OAuth login (`monday auth login`) is registered but deferred in
-#    v0.3.0 — the verb surfaces a clear `usage_error.details.reason:
+#    v0.5.0 — the verb surfaces a clear `usage_error.details.reason:
 #    oauth_unregistered` pointing here. Authenticate via the env var.
 export MONDAY_API_TOKEN="<your-token>"
 
 # 2. Smoke test — confirm the token works.
 monday account whoami --json
 
-# 3. Is everything wired up? (v0.3 diagnostics cluster)
-monday status --json                    # 7-probe DNS/TCP/TLS/auth/cache matrix
-monday usage --json                     # remaining daily Monday API operations
+# 3. Install shell completion (v0.4-M33 — bash / zsh / fish).
+#    The default mode emits raw script bytes on stdout (so the redirect
+#    works); `--json` opts INTO the §6 envelope.
+monday completion bash >> ~/.bashrc        # or .zshrc / config.fish
 
-# 4. List a board's items (replace 12345 with your board ID)
+# 4. Is everything wired up? (v0.3 diagnostics cluster)
+monday status --json                       # 7-probe DNS/TCP/TLS/auth/cache matrix
+monday usage --json                        # remaining daily Monday API operations
+
+# 5. List a board's items (replace 12345 with your board ID)
 monday item list --board 12345 --json
 
-# 5. File a new task (v0.2)
+# 6. File a new task (v0.2)
 monday item create --board 12345 --name "Refactor login" \
   --set status=Backlog --set 'Due date'=+1w --json
 
-# 6. Find-or-create with idempotent matching (v0.2)
-#    Re-running with the same args is safe — 0/1/2+ matches route to
-#    create / update / `ambiguous_match` (one of the 29 stable error codes).
+# 7. Long-poll for activity on an item (v0.4-M29 — NDJSON stream).
+#    Per-event NDJSON record + a `{"_meta": {...}}` trailer carrying
+#    the session counters. Use `--once` to drain backlog without
+#    polling further; SIGINT (Ctrl-C) drains gracefully and exits 130.
+monday item watch 67890 --once             # or --max-events 50 --max-duration 1h
+
+# 8. Upload a file to a column or update (v0.4-M31 — multipart wire).
+#    `add_file_to_column` for item columns; `add_file_to_update` for
+#    comment attachments. Both surface `--dry-run` for an envelope
+#    preview without the multipart round-trip.
+monday item upload 67890 --column 'Attachments' ./screenshot.png --json
+monday update upload <update-id> ./diagram.png --json
+
+# 9. Parallel partial-success bulk updates (v0.4-M30).
+#    `--concurrency <N>` (range 1..32) opts into parallel dispatch on
+#    the M25 partial-success path. Envelope is byte-equivalent to the
+#    sequential `--concurrency 1` default; input order is preserved
+#    in `data.results[]` regardless of completion order.
+monday item update --where status=Backlog --set status='Working on it' \
+  --board 12345 --yes --continue-on-error --concurrency 4 --json
+
+# 10. Browse the workdocs surface (v0.4-M32 — read-only at v0.4).
+monday doc list --workspace 5 --order-by used_at --limit 10 --json
+monday doc get 88001 --json                # full Document with blocks
+
+# 11. Workdocs CRUD (v0.5-M35 + v0.5-M36 + v0.5-M37 — the full
+#     mutation surface deferred at v0.4-M32 D8 closure).
+#     Doc-level CRUD (M35): create / rename / delete / duplicate.
+monday doc create-in-workspace --workspace 5 --name "Design notes" --json
+monday doc rename 88001 --name "Design notes (v2)" --json
+monday doc duplicate 88001 --with-updates --json
+monday doc delete 88001 --yes --json
+#     Doc-block CRUD (M36): block-create / block-update / block-delete.
+#     16-value `DocBlockContentType` enum for `--type`.
+monday doc block-create 88001 --type normal_text --content '{"text":"hi"}' --json
+#     Bulk import from HTML / markdown (M37): no per-block round-trips.
+monday doc import-html --workspace 5 --html ./page.html --title "Imported" --json
+monday doc append-markdown 88001 --markdown ./notes.md --json
+
+# 12. Team writers (v0.5-M34 — deferred from v0.4 at the post-M33
+#     candidate-selection session). Six new verbs under `monday user`.
+monday user team-list --json
+monday user team-create --name "Platform" --users 7,9 --json
+monday user team-add-members <tid> --users 11,13 --json
+
+# 13. Find-or-create with idempotent matching (v0.2)
+#     Re-running with the same args is safe — 0/1/2+ matches route to
+#     create / update / `ambiguous_match` (one of the 29 stable error codes).
 monday item upsert --board 12345 --name "Refactor login" \
   --match-by name --set status='Working on it' --json
 
-# 7. Move a ticket forward, then comment on it
+# 14. Move a ticket forward, then comment on it
 monday item set 67890 status=Done --json
 monday update create 67890 --body "Shipped in PR #1234" --json
 
-# 8. Monday Dev convention layer (v0.3 — sprint/epic/release/task)
-#    First-time setup auto-detects boards by Monday's stock template names.
-monday dev discover --apply --json      # writes ~/.monday-cli/config.toml
-monday dev sprint current --json        # the active sprint
-monday dev task list --mine --json      # my open tasks
+# 15. Monday Dev convention layer (v0.3 — sprint/epic/release/task)
+#     First-time setup auto-detects boards by Monday's stock template names.
+monday dev discover --apply --json         # writes ~/.monday-cli/config.toml
+monday dev sprint current --json           # the active sprint
+monday dev task list --mine --json         # my open tasks
 
-# 9. Outbound writes (v0.3 — webhooks + notifications)
+# 16. Outbound writes (v0.3 — webhooks + notifications)
 monday webhook list 12345 --json
 monday notification send --user 7 --target 67890 \
   --target-type item --text "PTAL" --json
@@ -152,7 +202,7 @@ Every JSON response uses the same universal envelope:
   "meta": {
     "schema_version": "1",
     "api_version": "2026-01",
-    "cli_version": "0.3.0",
+    "cli_version": "0.5.0",
     "request_id": "0e6f1a7b-...",
     "source": "live",
     "cache_age_seconds": null,
@@ -252,7 +302,38 @@ See [`.env.example`](./.env.example) for all supported variables
 
 ## Scope
 
-**v0.3.0 (current — `monday-cli@0.3.0` on npm):**
+**v0.5.0 (current — `monday-cli@0.5.0` on npm):**
+the v0.4 surface PLUS the full team-writer surface
+(`monday user team-list/get/create/delete/add-members/remove-members`),
+the full Monday workdocs CRUD mutation surface — doc-level
+(`monday doc create-in-workspace/create-on-column/rename/delete/duplicate`),
+doc-block (`monday doc block-create/block-update/block-delete`),
+and doc-content import (`monday doc import-html/append-markdown`) —
+closing the v0.4-M32 workdocs-mutation deferral. **16 new CLI
+verbs across 9 wire mutations.** **No breaking changes vs v0.4.0**
+— every v0.5 surface is additive. Built incrementally across
+M34–M37. See [CHANGELOG.md](./CHANGELOG.md) for the full
+per-milestone release notes.
+
+**OAuth deferral (unchanged from v0.4.0).** `monday auth login` is
+registered but the canonical Monday OAuth app is not registered in
+v0.5.0; the verb surfaces a clear `usage_error.details.reason:
+oauth_unregistered` pointing at `MONDAY_API_TOKEN`. Multi-profile
+config + per-profile credentials cache work fully against API
+tokens; OAuth registration revisits in v0.5.x / v0.6 contingent on
+user demand.
+
+**v0.4.0 (the previous release):**
+the v0.3 surface PLUS long-poll item activity streaming
+(`monday item watch <iid>` — NDJSON), parallel bulk dispatch
+(`monday item update --where ... --concurrency <N>`), asset uploads
+(`monday item upload` / `monday update upload` — multipart wire),
+Monday workdocs reads (`monday doc list` / `monday doc get` — full
+workdocs CRUD mutation surface deferred to v0.5; shipped at v0.5),
+and shell completion (`monday completion bash|zsh|fish`). Built
+incrementally across M29–M33.
+
+**v0.3.0 (the prior release):**
 the v0.2 mutating core PLUS the Monday Dev convention layer
 (`monday dev` namespace — sprint / epic / release / task workflow
 shortcuts on top of standard board CRUD), multi-profile auth
@@ -266,17 +347,8 @@ outbound writes (`monday webhook list/create/delete` +
 (`tags`, `board_relation`, `dependency`) closing the v0.2
 tentative-row carryover. **No breaking changes vs v0.2.0** — every
 v0.3 surface is additive. Built incrementally across M19–M28.
-See [CHANGELOG.md](./CHANGELOG.md) for the full per-milestone
-release notes.
-
-**OAuth deferral.** `monday auth login` is registered but the
-canonical Monday OAuth app is not registered in v0.3.0; the verb
-surfaces a clear `usage_error.details.reason: oauth_unregistered`
-pointing at `MONDAY_API_TOKEN`. Multi-profile config + per-profile
-credentials cache work fully against API tokens; OAuth registration
-revisits in v0.3.x / v0.4 contingent on user demand.
 
-**v0.2.0 (the previous release):**
+**v0.2.0 (the foundation-of-mutations release):**
 the v0.1 read-only core + safe-mutations surface PLUS the full
 mutation surface (item lifecycle, update mutations, workspace
 lifecycle, board lifecycle, board columns + groups). Built
@@ -461,15 +533,113 @@ row `tags`, `board_relation`, `dependency`.
   deferred out of v0.3 per Decision 11 (Monday's `sub_items_board`
   carries no `subtasks` column at API `2026-01`).
 
-**v0.4:** `monday item watch`, `--concurrency` bulk parallelism,
-asset uploads, multi-level subitems if Monday's data model
-surfaces them.
+**What v0.4 added (M29–M33; full per-milestone narrative in
+[CHANGELOG.md](./CHANGELOG.md)):**
+
+- **M29** — `monday item watch <iid>` long-polls `boards.activity_
+  logs(item_ids:)` for per-item event streaming. NDJSON output:
+  one event record per emitted activity-log row + a trailing
+  `{"_meta": {...}}` record carrying the seven session counters
+  (`events_emitted` / `polls_made` / `failed_polls` /
+  `last_seen_event_id` / `circuit_broken_at` / `exit_reason` /
+  `watch_duration_seconds`). `--once` drains backlog and exits
+  without polling further; `--max-events` / `--max-duration`
+  ceilings exit cleanly; SIGINT drains gracefully + exits 130.
+  Circuit-breaker trips after 5 consecutive `complexity_exceeded`
+  polls.
+- **M30** — `monday item update --where ... --concurrency <N>`
+  (range 1..32; default 1) opts into bounded parallel dispatch on
+  the M25 partial-success path. Envelope is byte-equivalent to the
+  sequential default; input order is preserved in `data.results[]`
+  regardless of completion order. `--concurrency 1` routes through
+  `dispatchSequential`; `> 1` routes through `dispatchParallel`.
+- **M31** — `monday item upload <iid> --column <col> <file>` +
+  `monday update upload <update-id> <file>` ship the first multipart
+  wire surface (`add_file_to_column` / `add_file_to_update`). Both
+  surface `--dry-run` for a planned-change envelope preview without
+  the multipart round-trip. Uploads are non-idempotent (each
+  successful call mints a fresh `Asset` ID); cache invalidation
+  fires single-leg on success. Read-side `item assets` / `update
+  assets` verbs deferred to v0.4.x per M31 Decision D6.
+- **M32** — `monday doc list [--workspace <wid>,...] [--order-by
+  <created_at|used_at>] [--limit <n>] [--page <n>]` + `monday doc
+  get <did>` ship read-only access to Monday's workdocs surface
+  (`Query.docs(...)`). Page/limit pagination (no cursor on this
+  Monday surface). The full workdocs CRUD mutation surface (9
+  mutations: `create_doc` / `update_doc_name` / `delete_doc` /
+  `duplicate_doc` / `import_doc_from_html` / `add_content_to_doc_
+  from_markdown` / `create_doc_block` / `update_doc_block` /
+  `delete_doc_block`) is deferred to v0.5.
+- **M33** — `monday completion <bash|zsh|fish>` ships shell
+  completion script generation. The default mode emits raw script
+  bytes on stdout regardless of TTY/pipe context (so `monday
+  completion bash >> ~/.bashrc` works as a sourceable file —
+  cli-design §3.1 #2 raw-bytes carve-out); `--json` opts INTO the
+  §6 envelope with `data: { shell, script }`. Hand-rolled per-shell
+  templates (commander 14.0.3 ships no built-in completion
+  machinery, verified by empirical probe at M33 pre-flight).
+
+**What v0.5 added (M34–M37; full per-milestone narrative in
+[CHANGELOG.md](./CHANGELOG.md)):**
+
+- **M34** — `monday user team-list/get/create/delete/add-members/
+  remove-members` ship the full team-writer surface. The two read
+  verbs (`team-list` / `team-get`) close the v0.4-M33 candidate-
+  selection deferral; the four mutations introduce a new partial-
+  success projection for `team-add-members` / `team-remove-members`
+  (Monday's `change_team_memberships` returns `failed_users` +
+  `successful_users` lists; the CLI projects to the universal §6.1
+  `results: [{user_id, ok, ...}]` shape with input-order preserved
+  + failed-bucket-priority discipline).
+- **M35** — `monday doc create-in-workspace/create-on-column/rename/
+  delete/duplicate` ship the doc-level CRUD writer surface. Two
+  create variants (per D7) — `create-in-workspace` (`--workspace`
+  required + optional `--folder` / `--kind`) vs `create-on-column`
+  (`--item` + `--column` against an existing file-shaped column).
+  `rename` (`update_doc_name`), `delete --yes` (`delete_doc` — the
+  destructive verb in the cluster), and `duplicate [--with-updates]`
+  (`duplicate_doc`) round out the lifecycle. Backed by 4 Monday
+  wire mutations.
+- **M36** — `monday doc block-create/block-update/block-delete`
+  ship the doc-block CRUD surface. `--type <DocBlockContentType>`
+  takes one of 16 enum values (`normal_text` / `large_title` /
+  `quote` / `bulleted_list` / `check_list` / `code` / `divider` /
+  …) per D10 closure. `--content <json>` (parsed via the M27-lifted
+  `parseJsonArg` helper). Per-type content payload shapes
+  documented in `docs/output-shapes.md` "Per-block content shapes"
+  reference table — 7 cassette-pinned variants + 9 TBD / inferred
+  variants awaiting follow-up cassettes per D11.
+- **M37** — `monday doc import-html/append-markdown` ship bulk
+  doc-content import in a single wire round-trip (no per-block
+  loop). `import-html` creates a new doc from an HTML payload;
+  `append-markdown` appends blocks to an existing doc from a
+  markdown payload. Both surface mutex argv sources
+  (`--html <file|-> | --html-string <s>` /
+  `--markdown <file|-> | --markdown-string <s>`) backed by the new
+  generic `readSourceContent` helper at `src/utils/source-content.ts`
+  (R-v0.5-NEW-18 lifted ahead-of-feat from M13's `readUpdateBody`
+  — 5 consumers post-lift). Wire-side payload cap pre-empted at
+  parse boundary via `MAX_DOC_IMPORT_PAYLOAD_BYTES = 256_000` per
+  D13 empirical-probe pinning (rejected at 500KB, OK at 250KB on
+  both surfaces).
+
+**v0.6 (next):** multi-level subitems remain conditional on
+Monday's data model surfacing them (slipped from v0.4 → v0.5 →
+v0.6 across two consecutive release-preps — Monday's
+`sub_items_board` still carries no `subtasks` column at API
+`2026-01`); cross-board `item move` value-overrides (Monday's
+`ColumnMappingInput` still carries no value slot — slipped twice
+for the same reason); resumable cross-board cursor pagination
+(per-board cursor-lifetime under aggregation needs design work);
+files-shaped friendly column writes (`--set <file-col>=<path>` and
+`--set-raw <file-col>=<json>` — `monday item upload` from v0.4-M31
+is the verb-shaped alternative path agents should use today).
 
 See [`docs/cli-design.md`](./docs/cli-design.md) §13 for the
-full roadmap, [`docs/v0.3-plan.md`](./docs/v0.3-plan.md) for the
-v0.3 milestone history, and
-[`docs/v0.2-plan.md`](./docs/v0.2-plan.md) for the v0.2 milestone
-history.
+full roadmap, [`docs/v0.5-plan.md`](./docs/v0.5-plan.md) for the
+v0.5 milestone history, [`docs/v0.4-plan.md`](./docs/v0.4-plan.md)
+for v0.4, [`docs/v0.3-plan.md`](./docs/v0.3-plan.md) for v0.3, and
+[`docs/v0.2-plan.md`](./docs/v0.2-plan.md) for v0.2.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the per-release contract.
 
@@ -513,7 +683,9 @@ The full dev workflow + how to add a new command is in
 - **No `any`** (lint-enforced).
 - **Parse at every boundary** with zod.
 - **Mock at the network boundary, not internal modules.**
-- **Branch coverage 95%+ floor** (v0.3 ratcheted from 94% — see
+- **Branch coverage 95.45% floor** for branches; 95% floor for
+  statements / functions / lines (v0.3-M22 ratcheted branches
+  from 94% via an OAuth coverage-push session — see
   `vitest.config.ts`).
 - **Atomic commits, Conventional Commits.**
 

package/dist/api/assets.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Asset upload surface for the v0.4-M31 `monday item upload` +
+ * `monday update upload` verbs (`cli-design.md` §2.2 + §4.3 + §6.4
+ * + §13 v0.4 entry; `v0.4-plan.md` §3 M31).
+ *
+ * **Wire surface (empirical probe 2026-05-13, API `2026-01`).** Two
+ * Monday GraphQL multipart mutations land here:
+ *
+ *   - `Mutation.add_file_to_column(column_id: String!, file: File!,
+ *     item_id: ID!) → Asset` — attaches a file to a `file`-typed
+ *     column on a specific item. Note **`column_id` is `String!`
+ *     not `ID!`** (the SDK's column-id surface is consistently
+ *     `String!` because column IDs are user-defined-looking tokens
+ *     like `'files'` / `'attachments_3'` rather than numeric).
+ *   - `Mutation.add_file_to_update(file: File!, update_id: ID!) →
+ *     Asset` — attaches a file to an Update (comment) record. Item
+ *     ID is implicit (the update's parent item).
+ *
+ * Both mutations cross the wire via `multipart/form-data` per the
+ * standard GraphQL multipart-request specification (jaydenseric).
+ * The `File` scalar is Monday's own (NOT the spec-standard `Upload`);
+ * the multipart envelope is otherwise spec-compliant — `operations`
+ * + `map` JSON parts + the file part keyed by index `0`.
+ *
+ * **Asset object — 10 fields.** `id` (ID, non-null), `name` (String,
+ * non-null — the multipart `filename` parameter), `url` (String,
+ * non-null — direct download), `public_url` (String, non-null —
+ * sharable), `file_extension` (String, non-null), `file_size` (Int,
+ * non-null — bytes), `created_at` (Date, nullable), `uploaded_by`
+ * (User, non-null — the token's owner; projected to the slim
+ * `{id, name}` shape for envelope compactness), `original_geometry`
+ * (String, nullable — image dimensions like `'1920x1080'`),
+ * `url_thumbnail` (String, nullable — image thumbnails only).
+ *
+ * **R-NEW-41 3rd consumer fires here.** Asset upload is the third
+ * site (after M27 `Webhook.config` JSON/String asymmetry + M27
+ * `NotificationTargetType` collapse) where the wire-vs-CLI semantics
+ * carry a documented asymmetry. This module's transport choice
+ * (sibling multipart module, NOT extension of `transport.ts`) is
+ * itself the load-bearing asymmetry shape — the JSON envelope's
+ * `body: JSON.stringify(...)` invariant doesn't compose with
+ * multipart/form-data's `FormData`-driven boundary parameter, so
+ * the two transports live in sibling modules with parallel
+ * interfaces. See `docs/architecture.md` "Wire-vs-CLI semantics
+ * documentation conventions" for the canonical writeup.
+ *
+ * **No new ERROR_CODES (29 stays).** Asset-upload failures route
+ * through the existing codes:
+ *
+ *   - `usage_error` — file path doesn't exist / not readable
+ *     (`details.reason: 'file_not_readable'`); file is empty
+ *     (`details.reason: 'file_empty'`); upload exceeded Monday's
+ *     per-file size limit (Monday surfaces this server-side;
+ *     `details.reason: 'file_too_large'` rewrap).
+ *   - `unsupported_column_type` — `--column <col>` resolves to a
+ *     non-`file` column type. Hint points back at the §5.3 writer
+ *     surface (Monday writes files via `add_file_to_column` for
+ *     `file` columns only; other column types route via
+ *     `change_column_value`).
+ *   - `not_found` — item / update / column doesn't exist or isn't
+ *     visible to the token.
+ *   - `validation_failed` — Monday-side rejection of the upload
+ *     payload (malformed filename, server-side virus scan flag,
+ *     etc.).
+ *   - `forbidden` / `unauthorized` — token lacks asset-write scope.
+ *
+ * Monday's per-file size cap is plan-tier-dependent and NOT exposed
+ * via the schema (verified at M31 pre-flight probe — `Plan` +
+ * `Account` carry no file-quota fields). The CLI does NOT pre-check
+ * file size against a hardcoded ceiling; Monday's runtime rejection
+ * (typically `FILE_SIZE_LIMIT_EXCEEDED` or a generic 413) is rewrapped
+ * as `usage_error` with `details.reason: 'file_too_large'` +
+ * `details.file_size_bytes` (the local `fs.stat()` measurement
+ * captured at upload time — Monday's wire rejection may not surface
+ * a size field, but the CLI already has the local size from the
+ * read leg and threads it for a stable agent-keyed envelope).
+ *
+ * **Idempotency: NO.** Each successful upload mints a new Asset
+ * with a new ID — re-running `item upload` with the same args
+ * uploads the file a second time. Agents needing register-once
+ * semantics dedupe on the CLI side (e.g., read `Item.assets` first
+ * and skip the upload if a matching `Asset.name` exists).
+ *
+ * **Status: runtime body shipped at v0.4-M31 IMPL.** Both fetchers
+ * dispatch via `inputs.multipart.request(...)` wrapped in
+ * `withRetry(...)` per cli-design §2.5; the response-parse boundary
+ * uses `mapResponse` (mirroring `MondayClient.raw`'s discipline) +
+ * `assertResponseFieldPresent` for the schema-drift / null-payload
+ * distinction + `assetSchema.safeParse(...)` via `unwrapOrThrow`
+ * for the per-field shape. Server-side size-cap rewrap fires at
+ * the error-mapping layer below.
+ */
+import { z } from 'zod';
+import type { MondayClient } from './client.js';
+import type { MultipartTransport } from './multipart-transport.js';
+import type { Complexity } from '../utils/output/envelope.js';
+/**
+ * Slim projection of Monday's `User` for the `Asset.uploaded_by`
+ * slot. Monday's full User type is ~30 fields; the envelope echoes
+ * only `id` + `name` (matching the M19 `User`-projection cadence
+ * elsewhere in the CLI — `account_tags`, `board describe`'s
+ * subscribers, etc.). Future verbs that need wider User detail
+ * (`user get <uid>`) read against the full type.
+ */
+export declare const uploadedBySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>;
+export type UploadedBy = z.infer<typeof uploadedBySchema>;
+/**
+ * Asset read-projection shape — surfaces Monday's full 10-field
+ * `Asset` object (per `scripts/probe/m31-asset-upload.ts` 2026-05-13,
+ * API `2026-01`). The output envelope echoes this verbatim so an
+ * agent reading the upload result has every field a follow-up
+ * `Query.assets(ids:)` read would surface, plus the inputs the CLI
+ * sent (echoed by the caller, not this module).
+ *
+ * `original_geometry` + `url_thumbnail` are image-only; nullable
+ * for non-image uploads. `created_at` is nullable in Monday's
+ * schema even though every successful upload sets it (the
+ * nullability is preserved for fidelity against the introspected
+ * type).
+ */
+export declare const assetSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    url: z.ZodString;
+    public_url: z.ZodString;
+    file_extension: z.ZodString;
+    file_size: z.ZodNumber;
+    created_at: z.ZodNullable<z.ZodString>;
+    uploaded_by: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>;
+    original_geometry: z.ZodNullable<z.ZodString>;
+    url_thumbnail: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type Asset = z.infer<typeof assetSchema>;
+/**
+ * Output shape for `monday item upload <iid> --column <col> <file>`.
+ * Echoes the wire `Asset` record plus the agent-supplied inputs
+ * (`item_id`, `column_id`, `filename`, `file_size_bytes`) so one
+ * envelope read carries the full upload context.
+ *
+ * `file_size_bytes` is the CLI-measured size at upload time (from
+ * the local file's `fs.stat()`); `asset.file_size` is Monday's
+ * server-stored size (usually identical to `file_size_bytes` but
+ * preserved separately for asymmetric-storage-encoding fidelity).
+ *
+ * `asset` is the canonical wire record; future field additions
+ * land additively per the §6.1 envelope evolution rules.
+ */
+export declare const itemUploadOutputSchema: z.ZodObject<{
+    operation: z.ZodLiteral<"add_file_to_column">;
+    item_id: z.ZodString;
+    column_id: z.ZodString;
+    filename: z.ZodString;
+    file_size_bytes: z.ZodNumber;
+    asset: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        url: z.ZodString;
+        public_url: z.ZodString;
+        file_extension: z.ZodString;
+        file_size: z.ZodNumber;
+        created_at: z.ZodNullable<z.ZodString>;
+        uploaded_by: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>;
+        original_geometry: z.ZodNullable<z.ZodString>;
+        url_thumbnail: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ItemUploadOutput = z.infer<typeof itemUploadOutputSchema>;
+/**
+ * Output shape for `monday update upload <uid> <file>`. Same general
+ * shape as `itemUploadOutputSchema` but carries `update_id` instead
+ * of `item_id` + `column_id` (an Update record is the target;
+ * Monday's `Update.assets` collection grows by one on success).
+ */
+export declare const updateUploadOutputSchema: z.ZodObject<{
+    operation: z.ZodLiteral<"add_file_to_update">;
+    update_id: z.ZodString;
+    filename: z.ZodString;
+    file_size_bytes: z.ZodNumber;
+    asset: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        url: z.ZodString;
+        public_url: z.ZodString;
+        file_extension: z.ZodString;
+        file_size: z.ZodNumber;
+        created_at: z.ZodNullable<z.ZodString>;
+        uploaded_by: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>;
+        original_geometry: z.ZodNullable<z.ZodString>;
+        url_thumbnail: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type UpdateUploadOutput = z.infer<typeof updateUploadOutputSchema>;
+/**
+ * Mutation document for `add_file_to_column`. Operation name is
+ * pinned literally to `AddFileToColumn` and matches the wire
+ * `operationName` payload (R-NEW-37 W2 audit-point — caller-
+ * overridable operationName slots were closed at M27 IMPL round-1
+ * P2-1).
+ *
+ * `$file: File!` — Monday's own scalar (NOT the spec-standard
+ * `Upload!`); the multipart wire dispatcher (`assets.ts`'s caller
+ * via `MultipartTransport`) populates this slot via the spec-
+ * compliant `map` JSON pointing the file part at `variables.file`.
+ *
+ * Returns the full 10-field `Asset` selection so the output
+ * envelope captures Monday's complete view of the upload in one
+ * round-trip (no follow-up `Query.assets(ids:)` re-read needed).
+ */
+export declare const ADD_FILE_TO_COLUMN_MUTATION = "\n  mutation AddFileToColumn(\n    $itemId: ID!,\n    $columnId: String!,\n    $file: File!\n  ) {\n    add_file_to_column(\n      item_id: $itemId,\n      column_id: $columnId,\n      file: $file\n    ) {\n      id\n      name\n      url\n      public_url\n      file_extension\n      file_size\n      created_at\n      uploaded_by { id name }\n      original_geometry\n      url_thumbnail\n    }\n  }\n";
+/**
+ * Mutation document for `add_file_to_update`. Operation name pinned
+ * to `AddFileToUpdate` (R-NEW-37 W2). No `column_id` — Updates
+ * carry attachments directly via `Update.assets`.
+ */
+export declare const ADD_FILE_TO_UPDATE_MUTATION = "\n  mutation AddFileToUpdate(\n    $updateId: ID!,\n    $file: File!\n  ) {\n    add_file_to_update(\n      update_id: $updateId,\n      file: $file\n    ) {\n      id\n      name\n      url\n      public_url\n      file_extension\n      file_size\n      created_at\n      uploaded_by { id name }\n      original_geometry\n      url_thumbnail\n    }\n  }\n";
+export interface AddFileToColumnInputs {
+    readonly client: MondayClient;
+    readonly multipart: MultipartTransport;
+    readonly itemId: string;
+    readonly columnId: string;
+    readonly file: Blob;
+    readonly filename: string;
+    /**
+     * **Required** AbortSignal threaded into the multipart wire
+     * dispatch via `MultipartTransportRequest.signal` at IMPL.
+     * Callers MUST pass the runner's combined signal (`ctx.signal`)
+     * explicitly — `MondayClient.signal` is private + multipart
+     * dispatch bypasses `MondayClient.raw`, so no implicit fallback
+     * exists. Abort propagation follows the standard
+     * `--timeout` / SIGINT plumbing (`src/api/transport.ts`'s
+     * `combineSignals` mirrors the multipart-transport's own
+     * combined-signal logic at IMPL).
+     *
+     * **Retry semantics pinned (cli-design §2.5).** Asset upload
+     * honors the global `--retry <n>` contract: the IMPL session
+     * wraps `multipart.request(...)` in `withRetry(...)` using the
+     * `retries` value threaded from `client.config`'s retry slot.
+     * Re-readability is safe — Web `Blob.stream()` returns a fresh
+     * `ReadableStream` per call, so multipart payload assembly can
+     * re-execute on each retry attempt without buffering.
+     * Retryable conditions match the JSON transport's set
+     * (`rate_limited` / `complexity_exceeded` /
+     * `concurrency_exceeded` / `ip_rate_limited` /
+     * `resource_locked` / `network_error`); non-retryable
+     * conditions (`forbidden`, `not_found`, `validation_failed`,
+     * `usage_error` with `file_too_large`) surface immediately.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Maximum retry count for transient failures (default
+     * `--retry 3`, range `[0, ...]`). Threaded through to
+     * `withRetry(...)` at IMPL — same retry layer the JSON
+     * transport uses (cli-design §2.5).
+     */
+    readonly retries: number;
+}
+export interface AddFileToColumnResult {
+    readonly asset: Asset;
+    readonly source: 'live';
+    readonly cacheAgeSeconds: null;
+    readonly complexity: Complexity | null;
+}
+export interface AddFileToUpdateInputs {
+    readonly client: MondayClient;
+    readonly multipart: MultipartTransport;
+    readonly updateId: string;
+    readonly file: Blob;
+    readonly filename: string;
+    /**
+     * **Required** — same semantics as
+     * {@link AddFileToColumnInputs.signal}. Callers MUST pass
+     * `ctx.signal` explicitly (no implicit fallback from
+     * `client`).
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Same semantics as {@link AddFileToColumnInputs.retries} —
+     * threaded into `withRetry(...)` around the multipart
+     * dispatch at IMPL.
+     */
+    readonly retries: number;
+}
+export interface AddFileToUpdateResult {
+    readonly asset: Asset;
+    readonly source: 'live';
+    readonly cacheAgeSeconds: null;
+    readonly complexity: Complexity | null;
+}
+/**
+ * Fires Monday's `add_file_to_column` mutation via the multipart
+ * transport (operationName `AddFileToColumn`, pinned literally per
+ * R-NEW-37 W2 — NOT caller-overridable). Builds the operations
+ * payload with the `file: null` placeholder per the GraphQL
+ * multipart-request spec, dispatches through `inputs.multipart` +
+ * `withRetry(...)`, parses the response — null `add_file_to_column`
+ * → `not_found` with `details.{item_id, column_id}`; non-Asset
+ * shape → `internal_error` via `assetSchema.safeParse + unwrapOr
+ * Throw`. Server-side size rejections rewrap as `usage_error` with
+ * `details.reason: 'file_too_large'` + `details.file_size_bytes`
+ * from the caller-supplied local `fs.stat()` measurement (D3).
+ *
+ * Not idempotent — re-running mints a new `Asset` ID.
+ */
+export declare const addFileToColumn: (inputs: AddFileToColumnInputs) => Promise<AddFileToColumnResult>;
+/**
+ * Fires Monday's `add_file_to_update` mutation via the multipart
+ * transport (operationName `AddFileToUpdate`, pinned literally per
+ * R-NEW-37 W2). Mirrors {@link addFileToColumn}'s shape minus the
+ * `column_id` slot — Updates carry attachments via `Update.assets`
+ * directly. Same response-parse boundary, same `file_too_large`
+ * rewrap, same idempotency caveat (re-running mints a new Asset).
+ */
+export declare const addFileToUpdate: (inputs: AddFileToUpdateInputs) => Promise<AddFileToUpdateResult>;
+//# sourceMappingURL=assets.d.ts.map

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

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