monday-cli 0.3.0 → 0.4.0

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;kBAKlB,CAAC;AAEZ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;kBAab,CAAC;AAEZ,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;kBASxB,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;kBAQ1B,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,yZAuBvC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,yWAqBvC,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC;AA4ID;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,qBAAqB,KAC5B,OAAO,CAAC,qBAAqB,CA6F/B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,qBAAqB,KAC5B,OAAO,CAAC,qBAAqB,CAsE/B,CAAC"}