raindrop-cli 0.1.0

package/dist/utils/spinner.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Progress indicator utilities using ora spinner.
+ *
+ * Per clig.dev guidelines:
+ * - "Responsive is more important than fast - print something in <100ms"
+ * - "Show progress if something takes a long time"
+ * - "If your program displays no output for a while, it will look broken"
+ *
+ * Spinner behavior:
+ * - Only shows after 100ms delay (avoid flicker for fast operations)
+ * - Disabled when stderr is not a TTY (piped/redirected)
+ * - Disabled in verbose mode (verbose output serves same purpose)
+ * - Writes to stderr to keep stdout clean for pipeable data
+ */
+import { type Ora } from "ora";
+/**
+ * Options for the spinner.
+ */
+export interface SpinnerOptions {
+    /** Message to display while operation is in progress */
+    text: string;
+    /** Message to display on success (optional) */
+    successText?: string;
+    /** Message to display on failure (optional) */
+    failText?: string;
+}
+/**
+ * Check if spinner should be shown.
+ * Disabled when:
+ * - stderr is not a TTY (output is piped/redirected)
+ * - verbose mode is enabled (verbose output replaces spinner)
+ */
+export declare function shouldShowSpinner(): boolean;
+/**
+ * Execute an async operation with a spinner.
+ *
+ * The spinner only appears after 100ms delay to avoid flicker for fast operations.
+ * If the operation completes before 100ms, no spinner is shown.
+ *
+ * @param options - Spinner options (text, successText, failText)
+ * @param operation - Async operation to execute
+ * @returns The result of the operation
+ *
+ * @example
+ * const result = await withSpinner(
+ *   { text: "Fetching bookmarks...", successText: "Done!" },
+ *   () => client.getRaindrops(collectionId)
+ * );
+ */
+export declare function withSpinner<T>(options: SpinnerOptions | string, operation: () => Promise<T>): Promise<T>;
+/**
+ * Create a manual spinner for operations that need progress updates.
+ * Useful for batch operations where you want to update the message.
+ *
+ * Returns null if spinner shouldn't be shown (non-TTY, verbose mode).
+ *
+ * @param text - Initial spinner text
+ * @returns Ora spinner instance or null
+ *
+ * @example
+ * const spinner = createSpinner("Processing bookmarks...");
+ * for (let i = 0; i < items.length; i++) {
+ *   spinner?.text = `Processing ${i + 1}/${items.length}...`;
+ *   await processItem(items[i]);
+ * }
+ * spinner?.succeed("Processed all bookmarks");
+ */
+export declare function createSpinner(text: string): Ora | null;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/utils/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/utils/spinner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAY,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAOpC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAY3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,cAAc,GAAG,MAAM,EAChC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAuDZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAStD"}

package/dist/utils/stdin.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Utilities for reading input from stdin.
+ */
+/**
+ * Check if stdin has data available (is being piped to).
+ * Returns true if stdin is not a TTY (i.e., data is being piped).
+ */
+export declare function hasStdinData(): boolean;
+/**
+ * Read all data from stdin and return as a string.
+ * Returns empty string if stdin is a TTY (no piped data).
+ */
+export declare function readStdin(): Promise<string>;
+/**
+ * Parse IDs from a string input.
+ * Accepts IDs separated by newlines, commas, or whitespace.
+ * Returns an array of valid positive integers.
+ *
+ * @param input - Raw string input containing IDs
+ * @returns Array of parsed integer IDs
+ * @throws Error if any ID is invalid (not a positive integer)
+ */
+export declare function parseIds(input: string): number[];
+/**
+ * Read and parse IDs from stdin.
+ * Combines readStdin() and parseIds().
+ *
+ * @returns Array of parsed integer IDs, or empty array if no stdin data
+ */
+export declare function readIdsFromStdin(): Promise<number[]>;
+//# sourceMappingURL=stdin.d.ts.map

package/dist/utils/stdin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.d.ts","sourceRoot":"","sources":["../../src/utils/stdin.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAkBjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBhD;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAM1D"}

