monday-cli 0.2.0 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@ AI coding agents need to operate on real tickets. Monday.com has a
 GraphQL API, but each agent learning that schema from scratch is
 wasteful — and the API is sharp-edged (40+ column types, idiosyncratic
 mutation shapes, complex pagination). `monday-cli` is the abstraction:
-**one stable contract** (universal envelope, 27 stable error codes,
+**one stable contract** (universal envelope, 29 stable error codes,
 JSON Schema introspection) that every agent can target.
 
 - **Agent-first ergonomics.** `--json` everywhere, stable
@@ -47,29 +47,76 @@ Requires **Node.js ≥ 22**.
 ```bash
 # 1. Set your Monday API token (admin or member; guests can't mint one).
 #    Get one at https://<your-org>.monday.com/admin/integrations/api
+#
+#    OAuth login (`monday auth login`) is registered but deferred in
+#    v0.4.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
+# 2. Smoke test — confirm the token works.
 monday account whoami --json
 
-# 3. List a board's items (replace 12345 with your board ID)
+# 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. 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
 
-# 4. 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
 
-# 5. 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` (the 27th stable error code).
+# 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. 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
 
-# 6. Move a ticket forward
+# 12. Move a ticket forward, then comment on it
 monday item set 67890 status=Done --json
-
-# 7. Comment on it
 monday update create 67890 --body "Shipped in PR #1234" --json
+
+# 13. 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
+
+# 14. Outbound writes (v0.3 — webhooks + notifications)
+monday webhook list 12345 --json
+monday notification send --user 7 --target 67890 \
+  --target-type item --text "PTAL" --json
 ```
 
 ## Usage
@@ -135,7 +182,7 @@ Every JSON response uses the same universal envelope:
   "meta": {
     "schema_version": "1",
     "api_version": "2026-01",
-    "cli_version": "0.2.0",
+    "cli_version": "0.4.0",
     "request_id": "0e6f1a7b-...",
     "source": "live",
     "cache_age_seconds": null,
@@ -186,10 +233,12 @@ If you're an AI coding agent driving this CLI:
    inside an agent harness. `--json` is an alias for
    `--output json` and forces JSON on every command. JSON is
    never truncated; tables are.
-2. **Branch on `error.code`, not `error.message`.** The 27 stable
+2. **Branch on `error.code`, not `error.message`.** The 29 stable
    codes (`not_found`, `confirmation_required`, `column_archived`,
    `unsupported_column_type`, `rate_limited`, `stale_cursor`,
-   `ambiguous_match`, …) are part of the contract. Messages are not.
+   `ambiguous_match`, `tag_not_found`, `oauth_failed`, …) are
+   part of the contract.
+   Messages are not.
 3. **Read `meta.source`** to know whether the data is
    `"live"` / `"cache"` / `"mixed"` / `"none"`. `"mixed"` means
    board metadata came from cache while the rest hit live —
@@ -233,19 +282,58 @@ See [`.env.example`](./.env.example) for all supported variables
 
 ## Scope
 
-**v0.2.0 (published) ships:** 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 incrementally across
-M8–M18; one breaking change vs v0.1 (see
+**v0.4.0 (current — `monday-cli@0.4.0` on npm):**
+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), and shell
+completion (`monday completion bash|zsh|fish`). **No breaking
+changes vs v0.3.0** — every v0.4 surface is additive. Built
+incrementally across M29–M33. See [CHANGELOG.md](./CHANGELOG.md)
+for the full per-milestone release notes.
+
+**OAuth deferral (unchanged from v0.3.0).** `monday auth login` is
+registered but the canonical Monday OAuth app is not registered in
+v0.4.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.4.x / v0.5 contingent on
+user demand.
+
+**v0.3.0 (the previous 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
+(`monday auth login/logout --profile <name>` + `~/.monday-cli/
+config.toml`), diagnostics (`monday status` + `monday usage`),
+cross-board `monday item search` + `monday board favorites`,
+per-item history (`monday item history <iid>`), partial-success
+bulk updates (`monday item update --where ... --continue-on-error`),
+outbound writes (`monday webhook list/create/delete` +
+`monday notification send`), and three new writable column types
+(`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.
+
+**v0.2.0 (the prior 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
+incrementally across M8–M18; one breaking change vs v0.1 (see
 [CHANGELOG.md](./CHANGELOG.md) for the full upgrade guide).
 
-**v0.1.0 (published) shipped:** read-only core (account, workspace,
+**v0.1.0 (git tag, foundation milestone — not published to npm
+under the `monday-cli` name):** read-only core (account, workspace,
 board, user, update, item) + safe mutations (`item set` /
 `item clear` / `item update` single + bulk, `update create`) +
 diagnostics (`board doctor`) + GraphQL escape hatch (`raw`) +
 filter DSL (`--where` + `--filter-json`) + cursor pagination with
-stale-cursor fail-fast + NDJSON streaming + local cache.
+stale-cursor fail-fast + NDJSON streaming + local cache. v0.1.0
+shipped to `main` as the foundation milestone but the npm publish
+slipped to v0.2.0; the v0.1 surface is fully present in the
+published v0.2.0 tarball.
 
 **What v0.2 added:**
 
@@ -308,7 +396,8 @@ stale-cursor fail-fast + NDJSON streaming + local cache.
 **Writer allowlist** (other types return `unsupported_column_type`
 with per-category guidance):
 `status`, `text`, `long_text`, `numbers`, `dropdown`, `date`,
-`people`, plus M8 firm row `link`, `email`, `phone`.
+`people`, plus M8 firm row `link`, `email`, `phone`, plus v0.3-M19
+row `tags`, `board_relation`, `dependency`.
 
 - **M13** ships the full update mutation surface — `monday update
   reply` / `edit` / `delete` / `like` / `unlike` / `pin` / `unpin`
@@ -365,14 +454,114 @@ with per-category guidance):
   audit, README quickstart with `item create` + `item upsert`
   examples, this CHANGELOG, and the version bump to `0.2.0`.
 
-**Deferred to v0.3+:** `tags` / `board_relation` / `dependency`
-friendly translators (slipped from v0.2 tentative at M18 close
-per cli-design §13 + §5.3; usable today via `--set-raw`),
-`monday dev` workflow shortcuts, multi-level subitem creation.
-**v0.4:** `monday item watch`, `--concurrency`, asset uploads.
+**What v0.3 added (M19–M28; full per-milestone narrative in
+[CHANGELOG.md](./CHANGELOG.md)):**
+
+- **M19** — `tags`, `board_relation`, `dependency` friendly
+  `--set` translators (closes the v0.2 tentative-row carryover);
+  `monday account tags` read verb closes the `tag_not_found.
+  details.hint` forward-reference.
+- **M20** — `monday item time-track start/stop <iid>` registered
+  for forward-compatibility (documentation-only; throw
+  `usage_error` today — empirical probe 2026-05-10 confirmed
+  Monday's API doesn't currently expose time-tracking writes).
+- **M21 + M28** — multi-profile auth via `~/.monday-cli/
+  config.toml` + `--profile <name>` global flag; per-profile
+  credentials cache at `~/.monday-cli/credentials` (mode 0600).
+  `monday auth login` is registered but the canonical OAuth app
+  is not registered in v0.3.0 — the verb surfaces `usage_error.
+  details.reason: oauth_unregistered` pointing at
+  `MONDAY_API_TOKEN`. Multi-profile config + per-profile token
+  caching work fully today.
+- **M22** — `monday status` (7-probe DNS/TCP/TLS/auth/cache/
+  redaction/env-var matrix per cli-design §11.5) + `monday usage`
+  (daily Monday API operation budget remaining from
+  `platform_api.daily_*`).
+- **M23** — Cross-board `monday item search` (omit `--board`;
+  scope via `--workspace` / `--favorites` / `--max-boards`) +
+  `monday board favorites` (the current user's starred boards).
+- **M24** — `monday item history <iid>` (two-source chronological
+  merge: `activity_logs` + `updates`; per-event typed projection
+  for `update_column_value`, synthesized `update_posted` /
+  `update_replied` from the updates source).
+- **M25** — `monday item update --where ... --continue-on-error`
+  attempts every matched item regardless of per-item failure;
+  emits a partial-success envelope with `data.summary.
+  failed_count` + per-item `data.results[]`. Orthogonal to
+  `--yes`.
+- **M26** — `monday dev` namespace (sprint / epic / release /
+  task workflow shortcuts on top of standard board CRUD). Three
+  setup verbs (`dev discover [--apply]` / `dev configure` /
+  `dev doctor`) + 10 workflow verbs. Per-profile board mapping
+  in `[profiles.<name>.dev]`.
+- **M27** — Outbound writes: `monday webhook list/create/delete`
+  (live-only; webhooks land on the user's own HTTPS endpoint —
+  the CLI never receives) + `monday notification send`
+  (single-recipient at v0.3).
+- **M28** — 0.3.0 release prep. Multi-level subitem creation
+  deferred out of v0.3 per Decision 11 (Monday's `sub_items_board`
+  carries no `subtasks` column at API `2026-01`).
+
+**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).
+
+**v0.5 (next):** `team` writers (deferred from v0.4-M34 at the
+post-v0.4-M33 candidate-selection session), Monday workdocs CRUD
+mutation surface (9 mutations deferred at v0.4-M32 D8 closure),
+multi-level subitems remain conditional on Monday's data model
+surfacing them, cross-board `item move` value-overrides (slipped
+from v0.4 at v0.4 release-prep — Monday's `ColumnMappingInput`
+carries no value slot), and resumable cross-board cursor pagination
+(slipped from v0.4 — per-board cursor-lifetime under aggregation
+needs design work).
+
 See [`docs/cli-design.md`](./docs/cli-design.md) §13 for the
-full roadmap and [`docs/v0.2-plan.md`](./docs/v0.2-plan.md) for
-the v0.2 milestone history.
+full roadmap, [`docs/v0.4-plan.md`](./docs/v0.4-plan.md) for the
+v0.4 milestone history, [`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.
 
@@ -380,8 +569,8 @@ See [CHANGELOG.md](./CHANGELOG.md) for the per-release contract.
 
 - **[`docs/cli-design.md`](./docs/cli-design.md)** — canonical CLI
   contract. **Start here** if you want to understand the full
-  surface, the JSON envelope, error codes, or the v0.1 vs v0.2
-  split.
+  surface, the JSON envelope, error codes, or the per-version
+  scope (§13).
 - [`docs/output-shapes.md`](./docs/output-shapes.md) — per-command
   output reference with concrete examples.
 - [`docs/examples.md`](./docs/examples.md) — worked agent sessions.
@@ -416,7 +605,10 @@ 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 94%+ floor.**
+- **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.**
 
 ## Contributing

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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"}