monday-cli 0.2.0

package/dist/api/emails.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure email-resolution helpers for the `email` column-value translator
+ * (`cli-design.md` §5.3 step 3 v0.2 expansion, `v0.2-plan.md` §3 M8).
+ *
+ * Surface:
+ *   - `parseEmailInput` — accepts the two pipe-form shapes cli-design
+ *     §5.3 enumerates: `<email>` (text defaults to the email) and
+ *     `<email>|<text>` (both segments trimmed; pipe-split max 1
+ *     split). Email validated via `z.string().email()`.
+ *
+ * **Note: `email` is the column type, distinct from `people`.**
+ * The `email` column is a free-form contact-info column on the item
+ * (e.g. "support contact"). The `people` column is the assignee
+ * column that takes Monday users by ID. They share zero wire shape.
+ *
+ * **Why a separate module.** Same template `links.ts` / `dates.ts`
+ * follow — column-values.ts owns translator dispatch; the per-type
+ * grammar machinery + zod boundary lives one module deeper. Splitting
+ * keeps each translator's tests + corner-case coverage isolated.
+ *
+ * **Pipe-form max 1 split.** Same rule as `links.ts` — `text` may
+ * contain literal `|` characters. cli-design doesn't pin this, but
+ * pinning here means agents who want a `|` in their visible label
+ * get it without reaching for `--set-raw`.
+ */
+/**
+ * Wire payload shape for an `email` column. Matches Monday's
+ * `change_column_value(value: JSON!)` JSON scalar:
+ *   `{email: <email>, text: <text>}`
+ *
+ * cli-design.md §5.3 step 3 v0.2 expansion line 812-814 pins the
+ * shape. `text` defaults to the email when the pipe form is absent —
+ * Monday's email-column UI shows the `text` segment as the visible
+ * label.
+ */
+export interface EmailPayload {
+    readonly email: string;
+    readonly text: string;
+}
+/**
+ * Parses an `email` column input per cli-design.md §5.3 step 3 v0.2
+ * expansion.
+ *
+ * Accepted inputs:
+ *   - **Single email** `alice@example.com` → `{email, text: <email>}`.
+ *     The email doubles as the visible text — Monday's email-column
+ *     UI shows `text` as the displayed label.
+ *   - **Pipe form** `alice@example.com|Alice` → `{email, text}`.
+ *     Both segments trimmed; pipe-split max 1.
+ *
+ * Throws `UsageError(usage_error)`:
+ *   - Email fails `z.string().email()` validation.
+ *   - Pipe form with empty trailer or empty leader.
+ *   - Empty input after trim.
+ *
+ * @param raw - The raw user-supplied value (post-`--set` parsing).
+ * @param columnId - Column ID for error messages.
+ */
+export declare const parseEmailInput: (raw: string, columnId: string) => EmailPayload;
+//# sourceMappingURL=emails.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emails.d.ts","sourceRoot":"","sources":["../../src/api/emails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,MAAM,EACX,UAAU,MAAM,KACf,YA8DF,CAAC"}

package/dist/api/emails.js

