monday-cli 0.2.0 → 0.3.0

package/dist/api/notifications.js

@@ -0,0 +1,215 @@
+/**
+ * Notification send surface for the v0.3-M27 `monday notification
+ * send` verb (`cli-design.md` §2.7 + §4.3 + §13 v0.3 entry;
+ * `v0.3-plan.md` §3 M27).
+ *
+ * **Wire surface (empirical probe 2026-05-12, API `2026-01`).** One
+ * Monday GraphQL operation lands here:
+ *
+ *   - `Mutation.create_notification(user_id: ID!, target_id: ID!,
+ *     target_type: NotificationTargetType!, text: String!)` — returns
+ *     the created `Notification { id, text }`.
+ *
+ * **`NotificationTargetType` is a 2-value wire enum: `Post` / `Project`.**
+ * Monday's `Post` value targets an Update (sending a notification
+ * about a specific post); `Project` targets an Item OR a Board (the
+ * wire enum doesn't distinguish). The CLI surface keeps the
+ * documented `--target-type item|board` argv vocabulary from
+ * cli-design §4.3 — both CLI values map to wire `Project`. The CLI
+ * preserves the item-vs-board distinction at the parse boundary
+ * for argv-validation discipline and to echo the agent-supplied
+ * kind in the output envelope; the CLI does NOT pre-verify that
+ * the supplied `--target <id>` actually names the declared kind,
+ * and Monday cannot either (the wire enum collapses both kinds to
+ * `Project`). Invisible / non-existent targets surface `not_found`
+ * at mutation time, but a passing `--target-type item` with a
+ * board-shaped ID succeeds and echoes the CLI-declared kind even
+ * though the record is a board. Monday's `Post` variant is
+ * unreachable at v0.3 — a v0.3.x / v0.4 contract-extension may add
+ * `--target-type update` once a clean argv-discriminator design is
+ * pinned (cli-design §13 v0.3 entry M27 sub-block carries the
+ * deferred note).
+ *
+ * **`Notification` read shape is minimal (2 fields).** `id` (ID,
+ * non-null), `text` (String, nullable). The CLI echoes the input
+ * fields (`user_id`, `target_id`, `target_type`) alongside the
+ * Monday-side fields so an agent verifies what was sent from a
+ * single envelope read.
+ *
+ * **No new ERROR_CODES (29 stays).** Notification send failures
+ * route through the existing codes: `not_found` (target user /
+ * `Project` invisible to the token or non-existent — Monday's
+ * visibility check; CLI-declared kind vs underlying record is NOT
+ * verified), `usage_error` (text empty / malformed argv — invalid
+ * `--target-type` enum value or non-numeric `--target` ID),
+ * `unauthorized` (token lacks notification scope), `forbidden`
+ * (account permissions), `validation_failed` (Monday-side rejection).
+ *
+ * **Notification send is single-recipient at v0.3** per cli-design
+ * §4.3 — the `--user <uid>` flag accepts one ID. Multi-recipient
+ * fan-out is a v0.3.x / v0.4 contract-extension (agents needing
+ * fan-out call `notification send` N times).
+ *
+ * **Notification send is not idempotent.** Re-running the verb
+ * produces a fresh notification with a new `id` (Monday treats
+ * each `create_notification` call as a discrete send). Agents
+ * needing send-once-semantics dedup on the CLI side; the verb
+ * does not enforce idempotency.
+ *
+ * **Runtime body (M27 IMPL).** Single `client.raw` round-trip
+ * against `mutation CreateNotification` with `operationName:
+ * 'CreateNotification'` (R-NEW-37 W2 audit-point). The CLI's
+ * 2-value `--target-type` enum collapses to wire `Project` at the
+ * runtime boundary; the CLI-side echo (`user_id` / `target_id` /
+ * `target_type`) is composed at the parse boundary so the envelope
+ * carries both the Monday-minted `id` + the agent-supplied inputs.
+ */
+import { z } from 'zod';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+import { assertResponseFieldPresent } from './response-root.js';
+import { ApiError } from '../utils/errors.js';
+/**
+ * CLI-side `target_type` vocabulary for `monday notification send
+ * --target-type <type>`. Both values map to Monday's wire
+ * `NotificationTargetType.Project` (which represents both items and
+ * boards) — the CLI keeps the item-vs-board distinction for argv
+ * validation discipline AND to echo the agent-supplied kind in the
+ * output envelope. The pairing of `--target-type` with `--target
+ * <id>` is **trusted, not verified**: the CLI validates the enum +
+ * numeric ID shape; Monday validates that the target is a visible
+ * `Project` (surfacing invisible / non-existent targets as
+ * `not_found`); but neither side verifies that the CLI-declared
+ * kind matches what the ID actually names — the wire enum
+ * collapses both kinds to `Project`. A CLI-side pre-read is
+ * deferred (v0.3.x / v0.4 contract-extension if agents need
+ * strict-kind enforcement).
+ *
+ * Monday's wire enum has only two values (`Post` / `Project`); the
+ * `Post` value targets Updates and is intentionally not surfaced
+ * at v0.3 per cli-design §4.3. A v0.3.x / v0.4 contract-extension
+ * may add a CLI third target-type `update` that dispatches to wire
+ * `Post`.
+ */
+export const NOTIFICATION_TARGET_TYPES = ['item', 'board'];
+export const notificationTargetTypeSchema = z.enum(NOTIFICATION_TARGET_TYPES);
+/**
+ * Output shape for `monday notification send --user <uid> --target
+ * <iid|bid> --target-type item|board --text <t>`. Carries both the
+ * Monday-side fields (`id` of the minted notification, server-echo
+ * `text`) and the CLI-side inputs (`user_id`, `target_id`,
+ * `target_type`) so an agent verifies what was sent from a single
+ * envelope read.
+ *
+ * `text` is nullable on the wire (Monday's `Notification.text` is
+ * `String` not `String!`); we preserve nullability for fidelity even
+ * though `create_notification`'s input `text` is non-null. In
+ * practice it round-trips the input value.
+ */
+export const notificationSendOutputSchema = z
+    .object({
+    id: z.string().min(1),
+    text: z.string().nullable(),
+    user_id: z.string().min(1),
+    target_id: z.string().min(1),
+    target_type: notificationTargetTypeSchema,
+})
+    .strict();
+const CREATE_NOTIFICATION_MUTATION = `
+  mutation CreateNotification(
+    $userId: ID!,
+    $targetId: ID!,
+    $targetType: NotificationTargetType!,
+    $text: String!
+  ) {
+    create_notification(
+      user_id: $userId,
+      target_id: $targetId,
+      target_type: $targetType,
+      text: $text
+    ) {
+      id
+      text
+    }
+  }
+`;
+const wireNotificationSchema = z
+    .object({
+    id: z.string().min(1),
+    text: z.string().nullable(),
+})
+    .strict();
+/**
+ * Fires Monday's `create_notification` mutation. Both CLI
+ * `--target-type` values (`item`/`board`) map to the wire enum
+ * `NotificationTargetType.Project` — Monday's wire surface doesn't
+ * distinguish items from boards at the enum level. Monday
+ * validates that `target_id` is a visible `Project` (invisible /
+ * non-existent targets surface `not_found`) but does NOT verify
+ * that the kind matches the CLI-declared `target_type`; the
+ * pairing is trusted and echoed but not enforced.
+ *
+ * The wire payload returns only `{id, text}`; the CLI-side echo
+ * (`user_id` / `target_id` / `target_type`) is composed at the
+ * caller's parse boundary so the resulting envelope carries both the
+ * Monday-minted `id` and the agent-supplied inputs in one read.
+ *
+ * `operationName: 'CreateNotification'` stays in sync with the named
+ * operation in {@link CREATE_NOTIFICATION_MUTATION} (R-NEW-37 W2
+ * audit-point). Not idempotent — re-running mints a fresh
+ * notification with a new ID.
+ */
+export const sendNotification = async (inputs) => {
+    // CLI's 2-value enum collapses to wire `Project` (Monday's wire
+    // surface has no item-vs-board distinction). The `Post` wire value
+    // is unreachable at v0.3 per cli-design §4.3.
+    const wireTargetType = 'Project';
+    const response = await inputs.client.raw(CREATE_NOTIFICATION_MUTATION, {
+        userId: inputs.userId,
+        targetId: inputs.targetId,
+        targetType: wireTargetType,
+        text: inputs.text,
+    }, { operationName: 'CreateNotification' });
+    assertResponseFieldPresent({
+        data: response.data,
+        key: 'create_notification',
+        operationLabel: 'CreateNotification',
+        details: {
+            user_id: inputs.userId,
+            target_id: inputs.targetId,
+            target_type: inputs.targetType,
+        },
+        nullHandling: 'caller_handles',
+    });
+    const raw = response.data.create_notification;
+    if (raw === null || raw === undefined) {
+        throw new ApiError('not_found', `Monday returned no notification payload from create_notification for user ${inputs.userId} on target ${inputs.targetId}`, {
+            details: {
+                user_id: inputs.userId,
+                target_id: inputs.targetId,
+                target_type: inputs.targetType,
+            },
+        });
+    }
+    const wire = unwrapOrThrow(wireNotificationSchema.safeParse(raw), {
+        context: 'Monday `create_notification` response',
+        details: {
+            user_id: inputs.userId,
+            target_id: inputs.targetId,
+            target_type: inputs.targetType,
+        },
+        hint: 'Monday may have amended the `Notification` selection — re-probe and amend `src/api/notifications.ts` if so',
+    });
+    return {
+        notification: {
+            id: wire.id,
+            text: wire.text,
+            user_id: inputs.userId,
+            target_id: inputs.targetId,
+            target_type: inputs.targetType,
+        },
+        source: 'live',
+        cacheAgeSeconds: null,
+        complexity: response.complexity,
+    };
+};
+//# sourceMappingURL=notifications.js.map

