doordash-cli 0.2.0

package/dist/lib.d.ts

@@ -0,0 +1,21 @@
+import { type AddToCartResult, type AuthBootstrapResult, type AuthResult, type CartResult, type ItemResult, type MenuResult, type OrderResult, type OrdersResult, type SearchResult, type SetAddressResult, type UpdateCartResult } from "./direct-api.js";
+export declare const SAFE_COMMANDS: readonly ["install-browser", "auth-check", "auth-bootstrap", "auth-clear", "set-address", "search", "menu", "item", "orders", "order", "add-to-cart", "update-cart", "cart"];
+export declare const BLOCKED_COMMANDS: readonly ["checkout", "place-order", "track-order", "payment", "pay", "tip", "submit-order"];
+export type SafeCommand = (typeof SAFE_COMMANDS)[number];
+export type CommandFlags = Record<string, string>;
+export type CommandResult = {
+    success: true;
+    message: string;
+    browser: "chromium";
+} | AuthResult | AuthBootstrapResult | {
+    success: true;
+    message: string;
+    cookiesPath: string;
+    storageStatePath: string;
+} | SetAddressResult | SearchResult | MenuResult | ItemResult | OrdersResult | OrderResult | AddToCartResult | UpdateCartResult | CartResult;
+export declare function isSafeCommand(value: string): value is SafeCommand;
+export declare function isBlockedCommand(value: string): value is (typeof BLOCKED_COMMANDS)[number];
+export declare function assertSafeCommand(value: string): asserts value is SafeCommand;
+export declare function assertAllowedFlags(command: SafeCommand, args: CommandFlags): void;
+export declare function runCommand(command: SafeCommand, args: CommandFlags): Promise<CommandResult>;
+export declare function shutdown(): Promise<void>;

package/dist/lib.js