package/dist/utils/timeout.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Timeout configuration for network operations.
+ *
+ * Per clig.dev guidelines:
+ * - Allow network timeouts to be configured
+ * - Have a reasonable default so it doesn't hang forever
+ *
+ * Precedence: --timeout flag > RDCLI_TIMEOUT env var > default (30s)
+ */
+export declare const DEFAULT_TIMEOUT_SECONDS = 30;
+export declare const MIN_TIMEOUT_SECONDS = 1;
+export declare const MAX_TIMEOUT_SECONDS = 300;
+/**
+ * Set the timeout from CLI flag (in seconds)
+ */
+export declare function setTimeoutSeconds(seconds: number): void;
+/**
+ * Get the configured timeout in seconds.
+ * Precedence: CLI flag > env var > default
+ */
+export declare function getTimeoutSeconds(): number;
+/**
+ * Get the configured timeout in milliseconds (for axios).
+ */
+export declare function getTimeoutMs(): number;
+/**
+ * Validate timeout value and return error message if invalid.
+ * Returns null if valid.
+ */
+export declare function validateTimeout(value: string): string | null;
+/**
+ * Reset timeout state (useful for testing)
+ */
+export declare function resetTimeoutState(): void;
+//# sourceMappingURL=timeout.d.ts.map

package/dist/utils/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/utils/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAG1C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAGrC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAKvC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAgB1C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAeD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/utils/tree.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Utilities for building and rendering tree structures.
+ */
+/**
+ * Represents an item that can be placed in a tree structure.
+ */
+export interface TreeItem {
+    _id: number;
+    title: string;
+    count: number;
+    parent?: {
+        $id: number;
+    } | null;
+}
+/**
+ * Tree node for hierarchical display.
+ */
+export interface TreeNode<T extends TreeItem = TreeItem> {
+    item: T;
+    children: TreeNode<T>[];
+}
+/**
+ * Rendered tree row with display string and item data.
+ */
+export interface TreeRow {
+    /** Display string with tree characters and icon (no ANSI styling) */
+    tree: string;
+    /** Original item ID */
+    _id: number;
+    /** Item count */
+    count: number;
+}
+/**
+ * Build a tree structure from flat item lists.
+ * Handles deduplication if items appear in both lists.
+ *
+ * @param rootItems - Items at root level (no parent)
+ * @param childItems - Items with parents
+ * @returns Array of root TreeNodes with children populated
+ */
+export declare function buildTree<T extends TreeItem>(rootItems: T[], childItems: T[]): TreeNode<T>[];
+/**
+ * Render tree nodes as formatted rows with tree characters.
+ * Returns plain text without ANSI styling - styling is applied by formatters.
+ *
+ * @param nodes - Tree nodes to render
+ * @param icon - Icon to display before each title (default: 📂)
+ * @returns Array of TreeRow objects
+ */
+export declare function renderTree<T extends TreeItem>(nodes: TreeNode<T>[], icon?: string): TreeRow[];
+//# sourceMappingURL=tree.d.ts.map

package/dist/utils/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/utils/tree.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IACrD,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAwC5F;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,QAAQ,EAC3C,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,EACpB,IAAI,GAAE,MAAa,GAClB,OAAO,EAAE,CAgCX"}

package/dist/utils/tty.d.ts

@@ -0,0 +1,32 @@
+import type { OutputFormat } from "../types/index.js";
+/**
+ * Check if stdout is a TTY (interactive terminal).
+ * Returns false when output is piped or redirected.
+ */
+export declare function isStdoutTTY(): boolean;
+/**
+ * Check if stderr is a TTY (interactive terminal).
+ * Returns false when stderr is piped or redirected.
+ */
+export declare function isStderrTTY(): boolean;
+/**
+ * Get the default output format based on TTY detection.
+ * - TTY (human): plain format for full content with labeled fields
+ * - Non-TTY (piped/scripted): JSON for machine parsing
+ */
+export declare function getDefaultFormat(): OutputFormat;
+/**
+ * Set the --no-color flag state (called from CLI parser).
+ */
+export declare function setNoColorFlag(value: boolean): void;
+/**
+ * Determine if colored output should be used.
+ *
+ * Per https://no-color.org/ and clig.dev, colors are disabled when:
+ * - --no-color flag is passed
+ * - NO_COLOR env var is set (any non-empty value)
+ * - TERM=dumb
+ * - stdout is not a TTY (piped/redirected)
+ */
+export declare function shouldUseColor(): boolean;
+//# sourceMappingURL=tty.d.ts.map