package/dist/api/notifications.js.map

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

package/dist/api/oauth-test-helper.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `__test_oauth_helper` test seam per cli-design §7.3.4.
+ *
+ * Substitutes for {@link bindOAuthListener} when the env var
+ * `__test_oauth_helper` is set; production code paths never see this
+ * helper. The substitution lives in `src/commands/auth/login.ts` —
+ * this module exposes the construction primitive.
+ *
+ * **Fixture file shape** (read from the path the env var holds):
+ *
+ * ```json
+ * {
+ *   "code": "fixture-code",
+ *   "force_csrf_mismatch": true,
+ *   "force_user_denied": true,
+ *   "force_authorization_failed": {
+ *     "error": "invalid_scope",
+ *     "error_description": "requested scope `boards:write` not granted"
+ *   },
+ *   "force_listener_timeout": true
+ * }
+ * ```
+ *
+ * All four `force_*` flags are mutually exclusive; the first
+ * non-undefined slot wins. The fixture **does not** carry `state` —
+ * it's randomly generated per invocation; the helper synthesises the
+ * redirect with the CLI's own generated `state` echoed back so CSRF
+ * verification passes by default.
+ *
+ * The fixture's PATH (the env var's value) is never echoed to the
+ * output envelope, never logged at any verbosity level, and is
+ * scrubbed from `--debug` output the same way `MONDAY_API_TOKEN` is.
+ */
+import { z } from 'zod';
+import type { OAuthListenerHandle } from './oauth.js';
+/** Env var name the test seam checks. The leading double-underscore
+ * discourages production use; tests set it explicitly. */
+export declare const TEST_OAUTH_HELPER_ENV_VAR = "__test_oauth_helper";
+declare const fixtureSchema: z.ZodObject<{
+    code: z.ZodString;
+    force_csrf_mismatch: z.ZodOptional<z.ZodLiteral<true>>;
+    force_user_denied: z.ZodOptional<z.ZodLiteral<true>>;
+    force_authorization_failed: z.ZodOptional<z.ZodObject<{
+        error: z.ZodString;
+        error_description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    force_listener_timeout: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type TestOAuthFixture = z.infer<typeof fixtureSchema>;
+/**
+ * Reads the test-helper fixture file and parses it. Surfaces
+ * `config_error` for any failure (file missing, malformed JSON,
+ * schema mismatch); a misconfigured test seam should fail loud,
+ * not silently fall back to the real listener.
+ */
+export declare const readTestOAuthFixture: (fixturePath: string) => Promise<TestOAuthFixture>;
+/**
+ * Builds a synthetic {@link OAuthListenerHandle} from the fixture +
+ * the CLI's generated `state`. No real socket bind; `awaitRedirect`
+ * resolves (or rejects) based on the fixture's `force_*` flags.
+ */
+export declare const buildTestOAuthListener: (fixture: TestOAuthFixture, generatedState: string) => OAuthListenerHandle;
+export {};
+//# sourceMappingURL=oauth-test-helper.d.ts.map

package/dist/api/oauth-test-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-test-helper.d.ts","sourceRoot":"","sources":["../../src/api/oauth-test-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,YAAY,CAAC;AAEvE;0DAC0D;AAC1D,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,QAAA,MAAM,aAAa;;;;;;;;;kBAcR,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,aAAa,MAAM,KAClB,OAAO,CAAC,gBAAgB,CA6C1B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,gBAAgB,EACzB,gBAAgB,MAAM,KACrB,mBA8FF,CAAC"}

package/dist/api/oauth-test-helper.js

@@ -0,0 +1,179 @@
+/**
+ * `__test_oauth_helper` test seam per cli-design §7.3.4.
+ *
+ * Substitutes for {@link bindOAuthListener} when the env var
+ * `__test_oauth_helper` is set; production code paths never see this
+ * helper. The substitution lives in `src/commands/auth/login.ts` —
+ * this module exposes the construction primitive.
+ *
+ * **Fixture file shape** (read from the path the env var holds):
+ *
+ * ```json
+ * {
+ *   "code": "fixture-code",
+ *   "force_csrf_mismatch": true,
+ *   "force_user_denied": true,
+ *   "force_authorization_failed": {
+ *     "error": "invalid_scope",
+ *     "error_description": "requested scope `boards:write` not granted"
+ *   },
+ *   "force_listener_timeout": true
+ * }
+ * ```
+ *
+ * All four `force_*` flags are mutually exclusive; the first
+ * non-undefined slot wins. The fixture **does not** carry `state` —
+ * it's randomly generated per invocation; the helper synthesises the
+ * redirect with the CLI's own generated `state` echoed back so CSRF
+ * verification passes by default.
+ *
+ * The fixture's PATH (the env var's value) is never echoed to the
+ * output envelope, never logged at any verbosity level, and is
+ * scrubbed from `--debug` output the same way `MONDAY_API_TOKEN` is.
+ */
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { ApiError, ConfigError, asError } from '../utils/errors.js';
+/** Env var name the test seam checks. The leading double-underscore
+ * discourages production use; tests set it explicitly. */
+export const TEST_OAUTH_HELPER_ENV_VAR = '__test_oauth_helper';
+const fixtureSchema = z
+    .object({
+    code: z.string().min(1),
+    force_csrf_mismatch: z.literal(true).optional(),
+    force_user_denied: z.literal(true).optional(),
+    force_authorization_failed: z
+        .object({
+        error: z.string().min(1),
+        error_description: z.string().optional(),
+    })
+        .strict()
+        .optional(),
+    force_listener_timeout: z.literal(true).optional(),
+})
+    .strict();
+/**
+ * Reads the test-helper fixture file and parses it. Surfaces
+ * `config_error` for any failure (file missing, malformed JSON,
+ * schema mismatch); a misconfigured test seam should fail loud,
+ * not silently fall back to the real listener.
+ */
+export const readTestOAuthFixture = async (fixturePath) => {
+    let raw;
+    try {
+        raw = await readFile(fixturePath, 'utf8');
+    }
+    catch (err) {
+        throw new ConfigError(`cannot read __test_oauth_helper fixture at ${fixturePath}`, {
+            cause: asError(err),
+            details: {
+                path: fixturePath,
+                hint: 'set __test_oauth_helper to the path of a valid fixture file or unset the env var to use the real OAuth listener',
+            },
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ConfigError(`__test_oauth_helper fixture at ${fixturePath} is not valid JSON`, {
+            cause: asError(err),
+            details: { path: fixturePath },
+        });
+    }
+    const result = fixtureSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ConfigError(`__test_oauth_helper fixture at ${fixturePath} does not match the documented shape`, {
+            cause: result.error,
+            details: {
+                path: fixturePath,
+                issues: result.error.issues.map((i) => ({
+                    path: i.path.join('.'),
+                    message: i.message,
+                })),
+            },
+        });
+    }
+    return result.data;
+};
+/**
+ * Builds a synthetic {@link OAuthListenerHandle} from the fixture +
+ * the CLI's generated `state`. No real socket bind; `awaitRedirect`
+ * resolves (or rejects) based on the fixture's `force_*` flags.
+ */
+export const buildTestOAuthListener = (fixture, generatedState) => {
+    let resolved = false;
+    const handle = {
+        port: 0,
+        awaitRedirect: () => new Promise((resolve, reject) => {
+            if (resolved) {
+                // Idempotent — repeat awaits are a programmer error in
+                // production, but the test seam guards explicitly so a
+                // double-await fails loud rather than hanging forever.
+                reject(new ApiError('internal_error', '__test_oauth_helper.awaitRedirect called twice'));
+                return;
+            }
+            resolved = true;
+            if (fixture.force_listener_timeout === true) {
+                // Mirror the real listener's timeout payload exactly so the
+                // command-level error mapping treats both surfaces
+                // identically.
+                reject(new ApiError('oauth_failed', 'OAuth listener timed out before the redirect arrived (test fixture)', {
+                    details: {
+                        reason: 'timeout',
+                        hint: 're-run `monday auth login` and complete the consent flow within 5 minutes',
+                    },
+                    retryable: true,
+                }));
+                return;
+            }
+            if (fixture.force_csrf_mismatch === true) {
+                // Substitute a different state so the caller's verifyCsrf
+                // call fails. Length-equal so the timing-safe path runs
+                // (mirrors the production CSRF code path; not just a
+                // length-mismatch shortcut).
+                const sameLengthDifferentState = generatedState
+                    .split('')
+                    .reverse()
+                    .join('');
+                // Ensure it's actually different — if `generatedState` is
+                // a palindrome (vanishingly rare), flip the first byte.
+                const echoed = sameLengthDifferentState === generatedState
+                    ? `${String.fromCharCode((generatedState.charCodeAt(0) ^ 1) & 0x7f)}${generatedState.slice(1)}`
+                    : sameLengthDifferentState;
+                resolve({ kind: 'code', code: fixture.code, state: echoed });
+                return;
+            }
+            if (fixture.force_user_denied === true) {
+                resolve({
+                    kind: 'error',
+                    error: 'access_denied',
+                    errorDescription: undefined,
+                    state: generatedState,
+                });
+                return;
+            }
+            if (fixture.force_authorization_failed !== undefined) {
+                resolve({
+                    kind: 'error',
+                    error: fixture.force_authorization_failed.error,
+                    errorDescription: fixture.force_authorization_failed.error_description,
+                    state: generatedState,
+                });
+                return;
+            }
+            // Default: success path with the CLI's own state echoed back.
+            resolve({
+                kind: 'code',
+                code: fixture.code,
+                state: generatedState,
+            });
+        }),
+        close: () => {
+            // No-op — no socket to close.
+        },
+    };
+    return handle;
+};
+//# sourceMappingURL=oauth-test-helper.js.map

package/dist/api/oauth-test-helper.js.map

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

package/dist/api/oauth.d.ts

@@ -0,0 +1,198 @@
+/**
+ * OAuth flow primitives for the v0.3-M21 `monday auth login` /
+ * `monday auth logout` verbs (cli-design §7.3 / §7.4).
+ *
+ * **Empirical probe findings (2026-05-10, against `auth.monday.com`):**
+ *
+ *   - `/oauth2/authorize` accepts arbitrary query params and encodes
+ *     them all into a JWT-signed `oauth_payload_token`, then 302-
+ *     redirects to `https://auth.monday.com/login?oauth_payload_token=<jwt>`.
+ *     Extra params like `code_challenge` + `code_challenge_method=S256`
+ *     are silently round-tripped through the JWT but **not enforced**
+ *     at token-exchange time — Monday's `/oauth2/token` requires
+ *     `client_secret` regardless. Verbatim probe response when the
+ *     PKCE-shape exchange omits `client_secret`:
+ *     `{"error":"invalid_request","error_description":"Missing client_secret param"}`
+ *     (status 400). PKCE is therefore **not load-bearing for v0.3**;
+ *     the design ships without `code_challenge` / `code_verifier`.
+ *
+ *   - `/oauth2/token` rejection responses follow RFC 6749 standard
+ *     shape (status 400, `application/json; charset=utf-8`):
+ *     `{"error": "<code>", "error_description": "<text>"}`.
+ *
+ *   - Redirect URI matching is documented as exact (Monday Apps
+ *     OAuth docs); design ships fixed-port `127.0.0.1:9876`.
+ *
+ *   - Token response shape per Monday's docs:
+ *     `{access_token, token_type, scope}`. **No `expires_in`**;
+ *     Monday tokens "do not expire and are valid until the user
+ *     uninstalls your app".
+ *
+ * **OAuth client registration (M21 implementation Part 1).**
+ * `OAUTH_CLIENT_ID` + `OAUTH_CLIENT_SECRET` are pinned in source
+ * per the public-OAuth-client convention — the secret authenticates
+ * the *app* (monday-cli), not the user. The user's flow is
+ * protected by the per-attempt `state` CSRF token + the listener-
+ * bound `redirect_uri`. **Until an OAuth app is registered with
+ * Monday's developer portal, the constants below carry placeholder
+ * values; production users see `oauth_failed.reason:
+ * "code_exchange_failed"` until they're swapped pre-publish.**
+ */
+/** Monday Apps OAuth authorize endpoint. */
+export declare const OAUTH_AUTHORIZE_URL = "https://auth.monday.com/oauth2/authorize";
+/** Monday Apps OAuth token-exchange endpoint. */
+export declare const OAUTH_TOKEN_URL = "https://auth.monday.com/oauth2/token";
+/**
+ * Default port for the local-loopback OAuth callback listener. Pinned
+ * to `9876` to match cli-design §7.3.1 step 2; the OAuth app's
+ * redirect URI configuration pins this port.
+ */
+export declare const OAUTH_DEFAULT_PORT = 9876;
+/** Path the listener answers; the OAuth app's redirect URI pins this. */
+export declare const OAUTH_CALLBACK_PATH = "/callback";
+/** Default listener timeout: 5 minutes (cli-design §7.3.1 step 4). */
+export declare const OAUTH_DEFAULT_LISTENER_TIMEOUT_MS: number;
+/**
+ * **PLACEHOLDER — replace with the registered Monday OAuth app's
+ * client_id pre-publish.** Tests do not depend on the value
+ * (cassettes intercept `/oauth2/token`); production users hit
+ * `oauth_failed.reason: "code_exchange_failed"` until swapped.
+ *
+ * Register at https://developer.monday.com/apps with redirect URI
+ * exactly `http://127.0.0.1:9876/callback`.
+ */
+export declare const OAUTH_CLIENT_ID = "<UNREGISTERED_PENDING_OAUTH_APP>";
+/**
+ * **PLACEHOLDER — replace alongside {@link OAUTH_CLIENT_ID}.** Same
+ * pre-publish swap; see {@link OAUTH_CLIENT_ID} for context.
+ */
+export declare const OAUTH_CLIENT_SECRET = "<UNREGISTERED_PENDING_OAUTH_APP>";
+/**
+ * Sentinel value the placeholder constants ship as until a Monday
+ * OAuth app is registered (see {@link OAUTH_CLIENT_ID} docstring).
+ * Exposed as a deliberately-widened `string` so consumers can compare
+ * `OAUTH_CLIENT_ID === OAUTH_UNREGISTERED_PLACEHOLDER` without
+ * triggering `@typescript-eslint/no-unnecessary-condition` on
+ * literal-vs-literal equality. v0.3-plan §8 Decision 11 rejected the
+ * v0.3 OAuth swap; the placeholder + guard in
+ * `src/commands/auth/login.ts` together surface a clear `usage_error`
+ * pointing users at `MONDAY_API_TOKEN` until a future version
+ * revisits the OAuth path.
+ */
+export declare const OAUTH_UNREGISTERED_PLACEHOLDER: string;
+/**
+ * Documented Monday Apps OAuth scopes per Monday's published docs at
+ * the M21 pre-flight probe (2026-05-10). Each entry is exposed
+ * verbatim so the OAuth-app-registration step (M21 implementation
+ * Part 1) can request the subset the CLI actually needs without a
+ * second source-of-truth elsewhere.
+ */
+export declare const OAUTH_SCOPES: readonly ["account:read", "assets:read", "boards:read", "boards:write", "departments:read", "departments:write", "docs:read", "docs:write", "me:read", "notifications:write", "tags:read", "teams:read", "teams:write", "updates:read", "updates:write", "users:read", "users:write", "webhooks:read", "webhooks:write", "workspaces:read", "workspaces:write"];
+export type OAuthScope = (typeof OAUTH_SCOPES)[number];
+/**
+ * The default scope set requested by `monday auth login` — a working
+ * subset of {@link OAUTH_SCOPES}. Agents calling `monday auth login`
+ * without a `--scopes` flag (v0.4+) pick up these.
+ */
+export declare const OAUTH_DEFAULT_REQUESTED_SCOPES: readonly OAuthScope[];
+/**
+ * The redirect payload as parsed by the listener.
+ */
+export type RedirectPayload = {
+    readonly kind: 'code';
+    readonly code: string;
+    readonly state: string;
+} | {
+    readonly kind: 'error';
+    readonly error: string;
+    readonly errorDescription: string | undefined;
+    readonly state: string;
+};
+/**
+ * Inputs to {@link bindOAuthListener}. Both fields optional with
+ * pinned defaults.
+ */
+export interface BindOAuthListenerInputs {
+    readonly port?: number;
+    readonly timeoutMs?: number;
+}
+/**
+ * Handle returned from {@link bindOAuthListener}. Decoupled from
+ * `node:http`'s `Server` so tests can substitute a fixture handle
+ * without a real socket bind.
+ */
+export interface OAuthListenerHandle {
+    readonly port: number;
+    readonly awaitRedirect: () => Promise<RedirectPayload>;
+    readonly close: () => void;
+}
+/**
+ * Inputs to {@link exchangeCode}. Mirror Monday's documented
+ * `/oauth2/token` body shape verbatim. `clientSecret` is **required**
+ * per the empirical probe; PKCE-only is not supported.
+ */
+export interface ExchangeCodeInputs {
+    readonly code: string;
+    readonly redirectUri: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    /** Optional fetch-impl override for tests. */
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Raw `/oauth2/token` success-response body shape per Monday Apps
+ * OAuth docs.
+ */
+export interface RawTokenResponse {
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly scope: string;
+}
+/**
+ * Normalized success-response shape that {@link exchangeCode} returns.
+ */
+export interface TokenResponse {
+    readonly accessToken: string;
+    readonly tokenType: string;
+    readonly scope: string;
+}
+/**
+ * Generates a 32-byte cryptographically-random `state` token, encoded
+ * base64url. Pure helper — no I/O.
+ */
+export declare const generateOAuthState: () => string;
+/**
+ * Constant-time CSRF comparison. Returns `false` on length mismatch
+ * (without throwing — cli-design §7.3.1 step 5 routes that to
+ * `csrf_mismatch`, NOT `internal_error`). Returns `false` on the
+ * empty-string case.
+ */
+export declare const verifyCsrf: (received: string, expected: string) => boolean;
+/**
+ * Binds an HTTP listener on `127.0.0.1:<port>`, waits for a single
+ * redirect to `${OAUTH_CALLBACK_PATH}?code=…&state=…` (or
+ * `?error=…&state=…`), and returns a handle whose `awaitRedirect`
+ * resolves with the parsed payload.
+ *
+ * Failure surfaces:
+ *   - Bind error (port held by another process or peer
+ *     `monday auth login`) → reject with `oauth_failed.reason:
+ *     "port_in_use"`.
+ *   - 5-minute timer elapses with no redirect → reject with
+ *     `oauth_failed.reason: "timeout"` (retryable: true; mirrors
+ *     M2-era cache_error override-at-throw-site precedent).
+ */
+export declare const bindOAuthListener: (inputs?: BindOAuthListenerInputs) => Promise<OAuthListenerHandle>;
+/**
+ * Posts the authorization code to `OAUTH_TOKEN_URL` and returns the
+ * normalized {@link TokenResponse}.
+ *
+ * Failure surfaces:
+ *   - 4xx (RFC 6749 standard shape) → throws
+ *     `oauth_failed.reason: "code_exchange_failed"` carrying
+ *     `monday_code` + `monday_description`.
+ *   - 5xx / network error → throws `network_error`.
+ *   - Malformed success body → throws `internal_error`.
+ */
+export declare const exchangeCode: (inputs: ExchangeCodeInputs) => Promise<TokenResponse>;
+//# sourceMappingURL=oauth.d.ts.map