@@ -0,0 +1,202 @@
+import { cleanup as browserCleanup } from "@striderlabs/mcp-doordash/dist/browser.js";
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { addToCartDirect, bootstrapAuthSession, checkAuthDirect, cleanupDirect, clearStoredSession, getCartDirect, getItemDirect, getMenuDirect, getOrderDirect, getOrdersDirect, parseOptionSelectionsJson, searchRestaurantsDirect, setAddressDirect, updateCartDirect, } from "./direct-api.js";
+const require = createRequire(import.meta.url);
+const PLAYWRIGHT_CLI_PATH = join(dirname(require.resolve("playwright/package.json")), "cli.js");
+export const SAFE_COMMANDS = [
+    "install-browser",
+    "auth-check",
+    "auth-bootstrap",
+    "auth-clear",
+    "set-address",
+    "search",
+    "menu",
+    "item",
+    "orders",
+    "order",
+    "add-to-cart",
+    "update-cart",
+    "cart",
+];
+export const BLOCKED_COMMANDS = [
+    "checkout",
+    "place-order",
+    "track-order",
+    "payment",
+    "pay",
+    "tip",
+    "submit-order",
+];
+const COMMAND_FLAGS = {
+    "install-browser": [],
+    "auth-check": [],
+    "auth-bootstrap": [],
+    "auth-clear": [],
+    "set-address": ["address"],
+    search: ["query", "cuisine"],
+    menu: ["restaurant-id"],
+    item: ["restaurant-id", "item-id"],
+    orders: ["limit", "active-only"],
+    order: ["order-id"],
+    "add-to-cart": ["restaurant-id", "item-id", "item-name", "quantity", "special-instructions", "options-json"],
+    "update-cart": ["cart-item-id", "quantity"],
+    cart: [],
+};
+export function isSafeCommand(value) {
+    return SAFE_COMMANDS.includes(value);
+}
+export function isBlockedCommand(value) {
+    return BLOCKED_COMMANDS.includes(value);
+}
+export function assertSafeCommand(value) {
+    if (isSafeCommand(value)) {
+        return;
+    }
+    if (isBlockedCommand(value)) {
+        const guidance = value === "track-order" ? " Use `orders` or `order --order-id ...` for read-only existing-order status instead." : "";
+        throw new Error(`Blocked command: ${value}. This CLI is read-only for browse, cart, and existing-order inspection only; checkout, order placement, and payment actions stay out of scope.${guidance}`);
+    }
+    throw new Error(`Unsupported command: ${value}. Allowed commands: ${SAFE_COMMANDS.join(", ")}`);
+}
+export function assertAllowedFlags(command, args) {
+    const allowedFlags = new Set(COMMAND_FLAGS[command]);
+    const unknownFlags = Object.keys(args).filter((key) => key !== "help" && !allowedFlags.has(key));
+    if (unknownFlags.length === 0) {
+        return;
+    }
+    const allowedText = COMMAND_FLAGS[command].length > 0 ? COMMAND_FLAGS[command].join(", ") : "(none)";
+    throw new Error(`Unsupported flag(s) for ${command}: ${unknownFlags.join(", ")}. Allowed flags: ${allowedText}`);
+}
+export async function runCommand(command, args) {
+    assertAllowedFlags(command, args);
+    switch (command) {
+        case "install-browser":
+            return installBrowser();
+        case "auth-check":
+            return checkAuthDirect();
+        case "auth-bootstrap":
+            return bootstrapAuthSession();
+        case "auth-clear":
+            return clearStoredSession();
+        case "set-address": {
+            const address = requiredArg(args, "address");
+            return setAddressDirect(address);
+        }
+        case "search": {
+            const query = requiredArg(args, "query");
+            const cuisine = optionalArg(args, "cuisine");
+            return searchRestaurantsDirect(query, cuisine);
+        }
+        case "menu": {
+            const restaurantId = requiredArg(args, "restaurant-id");
+            return getMenuDirect(restaurantId);
+        }
+        case "item": {
+            const restaurantId = requiredArg(args, "restaurant-id");
+            const itemId = requiredArg(args, "item-id");
+            return getItemDirect(restaurantId, itemId);
+        }
+        case "orders": {
+            const limitRaw = optionalArg(args, "limit");
+            const limit = limitRaw === undefined ? undefined : Number.parseInt(limitRaw, 10);
+            if (limitRaw !== undefined && (!Number.isInteger(limit) || (limit ?? 0) < 1)) {
+                throw new Error(`Invalid --limit: ${limitRaw}`);
+            }
+            return getOrdersDirect({
+                limit,
+                activeOnly: parseBooleanFlag(optionalArg(args, "active-only"), "active-only") ?? false,
+            });
+        }
+        case "order": {
+            const orderId = requiredArg(args, "order-id");
+            return getOrderDirect(orderId);
+        }
+        case "add-to-cart": {
+            const restaurantId = requiredArg(args, "restaurant-id");
+            const itemId = optionalArg(args, "item-id");
+            const itemName = optionalArg(args, "item-name");
+            const quantityRaw = optionalArg(args, "quantity");
+            const specialInstructions = optionalArg(args, "special-instructions");
+            const optionsJson = optionalArg(args, "options-json");
+            const quantity = quantityRaw === undefined ? 1 : Number.parseInt(quantityRaw, 10);
+            if (!itemId && !itemName) {
+                throw new Error("Missing required flag --item-id or --item-name");
+            }
+            if (!Number.isInteger(quantity) || quantity < 1) {
+                throw new Error(`Invalid --quantity: ${quantityRaw}`);
+            }
+            return addToCartDirect({
+                restaurantId,
+                itemId,
+                itemName,
+                quantity,
+                specialInstructions,
+                optionSelections: optionsJson ? parseOptionSelectionsJson(optionsJson) : [],
+            });
+        }
+        case "update-cart": {
+            const cartItemId = requiredArg(args, "cart-item-id");
+            const quantityRaw = requiredArg(args, "quantity");
+            const quantity = Number.parseInt(quantityRaw, 10);
+            if (!Number.isInteger(quantity) || quantity < 0) {
+                throw new Error(`Invalid --quantity: ${quantityRaw}`);
+            }
+            return updateCartDirect({
+                cartItemId,
+                quantity,
+            });
+        }
+        case "cart":
+            return getCartDirect();
+    }
+}
+export async function shutdown() {
+    await cleanupDirect().catch(() => { });
+    await browserCleanup().catch(() => { });
+}
+async function installBrowser() {
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [PLAYWRIGHT_CLI_PATH, "install", "chromium"], {
+            stdio: "inherit",
+        });
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`Playwright browser install failed (code=${code ?? "null"}, signal=${signal ?? "none"})`));
+        });
+    });
+    return {
+        success: true,
+        browser: "chromium",
+        message: "Chromium is installed for doordash-cli.",
+    };
+}
+function requiredArg(args, key) {
+    const value = args[key];
+    if (!value) {
+        throw new Error(`Missing required flag --${key}`);
+    }
+    return value;
+}
+function optionalArg(args, key) {
+    const value = args[key];
+    return value && value.length > 0 ? value : undefined;
+}
+function parseBooleanFlag(value, key) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized)) {
+        return true;
+    }
+    if (["false", "0", "no", "off"].includes(normalized)) {
+        return false;
+    }
+    throw new Error(`Invalid --${key}: ${value}. Expected true or false.`);
+}