@@ -0,0 +1,113 @@
+/**
+ * Pure email-resolution helpers for the `email` column-value translator
+ * (`cli-design.md` §5.3 step 3 v0.2 expansion, `v0.2-plan.md` §3 M8).
+ *
+ * Surface:
+ *   - `parseEmailInput` — accepts the two pipe-form shapes cli-design
+ *     §5.3 enumerates: `<email>` (text defaults to the email) and
+ *     `<email>|<text>` (both segments trimmed; pipe-split max 1
+ *     split). Email validated via `z.string().email()`.
+ *
+ * **Note: `email` is the column type, distinct from `people`.**
+ * The `email` column is a free-form contact-info column on the item
+ * (e.g. "support contact"). The `people` column is the assignee
+ * column that takes Monday users by ID. They share zero wire shape.
+ *
+ * **Why a separate module.** Same template `links.ts` / `dates.ts`
+ * follow — column-values.ts owns translator dispatch; the per-type
+ * grammar machinery + zod boundary lives one module deeper. Splitting
+ * keeps each translator's tests + corner-case coverage isolated.
+ *
+ * **Pipe-form max 1 split.** Same rule as `links.ts` — `text` may
+ * contain literal `|` characters. cli-design doesn't pin this, but
+ * pinning here means agents who want a `|` in their visible label
+ * get it without reaching for `--set-raw`.
+ */
+import { z } from 'zod';
+import { UsageError } from '../utils/errors.js';
+const EMAIL_SCHEMA = z.email();
+/**
+ * Parses an `email` column input per cli-design.md §5.3 step 3 v0.2
+ * expansion.
+ *
+ * Accepted inputs:
+ *   - **Single email** `alice@example.com` → `{email, text: <email>}`.
+ *     The email doubles as the visible text — Monday's email-column
+ *     UI shows `text` as the displayed label.
+ *   - **Pipe form** `alice@example.com|Alice` → `{email, text}`.
+ *     Both segments trimmed; pipe-split max 1.
+ *
+ * Throws `UsageError(usage_error)`:
+ *   - Email fails `z.string().email()` validation.
+ *   - Pipe form with empty trailer or empty leader.
+ *   - Empty input after trim.
+ *
+ * @param raw - The raw user-supplied value (post-`--set` parsing).
+ * @param columnId - Column ID for error messages.
+ */
+export const parseEmailInput = (raw, columnId) => {
+    const trimmedRaw = raw.trim();
+    if (trimmedRaw.length === 0) {
+        throw emptyEmailInputError(columnId, raw);
+    }
+    const pipeIdx = trimmedRaw.indexOf('|');
+    let emailSegment;
+    let textSegment;
+    if (pipeIdx === -1) {
+        emailSegment = trimmedRaw;
+        textSegment = trimmedRaw;
+    }
+    else {
+        emailSegment = trimmedRaw.slice(0, pipeIdx).trim();
+        textSegment = trimmedRaw.slice(pipeIdx + 1).trim();
+        if (emailSegment.length === 0) {
+            throw emptyEmailInputError(columnId, raw);
+        }
+        if (textSegment.length === 0) {
+            throw new UsageError(`Email column "${columnId}" got pipe-form input with an empty ` +
+                `text segment ("${raw}"). The friendly translator requires ` +
+                `non-empty text after "|"; pass a single email (text defaults ` +
+                `to the email) or use --set-raw to write an email with empty text.`, {
+                details: {
+                    column_id: columnId,
+                    column_type: 'email',
+                    raw_input: raw,
+                    hint: `pass a single email (--set ${columnId}=alice@example.com) ` +
+                        `or pipe-form (--set ${columnId}='alice@example.com|Alice'). ` +
+                        `For empty text, use --set-raw ${columnId}=` +
+                        `'{"email":"alice@example.com","text":""}'.`,
+                },
+            });
+        }
+    }
+    const emailResult = EMAIL_SCHEMA.safeParse(emailSegment);
+    if (!emailResult.success) {
+        throw new UsageError(`Email column "${columnId}" got invalid email "${emailSegment}". ` +
+            `Monday's email column requires a well-formed email address ` +
+            `(e.g. alice@example.com).`, {
+            details: {
+                column_id: columnId,
+                column_type: 'email',
+                raw_input: raw,
+                email_segment: emailSegment,
+                hint: `pass an email address (--set ${columnId}=alice@example.com). ` +
+                    `The pipe form (--set ${columnId}='alice@example.com|Alice') ` +
+                    `sets a custom visible label.`,
+            },
+        });
+    }
+    return { email: emailResult.data, text: textSegment };
+};
+const emptyEmailInputError = (columnId, raw) => new UsageError(`Email column "${columnId}" needs an email address. Got "${raw}". ` +
+    `To clear an email column, use \`monday item clear <iid> ${columnId} ` +
+    `[--board <bid>]\` instead.`, {
+    details: {
+        column_id: columnId,
+        column_type: 'email',
+        raw_input: raw,
+        hint: `pass an email (--set ${columnId}=alice@example.com) or ` +
+            `pipe-form with a visible label (--set ${columnId}=` +
+            `'alice@example.com|Alice').`,
+    },
+});
+//# sourceMappingURL=emails.js.map