package/dist/utils/tty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tty.d.ts","sourceRoot":"","sources":["../../src/utils/tty.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,YAAY,CAE/C;AAKD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAsBxC"}

package/dist/utils/validation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared validation utilities for CLI arguments and options.
+ * These are extracted to enable fast unit testing without subprocess spawning.
+ */
+/**
+ * Parse and validate a limit parameter.
+ * @param value - String value from CLI
+ * @param min - Minimum allowed value (inclusive)
+ * @param max - Maximum allowed value (inclusive)
+ * @returns Parsed number
+ * @throws UsageError if invalid
+ */
+export declare function parseLimit(value: string, min?: number, max?: number): number;
+/**
+ * Parse and validate a page parameter.
+ * @param value - String value from CLI
+ * @returns Parsed number (0-indexed)
+ * @throws UsageError if invalid
+ */
+export declare function parsePage(value: string): number;
+/**
+ * Parse and validate a bookmark ID.
+ * @param value - String value from CLI
+ * @returns Parsed positive integer
+ * @throws UsageError if invalid
+ */
+export declare function parseBookmarkId(value: string): number;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAU,EAAE,GAAG,GAAE,MAAW,GAAG,MAAM,CAMnF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMrD"}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "raindrop-cli",
+  "version": "0.1.0",
+  "description": "A TypeScript CLI for Raindrop.io built for AI agent integration and personal productivity workflows",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "rd": "dist/index.js",
+    "rdcli": "dist/index.js",
+    "raindrop-cli": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/test-utils",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/temp && mv dist/temp dist/index.js && bun run build:dts",
+    "build:dts": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "dev": "bun src/index.ts",
+    "test": "bash scripts/check.sh test",
+    "test:verbose": "bash scripts/test-unit.sh",
+    "test:live": "RDCLI_API_DELAY_MS=250 bash scripts/check.sh test:live",
+    "test:live:verbose": "RDCLI_API_DELAY_MS=250 bun test --no-parallel src/**/*.live.test.ts",
+    "test:all": "RDCLI_API_DELAY_MS=250 bash scripts/check.sh test:all",
+    "test:all:verbose": "RDCLI_API_DELAY_MS=250 bun test src",
+    "lint": "bash scripts/check.sh lint",
+    "lint:fix": "oxlint --type-aware --fix src/",
+    "lint:verbose": "oxlint --type-aware src/",
+    "format": "bash scripts/check.sh format-fix",
+    "format:verbose": "prettier --write \"src/**/*.ts\"",
+    "format:check": "bash scripts/check.sh format",
+    "format:check:verbose": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "bash scripts/check.sh typecheck",
+    "typecheck:verbose": "tsc --noEmit",
+    "verify": "bun scripts/verify.ts",
+    "verify:verbose": "VERBOSE=1 bun scripts/verify.ts",
+    "prepare": "lefthook install || true",
+    "prepublishOnly": "bun run verify && bun run build && ggshield secret scan path . -r --use-gitignore -y && ggshield secret scan path dist -r -y"
+  },
+  "keywords": [
+    "raindrop",
+    "raindrop.io",
+    "cli",
+    "bookmarks",
+    "ai-agent"
+  ],
+  "author": "Christian Catalan <crcatala@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crcatala/raindrop-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/crcatala/raindrop-cli/issues"
+  },
+  "homepage": "https://github.com/crcatala/raindrop-cli#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@lasuillard/raindrop-client": "^0.7.3",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.2",
+    "ora": "^9.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/nock": "^11.1.0",
+    "@types/node": "^22",
+    "lefthook": "^2.0.13",
+    "nock": "^14.0.10",
+    "oxlint": "^1.36.0",
+    "oxlint-tsgolint": "^0.10.1",
+    "prettier": "^3.7.4",
+    "tasuku": "^2.0.5",
+    "typescript": "^5.9.3"
+  }
+}