package/docs/examples.md

@@ -0,0 +1,158 @@
+# doordash-cli examples
+
+Use the preferred lowercase command name `dd-cli`. `doordash-cli` is an equivalent alias.
+
+If you are running from a local checkout without linking, prefix commands with:
+
+```bash
+npm run cli --
+```
+
+For installation and first-run setup, see [install.md](install.md).
+
+All commands print JSON.
+
+## Session setup
+
+Install the matching Chromium build once if you do not already have it:
+
+```bash
+dd-cli install-browser
+```
+
+Check whether you already have reusable session state:
+
+```bash
+dd-cli auth-check
+```
+
+If needed, launch Chromium for a one-time sign-in and save reusable state:
+
+```bash
+dd-cli auth-bootstrap
+```
+
+Reset saved session state when you want a clean start:
+
+```bash
+dd-cli auth-clear
+```
+
+## Search, menus, and items
+
+Set the active delivery address before discovery commands:
+
+```bash
+dd-cli set-address --address "350 5th Ave, New York, NY 10118"
+```
+
+Search by query, with or without a cuisine filter:
+
+```bash
+dd-cli search --query tacos
+dd-cli search --query tacos --cuisine mexican
+```
+
+Inspect a restaurant menu and a specific item:
+
+```bash
+dd-cli menu --restaurant-id 1721744
+dd-cli item --restaurant-id 1721744 --item-id 546936015
+```
+
+## Existing orders
+
+List recent existing orders:
+
+```bash
+dd-cli orders
+dd-cli orders --limit 5
+```
+
+Focus on still-active orders only:
+
+```bash
+dd-cli orders --active-only
+```
+
+Inspect one order in detail. `--order-id` accepts the CLI's returned internal ID, `orderUuid`, or `deliveryUuid`:
+
+```bash
+dd-cli order --order-id 3f4c6d0e-1234-5678-90ab-cdef12345678
+```
+
+## Cart basics
+
+Add by item ID:
+
+```bash
+dd-cli add-to-cart --restaurant-id 1721744 --item-id 876658890 --quantity 2
+```
+
+Add by visible item name:
+
+```bash
+dd-cli add-to-cart --restaurant-id 1721744 --item-name "Spicy Tuna Roll"
+```
+
+Add with special instructions:
+
+```bash
+dd-cli add-to-cart \
+  --restaurant-id 1721744 \
+  --item-name "Fries" \
+  --special-instructions "extra crispy"
+```
+
+Update quantity or remove an item:
+
+```bash
+dd-cli update-cart --cart-item-id 3b231d03-5a72-4636-8d12-c8769d706d45 --quantity 1
+dd-cli update-cart --cart-item-id 3b231d03-5a72-4636-8d12-c8769d706d45 --quantity 0
+```
+
+Inspect the active cart:
+
+```bash
+dd-cli cart
+```
+
+## Configurable items
+
+For items with required option groups, pass `--options-json` with explicit selections:
+
+```bash
+dd-cli add-to-cart \
+  --restaurant-id 1721744 \
+  --item-id 546936015 \
+  --options-json '[
+    {"groupId":"703393388","optionId":"4716032529"},
+    {"groupId":"703393389","optionId":"4716042466"}
+  ]'
+```
+
+Supported standalone recommended add-ons can include recursive `children` selections:
+
+```bash
+dd-cli add-to-cart \
+  --restaurant-id 1721744 \
+  --item-id 546936015 \
+  --options-json '[
+    {"groupId":"703393388","optionId":"4716032529"},
+    {"groupId":"703393389","optionId":"4716042466"},
+    {
+      "groupId":"recommended_option_546935995",
+      "optionId":"546936011",
+      "children":[
+        {"groupId":"780057412","optionId":"4702669757"}
+      ]
+    }
+  ]'
+```
+
+Guardrails:
+
+- unknown group IDs or option IDs are rejected
+- required min/max selection counts are enforced
+- duplicate nested selections are rejected
+- unsupported nested transport shapes fail closed

package/docs/install.md