package/dist/api/emails.js.map

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

package/dist/api/errors.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Monday API → CLI error code mapper (`v0.1-plan.md` §3 M2,
+ * `cli-design.md` §2.5 / §6.5).
+ *
+ * The transport layer (`src/api/transport.ts`) already maps the
+ * lowest-level failures it sees: `fetch` exceptions → `network_error`,
+ * `AbortSignal.timeout` → `timeout`, malformed JSON →
+ * `network_error`. Everything else — HTTP status codes, GraphQL
+ * `errors[]` payloads, Monday's own application-level codes that
+ * arrive on `200 OK` — is interpreted *here* against the response
+ * body the transport hands back.
+ *
+ * Two consumers:
+ *
+ *  - `api/client.ts` calls `mapResponse(transportResponse)` on every
+ *    request. A non-error response returns `{ ok: true, data }`; an
+ *    error becomes `ApiError(<code>, ..., { httpStatus, mondayCode,
+ *    retryAfterSeconds, details })` for the retry layer to inspect.
+ *  - The retry layer (`api/retry.ts`) reads `error.retryable` and
+ *    `error.retryAfterSeconds` to decide.
+ *
+ * **No English-message keying.** Monday's error code dictionary is
+ * unstable across API versions; we extract the structured signals
+ * (`extensions.code`, `extensions.error_code`, HTTP status,
+ * `retry_in_seconds` / `Retry-After` headers) and ignore the prose.
+ */
+import { ApiError } from '../utils/errors.js';
+/**
+ * Subset of Monday's GraphQL error shape that we read. Everything
+ * past `extensions` is `unknown` because Monday adds fields
+ * version-by-version and we mustn't pretend to type them.
+ */
+export interface GraphQlError {
+    readonly message: string;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    readonly path?: readonly (string | number)[];
+}
+export interface GraphQlResponseBody {
+    readonly data?: unknown;
+    readonly errors?: readonly GraphQlError[];
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    readonly error_code?: string;
+    readonly error_message?: string;
+    readonly status_code?: number;
+}
+export interface MapInput {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: unknown;
+}
+export interface MapSuccess<T = unknown> {
+    readonly ok: true;
+    readonly data: T;
+    readonly extensions: Readonly<Record<string, unknown>> | undefined;
+}
+export interface MapFailure {
+    readonly ok: false;
+    readonly error: ApiError;
+}
+export type MapResult<T = unknown> = MapSuccess<T> | MapFailure;
+/**
+ * Maps a transport response to either a parsed `data` payload or an
+ * `ApiError`. The caller (`api/client.ts`) typically destructures:
+ *
+ *   const result = mapResponse<MyShape>(resp);
+ *   if (!result.ok) throw result.error;
+ *   return result.data;
+ *
+ * Throwing here would force every caller to have its own try/catch;
+ * returning a tagged result keeps the retry layer's loop linear.
+ */
+export declare const mapResponse: <T = unknown>(input: MapInput) => MapResult<T>;
+/**
+ * Re-maps an unknown error caught around a transport call to a typed
+ * `MondayCliError`. The transport already throws `ApiError` for
+ * network/timeout failures; anything else (a bug in the SDK, a
+ * malformed cassette, a future SDK retry layer leaking a custom
+ * error type) falls through to `internal_error` so the runner's
+ * envelope still carries something agents can act on.
+ */
+export declare const wrapTransportError: (err: unknown) => ApiError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,QAAQ,EAAuB,MAAM,oBAAoB,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CACpE;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;AA6ShE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,OAAO,EAAE,OAAO,QAAQ,KAAG,SAAS,CAAC,CAAC,CAgJrE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,QAOjD,CAAC"}