@@ -0,0 +1,63 @@
+# Install and first run
+
+## Install from npm
+
+```bash
+npm install -g doordash-cli
+```
+
+That installs both lowercase command names: `doordash-cli` and `dd-cli`.
+
+Package page: <https://www.npmjs.com/package/doordash-cli>
+
+## Install from source instead
+
+If you want the latest unreleased work or a local checkout you can edit, install from a checkout:
+
+```bash
+git clone https://github.com/LatencyTDH/doordash-cli.git
+cd doordash-cli
+npm install
+npm link
+```
+
+After `npm link`, both `doordash-cli` and `dd-cli` resolve globally from your checkout.
+
+## Run from a checkout without linking
+
+```bash
+npm run cli -- --help
+```
+
+If you stay in checkout mode, replace `doordash-cli` with `npm run cli --` in the examples below.
+
+## Install the browser once
+
+If you plan to use `auth-bootstrap`, install the matching Playwright Chromium build:
+
+### Global or linked install
+
+```bash
+doordash-cli install-browser
+```
+
+### Checkout without linking
+
+```bash
+npm run install:browser
+```
+
+## First run
+
+```bash
+doordash-cli auth-bootstrap
+doordash-cli auth-check
+doordash-cli set-address --address "350 5th Ave, New York, NY 10118"
+doordash-cli search --query sushi
+```
+
+## Session reuse
+
+If you already have a compatible signed-in DoorDash browser session available, direct commands may reuse it instead of opening a fresh browser context.
+
+If not, run `doordash-cli auth-bootstrap` once to save reusable state for later commands.

package/man/dd-cli.1

@@ -0,0 +1,241 @@
+.TH DD-CLI 1 "2026-03-10" "doordash-cli 0.1.0" "User Commands"
+.SH NAME
+dd-cli, doordash-cli \- unofficial cart-safe DoorDash CLI for browsing, read-only order inspection, and cart management
+.SH SYNOPSIS
+.B dd-cli
+[\fICOMMAND\fR] [\fIOPTIONS\fR]
+.br
+.B doordash-cli
+[\fICOMMAND\fR] [\fIOPTIONS\fR]
+.SH DESCRIPTION
+.B dd-cli
+is a focused DoorDash command line interface for the parts of the workflow that
+fit well in a terminal: signing in, setting delivery context, searching stores,
+inspecting menus and items, inspecting existing orders, and managing the cart.
+.PP
+The command surface is intentionally small. The CLI does not expose checkout,
+order placement, payment actions, or order mutation/cancellation. Read-only
+existing-order inspection is allowed. If a payload cannot be validated safely
+from known DoorDash consumer-web request shapes, the tool fails closed instead
+of guessing.
+.PP
+If invoked with no command, or with
+.BR -h / --help ,
+it prints usage text and exits successfully.
+.PP
+The preferred command name is
+.BR dd-cli .
+.B doordash-cli
+is installed as a lowercase alias.
+.SH COMMANDS
+.TP
+.B install-browser
+Install the matching Playwright Chromium build used by this package.
+.TP
+.B auth-check
+Verify whether the saved session appears authenticated. This command can also
+import an already-signed-in compatible managed-browser DoorDash session when a
+usable CDP endpoint is available.
+.TP
+.B auth-bootstrap
+Launch Chromium for a one-time manual sign-in flow, then save reusable browser
+state for later direct API calls.
+.TP
+.B auth-clear
+Delete stored session material used by this CLI.
+.TP
+.BI "set-address --address " ADDRESS
+Resolve and persist the active delivery address. Saved addresses are reused when
+possible; new addresses are enrolled through DoorDash's consumer-web address
+APIs.
+.TP
+.BI "search --query " TEXT " [--cuisine " CUISINE "]"
+Search for restaurants matching a query, optionally narrowed by cuisine.
+.TP
+.BI "menu --restaurant-id " ID
+Fetch a restaurant menu.
+.TP
+.BI "item --restaurant-id " ID " --item-id " ITEM_ID
+Fetch detailed information for a single item.
+.TP
+.BI "orders [--limit " N "] [--active-only]"
+List existing orders with current status, totals, timestamps, and item
+summaries.
+.TP
+.BI "order --order-id " ID
+Inspect one existing order in more detail. The identifier may be the CLI's
+returned internal order ID,
+.BR orderUuid ,
+or
+.BR deliveryUuid .
+.TP
+.BI "add-to-cart --restaurant-id " ID " (--item-id " ITEM_ID " | --item-name " NAME ") [--quantity " N "] [--special-instructions " TEXT "] [--options-json " JSON "]"
+Add an item to the active cart. Configurable items require explicit option
+selections via
+.BR --options-json .
+.TP
+.BI "update-cart --cart-item-id " ID " --quantity " N
+Update a cart item's quantity. Use quantity
+.B 0
+to remove it.
+.TP
+.B cart
+Show the current cart.
+.SH OPTIONS
+.TP
+.BR -h , " --help"
+Show usage information.
+.TP
+.BR -v , " --version"
+Show the packaged CLI version.
+.TP
+.BI --address " ADDRESS"
+Freeform delivery address for
+.BR set-address .
+.TP
+.BI --query " TEXT"
+Restaurant search query.
+.TP
+.BI --cuisine " CUISINE"
+Optional cuisine filter for
+.BR search .
+.TP
+.BI --restaurant-id " ID"
+DoorDash restaurant identifier used by
+.BR menu ,
+.BR item ,
+and
+.BR add-to-cart .
+.TP
+.BI --item-id " ID"
+DoorDash item identifier.
+.TP
+.BI --item-name " NAME"
+Fallback item lookup by visible item name when an item ID is not convenient.
+.TP
+.BI --order-id " ID"
+Existing-order identifier accepted by
+.BR order .
+.TP
+.BI --limit " N"
+Maximum number of existing orders to return for
+.BR orders .
+.TP
+.B --active-only
+Filter
+.B orders
+output to active / still-tracking orders only.
+.TP
+.BI --quantity " N"
+Positive integer quantity for add/update operations.
+.TP
+.BI --cart-item-id " ID"
+DoorDash cart item identifier for
+.BR update-cart .
+.TP
+.BI --special-instructions " TEXT"
+Freeform item instructions for
+.BR add-to-cart .
+.TP
+.BI --options-json " JSON"
+Structured option selections for configurable items. Some supported standalone
+recommended add-ons can be represented with recursive
+.B children
+arrays.
+.SH EXAMPLES
+.PP
+Show help, version, and read the manual:
+.PP
+.EX
+dd-cli --help
+dd-cli --version
+man dd-cli
+.EE
+.PP
+Install the matching browser build once:
+.PP
+.EX
+dd-cli install-browser
+.EE
+.PP
+Bootstrap a reusable session:
+.PP
+.EX
+dd-cli auth-bootstrap
+.EE
+.PP
+Set an address and search for sushi:
+.PP
+.EX
+dd-cli set-address --address "350 5th Ave, New York, NY 10118"
+dd-cli search --query sushi
+.EE
+.PP
+Inspect existing orders:
+.PP
+.EX
+dd-cli orders
+dd-cli orders --active-only
+dd-cli order --order-id 3f4c6d0e-1234-5678-90ab-cdef12345678
+.EE
+.PP
+Add a configurable item to the cart:
+.PP
+.EX
+dd-cli add-to-cart \
+  --restaurant-id 1721744 \
+  --item-id 546936015 \
+  --options-json '[{"groupId":"703393388","optionId":"4716032529"},{"groupId":"703393389","optionId":"4716042466"}]'
+.EE
+.SH OUTPUT
+Commands print JSON on standard output so they can be piped into shell tools,
+parsers, or scripts.
+.SH SESSION STORAGE
+The CLI persists reusable session state under the user's configuration
+directory. The exact file layout is an implementation detail and may evolve over
+time, but the saved state is reused across runs unless cleared with
+.BR auth-clear .
+.SH ENVIRONMENT
+.TP
+.B DOORDASH_MANAGED_BROWSER_CDP_URL
+Preferred Chrome DevTools Protocol endpoint for importing an already-signed-in
+compatible managed-browser session.
+.PP
+The CLI may also honor additional compatible CDP endpoint environment variables
+for integration convenience.
+.SH EXIT STATUS
+.TP
+.B 0
+Success, including help and no-argument usage output.
+.TP
+.B 1
+Validation error, blocked command, unsupported flag, or runtime failure.
+.SH SAFETY
+The CLI is intentionally limited to browsing, read-only existing-order
+inspection, and cart management. Dangerous commands such as checkout,
+place-order, payment actions, and order mutation/cancellation are blocked
+immediately. The legacy
+.B track-order
+verb remains blocked; use
+.B orders
+or
+.B order
+instead.
+.SH MAN PAGE INSTALLATION
+For cloned or linked development checkouts, install the local manual pages with:
+.PP
+.EX
+npm run install:man
+.EE
+.PP
+This links
+.BR dd-cli (1)
+and
+.BR doordash-cli (1)
+into the user's local manpath, typically
+.I ~/.local/share/man/man1
+on Linux.
+.SH SEE ALSO
+.BR doordash-cli (1),
+.BR npm (1),
+.BR man (1)

package/man/doordash-cli.1

@@ -0,0 +1 @@
+.so man1/dd-cli.1