@localpulse/cli 0.0.1 → 0.0.3

package/README.md

@@ -25,8 +25,17 @@ chmod +x localpulse
 # Authenticate
 localpulse auth login --token lp_cli_...
 
-# Search events
-localpulse search "techno amsterdam" --date weekend --tz Europe/Amsterdam
+# Search upcoming events
+localpulse search "techno amsterdam"
+
+# Search with filters
+localpulse search "festival" --date weekend --tz Europe/Amsterdam
+
+# Include past events
+localpulse search "amsterdam" --all
+
+# Structured JSON output
+localpulse search "berlin" --json
 
 # Ingest a poster (creates a draft for review)
 localpulse ingest poster.jpg --research metadata.json
@@ -47,11 +56,13 @@ Remove stored credentials.
 
 ### `ingest <file> --research <payload.json>`
 
-Upload an event poster with research metadata. By default creates a draft for review at `localpulse.nl/publish/edit/<id>`. Use `--force` to submit directly. Use `--generate-skeleton` to see the research JSON format.
+Upload an event poster with research metadata. By default creates a draft for review at `localpulse.nl/publish/edit/<id>`. Use `--force` to submit directly. Use `--generate-skeleton` to see the research JSON format. Pass `--json` for structured output.
 
 ### `search <query>`
 
-Search events by text. Supports `--city`, `--date today|weekend`, `--tz`, `--limit`, `--cursor`.
+Search upcoming events by default. Supports `--city`, `--date today|weekend|upcoming`, `--tz`, `--all` (include past), `--json`, `--limit`, `--cursor`.
+
+All commands support `--json` for structured, machine-parseable output.
 
 ## Environment variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localpulse/cli",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Local Pulse CLI — ingest event posters, search events, manage credentials",
   "type": "module",
   "license": "MIT",

package/src/index.test.ts

@@ -24,12 +24,14 @@ function runCli(...args: string[]): { exitCode: number; stdout: string; stderr:
 }
 
 describe("localpulse", () => {
-  it("shows root help with expected commands", () => {
+  it("shows root help with expected commands and quick start", () => {
     const { exitCode, stdout } = runCli("--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("ingest");
     expect(stdout).toContain("search");
     expect(stdout).toContain("auth");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Quick start:");
     expect(stdout).not.toMatch(/^\s+directives\s/m);
     expect(stdout).not.toMatch(/^\s+event\s/m);
     expect(stdout).not.toMatch(/^\s+status\s/m);
@@ -43,12 +45,14 @@ describe("localpulse", () => {
     expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+$/);
   });
 
-  it("shows ingest help with research as primary input", () => {
+  it("shows ingest help with research, --json, and examples", () => {
     const { exitCode, stdout } = runCli("ingest", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("--research");
     expect(stdout).toContain("--generate-skeleton");
     expect(stdout).toContain("--dry-run");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Examples:");
     expect(stdout).not.toContain("--performers");
     expect(stdout).not.toContain("--genre");
     expect(stdout).not.toContain("--socials");
@@ -57,26 +61,41 @@ describe("localpulse", () => {
     expect(stdout).not.toContain("--batch");
   });
 
-  it("shows search help with --date instead of --time", () => {
+  it("shows search help with --date, --all, --json, and examples", () => {
     const { exitCode, stdout } = runCli("search", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("--date");
     expect(stdout).toContain("--city");
+    expect(stdout).toContain("--all");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("upcoming");
+    expect(stdout).toContain("Examples:");
     expect(stdout).not.toContain("--time");
   });
 
-  it("shows auth help", () => {
+  it("shows auth help with examples", () => {
     const { exitCode, stdout } = runCli("auth", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("login");
     expect(stdout).toContain("logout");
+    expect(stdout).toContain("Examples:");
   });
 
-  it("shows auth login help", () => {
+  it("shows drafts help with --status, --json, and examples", () => {
+    const { exitCode, stdout } = runCli("drafts", "--help");
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--status");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Examples:");
+  });
+
+  it("shows auth login help with examples", () => {
     const { exitCode, stdout } = runCli("auth", "login", "--help");
     expect(exitCode).toBe(0);
     expect(stdout).toContain("--token");
     expect(stdout).toContain("--api-url");
+    expect(stdout).toContain("--json");
+    expect(stdout).toContain("Examples:");
   });
 
   it("rejects unknown commands", () => {

package/src/index.ts

@@ -4,13 +4,16 @@ import { stdin, stdout } from "node:process";
 
 import { hasOption, parseArgv, readNumberOption, readStringArrayOption, readStringOption } from "./lib/argv";
 import { requireToken } from "./lib/auth";
-import { searchCliEvents } from "./lib/cli-read-client";
-import type { SearchEventCard } from "./lib/cli-read-types";
+import { toFrontendBaseUrl } from "./lib/api-url";
+import { fetchDrafts, searchCliEvents } from "./lib/cli-read-client";
+import { DRAFT_STATUSES } from "./lib/cli-read-types";
+import type { DraftListItem, DraftStatus, SearchEventCard } from "./lib/cli-read-types";
 import {
   deleteCredentials,
   getCredentialsPath,
   getDefaultApiUrl,
   resolveApiUrl,
+  resolveToken,
 } from "./lib/credentials";
 import { loginWithToken } from "./lib/login";
 import { exitCodeForError, printError } from "./lib/output";
@@ -26,8 +29,7 @@ import {
   type DraftResult,
   uploadPoster,
   createDraft,
-  uploadDraftMedia,
-  detectMediaType,
+  verifyCliToken,
 } from "./lib/upload-client";
 import packageJson from "../package.json";
 
@@ -60,6 +62,9 @@ async function main(argv: string[]): Promise<void> {
       case "search":
         await runSearch(parsed);
         break;
+      case "drafts":
+        await runDrafts(parsed);
+        break;
       default:
         throw new Error(`Unknown command: ${command}. Run \`localpulse --help\` for usage.`);
     }
@@ -76,14 +81,16 @@ async function runAuth(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   }
 
   const subcommand = parsed.positionals[0];
-  if (!subcommand || (subcommand !== "login" && subcommand !== "logout")) {
-    throw new Error("Usage: localpulse auth <login|logout>. Run `localpulse auth --help` for details.");
+  if (!subcommand || !["login", "logout", "status"].includes(subcommand)) {
+    throw new Error("Usage: localpulse auth <login|logout|status>. Run `localpulse auth --help` for details.");
   }
 
   if (subcommand === "login") {
     await runAuthLogin(parsed);
+  } else if (subcommand === "status") {
+    await runAuthStatus(parsed);
   } else {
-    await runAuthLogout();
+    await runAuthLogout(parsed);
   }
 }
 
@@ -93,6 +100,7 @@ async function runAuthLogin(parsed: ReturnType<typeof parseArgv>): Promise<void>
     return;
   }
 
+  const jsonOutput = hasOption(parsed, "json");
   const apiUrl = readStringOption(parsed, "api-url")?.trim() || getDefaultApiUrl();
   const token = await resolveLoginToken(readStringOption(parsed, "token"));
   if (!isLikelyCliToken(token)) {
@@ -100,18 +108,64 @@ async function runAuthLogin(parsed: ReturnType<typeof parseArgv>): Promise<void>
   }
 
   const result = await loginWithToken(apiUrl, token);
-  stdout.write(`Authenticated. Credentials saved to ${result.credentials_path}\n`);
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify({ authenticated: true, credentials_path: result.credentials_path })}\n`);
+  } else {
+    stdout.write(`Authenticated. Credentials saved to ${result.credentials_path}\n`);
+  }
 }
 
-async function runAuthLogout(): Promise<void> {
+async function runAuthLogout(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  const jsonOutput = hasOption(parsed, "json");
   const deleted = await deleteCredentials();
-  if (deleted) {
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify({ logged_out: deleted })}\n`);
+  } else if (deleted) {
     stdout.write("Logged out. Credentials removed.\n");
   } else {
     stdout.write("No credentials found.\n");
   }
 }
 
+async function runAuthStatus(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  const jsonOutput = hasOption(parsed, "json");
+  const token = await resolveToken();
+  const apiUrl = await resolveApiUrl();
+  const credentialsPath = getCredentialsPath();
+  const source = process.env.LP_TOKEN?.trim() ? "LP_TOKEN" : credentialsPath;
+
+  if (!token) {
+    if (jsonOutput) {
+      stdout.write(`${JSON.stringify({ authenticated: false, source: null, reason: "no_token" })}\n`);
+    } else {
+      stdout.write("Not authenticated. Run `localpulse auth login` or set LP_TOKEN.\n");
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const result = await verifyCliToken(apiUrl, token);
+    if (jsonOutput) {
+      stdout.write(`${JSON.stringify({ authenticated: true, email: result.email, api_url: apiUrl, source })}\n`);
+    } else {
+      stdout.write(`Authenticated as ${result.email}\n`);
+      stdout.write(`  API:         ${apiUrl}\n`);
+      stdout.write(`  Credentials: ${source}\n`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Token verification failed";
+    if (jsonOutput) {
+      stdout.write(`${JSON.stringify({ authenticated: false, api_url: apiUrl, source, error: message })}\n`);
+    } else {
+      stdout.write(`Authentication failed: ${message}\n`);
+      stdout.write(`  API:         ${apiUrl}\n`);
+      stdout.write(`  Credentials: ${source}\n`);
+    }
+    process.exitCode = 1;
+  }
+}
+
 async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   if (hasOption(parsed, "help")) {
     stdout.write(ingestHelp());
@@ -143,6 +197,7 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   const apiUrl = await resolveApiUrl();
   const dryRun = hasOption(parsed, "dry-run");
   const force = hasOption(parsed, "force");
+  const jsonOutput = hasOption(parsed, "json");
   const token = dryRun ? "" : await requireToken();
 
   const uploadOptions = {
@@ -157,13 +212,16 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
     venue: readStringOption(parsed, "venue") ?? mapped.venue,
     extraMedia: readStringArrayOption(parsed, "extra-media"),
     dryRun,
-    force,
   };
 
   if (dryRun) {
     const result = await uploadPoster(apiUrl, token, uploadOptions);
     if ("dry_run" in result) {
-      stdout.write(`Dry run passed: ${result.file} (${result.extra_media_count} extra media)\n`);
+      if (jsonOutput) {
+        stdout.write(`${JSON.stringify(result)}\n`);
+      } else {
+        stdout.write(`Dry run passed: ${result.file} (${result.extra_media_count} extra media)\n`);
+      }
     }
     return;
   }
@@ -171,25 +229,42 @@ async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
   if (force) {
     const result = await uploadPoster(apiUrl, token, uploadOptions);
     if (!("dry_run" in result)) {
-      printIngestResult(result);
+      if (jsonOutput) {
+        stdout.write(`${JSON.stringify(result)}\n`);
+      } else {
+        printIngestResult(result);
+      }
     }
     return;
   }
 
-  // Default: draft flow
+  // Default: draft flow — create draft then submit to ingestion pipeline
   const draft = await runDraftIngest(apiUrl, token, file, uploadOptions);
-  printDraftResult(draft, apiUrl);
+  process.stderr.write("Submitting to ingestion pipeline...\n");
+  const result = await uploadPoster(apiUrl, token, { ...uploadOptions, draftId: draft.id }) as UploadPosterResult;
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify({ draft_id: draft.id, ...result })}\n`);
+  } else {
+    printIngestResult(result);
+    const baseUrl = toFrontendBaseUrl(apiUrl);
+    stdout.write(`Draft: ${baseUrl}/publish/edit/${draft.id}\n`);
+  }
 }
 
 async function validateFilePaths(primaryFile: string, extraMedia?: string[]): Promise<void> {
-  const { existsSync } = await import("node:fs");
-  const missing: string[] = [];
-  if (!existsSync(primaryFile)) missing.push(primaryFile);
-  for (const p of extraMedia ?? []) {
-    if (!existsSync(p)) missing.push(p);
+  const { access } = await import("node:fs/promises");
+
+  if (extraMedia && extraMedia.length > 2) {
+    throw new Error("`--extra-media` supports at most 2 files.");
   }
-  if (missing.length) {
-    throw new Error(`File(s) not found: ${missing.join(", ")}`);
+
+  const checkFile = async (path: string, label: string) => {
+    try { await access(path); } catch { throw new Error(`File not found: ${path} (${label})`); }
+  };
+
+  await checkFile(primaryFile, "file");
+  for (const [i, p] of (extraMedia ?? []).entries()) {
+    await checkFile(p, `extra-media[${i}]`);
   }
 }
 
@@ -201,38 +276,13 @@ async function runDraftIngest(
 ): Promise<DraftResult> {
   await validateFilePaths(primaryFile, options.extraMedia);
 
-  stdout.write("Creating draft...\n");
+  process.stderr.write("Creating draft...\n");
   const draft = await createDraft(apiUrl, token, options);
-
-  stdout.write(`Draft created: ${draft.id}\n`);
-  stdout.write("Uploading primary media...\n");
-  await uploadDraftMedia(apiUrl, token, draft.id, primaryFile, {
-    mediaType: detectMediaType(primaryFile),
-    sortOrder: 0,
-    isPrimary: true,
-  });
-
-  if (options.extraMedia?.length) {
-    for (const [index, path] of options.extraMedia.entries()) {
-      stdout.write(`Uploading extra media ${index + 1}...\n`);
-      await uploadDraftMedia(apiUrl, token, draft.id, path, {
-        mediaType: detectMediaType(path),
-        sortOrder: index + 1,
-        isPrimary: false,
-      });
-    }
-  }
+  process.stderr.write(`Draft created: ${draft.id}\n`);
 
   return draft;
 }
 
-function printDraftResult(draft: DraftResult, apiUrl: string): void {
-  const baseUrl = apiUrl.replace(/\/api\/?$/, "").replace(/\/$/, "");
-  stdout.write(`\nDraft saved: ${draft.id}\n`);
-  stdout.write("Open the publish dashboard to review and submit:\n");
-  stdout.write(`  ${baseUrl}/publish/edit/${draft.id}\n`);
-}
-
 function printIngestResult(result: UploadPosterResult): void {
   stdout.write(`${result.message}\n`);
   if (result.run_id) {
@@ -254,19 +304,29 @@ async function runSearch(parsed: ReturnType<typeof parseArgv>): Promise<void> {
 
   const query = parsed.positionals.join(" ").trim();
   if (!query) {
-    throw new Error("Search query is required. Run `localpulse search --help` for usage.");
+    throw new Error("Search query is required.\n  localpulse search \"amsterdam\"\n  localpulse search --help");
   }
 
+  const jsonOutput = hasOption(parsed, "json");
+  const allEvents = hasOption(parsed, "all");
+  const dateFilter = readDateFilterOption(parsed);
+  const time_intent = allEvents ? undefined : (dateFilter ?? "upcoming");
+
   const apiUrl = await resolveApiUrl();
   const result = await searchCliEvents(apiUrl, {
     query,
     city: readStringOption(parsed, "city"),
-    time_intent: readDateFilterOption(parsed),
+    time_intent,
     timezone: readStringOption(parsed, "tz"),
     limit: readNumberOption(parsed, "limit") ?? 10,
     cursor: readNumberOption(parsed, "cursor") ?? 0,
   });
 
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
   if (result.results.length === 0) {
     stdout.write("No events found.\n");
     return;
@@ -295,6 +355,63 @@ function printSearchCard(card: SearchEventCard): void {
   stdout.write(`  ${card.frontend_url}\n`);
 }
 
+const VALID_DRAFT_STATUSES: ReadonlySet<string> = new Set<DraftStatus>(DRAFT_STATUSES);
+
+function countByStatus(drafts: DraftListItem[]): Record<DraftStatus, number> {
+  const counts: Record<DraftStatus, number> = { uploading: 0, processing: 0, ready: 0, failed: 0 };
+  for (const d of drafts) counts[d.status]++;
+  return counts;
+}
+
+async function runDrafts(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  if (hasOption(parsed, "help")) {
+    stdout.write(draftsHelp());
+    return;
+  }
+
+  const jsonOutput = hasOption(parsed, "json");
+  const statusFilter = readStringOption(parsed, "status");
+
+  if (statusFilter && !VALID_DRAFT_STATUSES.has(statusFilter)) {
+    throw new Error(
+      `\`--status\` must be \`uploading\`, \`processing\`, \`ready\`, or \`failed\`.\n  localpulse drafts --status failed`,
+    );
+  }
+
+  const apiUrl = await resolveApiUrl();
+  const token = await requireToken();
+  const drafts = await fetchDrafts(apiUrl, token, statusFilter as DraftStatus | undefined);
+  const counts = countByStatus(drafts);
+
+  if (jsonOutput) {
+    stdout.write(`${JSON.stringify({ total: drafts.length, counts, drafts }, null, 2)}\n`);
+    return;
+  }
+
+  if (drafts.length === 0) {
+    stdout.write("No drafts.\n");
+    return;
+  }
+
+  const summary = Object.entries(counts).filter(([, n]) => n > 0).map(([s, n]) => `${n} ${s}`).join(", ");
+  stdout.write(`Drafts: ${drafts.length} total (${summary})\n\n`);
+
+  const baseUrl = toFrontendBaseUrl(apiUrl);
+  for (const draft of drafts) {
+    printDraftListItem(draft, baseUrl);
+  }
+}
+
+function printDraftListItem(draft: DraftListItem, baseUrl: string): void {
+  const title = draft.metadata?.event_title ? `"${draft.metadata.event_title}"` : "";
+  const status = draft.status.padEnd(10);
+  stdout.write(`${draft.id}  ${status}  ${draft.updated_at}  ${title}\n`);
+  if (draft.status === "failed" && draft.error_message) {
+    stdout.write(`  Error: ${draft.error_message}\n`);
+  }
+  stdout.write(`  ${baseUrl}/publish/edit/${draft.id}\n`);
+}
+
 async function resolveLoginToken(explicitToken?: string): Promise<string> {
   if (explicitToken?.trim()) {
     return explicitToken.trim();
@@ -321,15 +438,15 @@ async function resolveLoginToken(explicitToken?: string): Promise<string> {
 
 function readDateFilterOption(
   parsed: ReturnType<typeof parseArgv>,
-): "today" | "weekend" | undefined {
+): "today" | "weekend" | "upcoming" | undefined {
   const value = readStringOption(parsed, "date");
   if (!value) {
     return undefined;
   }
-  if (value === "today" || value === "weekend") {
+  if (value === "today" || value === "weekend" || value === "upcoming") {
     return value;
   }
-  throw new Error("`--date` must be `today` or `weekend`.");
+  throw new Error("`--date` must be `today`, `weekend`, or `upcoming`.\n  localpulse search \"amsterdam\" --date today --tz Europe/Amsterdam");
 }
 
 function rootHelp(): string {
@@ -337,16 +454,23 @@ function rootHelp(): string {
 
 Commands:
   ingest   Ingest an event poster into Local Pulse
-  search   Search existing events
+  search   Search upcoming events
+  drafts   List your submission drafts
   auth     Login and logout
 
 Options:
   --help     Show help
   --version  Show version
+  --json     Output structured JSON (supported by all commands)
 
 Environment:
   LP_TOKEN    Override stored auth token
   LP_API_URL  Override API base URL (default: https://localpulse.nl)
+
+Quick start:
+  localpulse auth login --token <token>
+  localpulse search "amsterdam"
+  localpulse ingest poster.jpg --research data.json
 `;
 }
 
@@ -356,8 +480,13 @@ function authHelp(): string {
 Commands:
   login    Authenticate with a Local Pulse CLI token
   logout   Remove stored credentials
+  status   Check authentication status and verify token
 
-Run \`localpulse auth login --help\` for login options.
+Examples:
+  localpulse auth login --token lp_cli_...
+  localpulse auth status
+  localpulse auth status --json
+  localpulse auth logout
 `;
 }
 
@@ -367,9 +496,15 @@ function authLoginHelp(): string {
 Options:
   --token <token>        Local Pulse CLI token
   --api-url <url>        Override API base URL
+  --json                 Output structured JSON
   --help                 Show this help
 
 Without --token, prompts interactively (visit https://localpulse.nl/dev to create a token).
+
+Examples:
+  localpulse auth login --token lp_cli_...
+  localpulse auth login --token lp_cli_... --json
+  LP_TOKEN=lp_cli_... localpulse auth login
 `;
 }
 
@@ -388,7 +523,16 @@ Research payload:
   --generate-skeleton     Print an example research template and exit
 
   The payload is JSON with five top-level sections. All are optional,
-  but the more you provide, the better the enrichment.
+  but richer research produces much better event listings.
+
+  Quality checklist (aim to fill as many as possible):
+  ✓ Performer socials: Instagram, Spotify, Bandcamp, SoundCloud, RA, website
+  ✓ Organizer socials: Instagram, website, RA promoter page
+  ✓ Venue google_place_id (search Google Maps → share → extract place ID)
+  ✓ Multiple event.urls: venue page, RA, Facebook event, artist page
+  ✓ Embed URLs in context: Spotify album/track links, YouTube videos
+  ✓ Performer context: recent releases, labels, residencies, tour info
+  ✓ All support acts as separate performer entries
 
   performers[]            Who is performing or presenting
     .name                 Full name (required per performer)
@@ -441,29 +585,60 @@ Extra:
   --extra-media <file>... Up to 2 additional poster or flyer images
 
 Options:
+  --json                  Output structured JSON
   --help                  Show this help
 
-Example:
+Examples:
   localpulse ingest --generate-skeleton > research.json
-  # research and fill in the payload
-  localpulse ingest ./poster.jpg --research research.json
+  localpulse ingest poster.jpg --research research.json
+  localpulse ingest poster.jpg --research research.json --force
+  localpulse ingest poster.jpg --research research.json --json
+  cat research.json | localpulse ingest poster.jpg --research -
 `;
 }
 
 function searchHelp(): string {
   return `Usage: localpulse search <query> [options]
 
-Search existing events on Local Pulse.
+Search events on Local Pulse. Returns upcoming events by default.
 
 Arguments:
   query                 Free-text search query
 
 Options:
   --city <text>         Filter by city
-  --date <today|weekend> Time intent filter
+  --date <today|weekend|upcoming>  Time intent filter (default: upcoming)
   --tz <timezone>       IANA timezone (requires --date)
+  --all                 Include past events
+  --json                Output structured JSON
   --limit <n>           Results per page (1-25, default 10)
   --cursor <n>          Pagination offset
   --help                Show this help
+
+Examples:
+  localpulse search "amsterdam"
+  localpulse search "techno" --city Amsterdam
+  localpulse search "festival" --date weekend --tz Europe/Amsterdam
+  localpulse search "amsterdam" --all
+  localpulse search "berlin" --json
+  localpulse search "amsterdam" --json | jq '.results[].frontend_url'
+`;
+}
+
+function draftsHelp(): string {
+  return `Usage: localpulse drafts [options]
+
+List your event submission drafts and their status.
+
+Options:
+  --status <uploading|processing|ready|failed>  Filter by status
+  --json                Output structured JSON
+  --help                Show this help
+
+Examples:
+  localpulse drafts
+  localpulse drafts --status failed
+  localpulse drafts --json
+  localpulse drafts --json | jq '.counts'
 `;
 }

package/src/lib/api-url.ts

@@ -13,3 +13,7 @@ export function buildApiUrl(apiUrl: string, path: string): string {
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
   return `${normalizeApiUrl(apiUrl)}${normalizedPath}`;
 }
+
+export function toFrontendBaseUrl(apiUrl: string): string {
+  return apiUrl.replace(/\/api\/?$/, "").replace(/\/$/, "");
+}

package/src/lib/cli-read-client.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, mock } from "bun:test";
 import { CliApiError } from "./api-response";
 import {
   fetchCliInfo,
+  fetchDrafts,
   searchCliEvents,
 } from "./cli-read-client";
 
@@ -70,6 +71,53 @@ describe("cli-read-client", () => {
     });
   });
 
+  it("encodes upcoming time_intent in query params", async () => {
+    globalThis.fetch = mock(async (input) => {
+      expect(String(input)).toBe(
+        "https://localpulse.nl/api/cli/events/search?query=berlin&limit=10&cursor=0&time_intent=upcoming",
+      );
+      return new Response(
+        JSON.stringify({ results: [], cursor: 0, next_cursor: null }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    expect(
+      await searchCliEvents("https://localpulse.nl", {
+        query: "berlin",
+        time_intent: "upcoming",
+        limit: 10,
+        cursor: 0,
+      }),
+    ).toEqual({ results: [], cursor: 0, next_cursor: null });
+  });
+
+  it("fetches drafts with auth header", async () => {
+    globalThis.fetch = mock(async (input, init) => {
+      expect(String(input)).toBe("https://localpulse.nl/api/drafts");
+      expect(init?.headers).toMatchObject({ authorization: "Bearer test-token" });
+      return new Response(
+        JSON.stringify([
+          { id: "abc", status: "uploading", error_message: null, metadata: null, created_at: "2026-01-01T00:00:00Z", updated_at: "2026-01-01T00:00:00Z" },
+        ]),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const result = await fetchDrafts("https://localpulse.nl", "test-token");
+    expect(result).toHaveLength(1);
+    expect(result[0].status).toBe("uploading");
+  });
+
+  it("passes status filter to drafts endpoint", async () => {
+    globalThis.fetch = mock(async (input) => {
+      expect(String(input)).toBe("https://localpulse.nl/api/drafts?status=failed");
+      return new Response(JSON.stringify([]), { status: 200, headers: { "Content-Type": "application/json" } });
+    }) as typeof fetch;
+
+    expect(await fetchDrafts("https://localpulse.nl", "test-token", "failed")).toEqual([]);
+  });
+
   it("surfaces REST error responses", async () => {
     globalThis.fetch = mock(async () => {
       return new Response(

package/src/lib/cli-read-client.ts

@@ -7,6 +7,8 @@ import {
 import { buildApiUrl } from "./api-url";
 import type {
   CliInfoResult,
+  DraftListItem,
+  DraftStatus,
   SearchEventsResult,
 } from "./cli-read-types";
 
@@ -20,7 +22,7 @@ export async function searchCliEvents(
   args: {
     query: string;
     city?: string;
-    time_intent?: "today" | "weekend";
+    time_intent?: "today" | "weekend" | "upcoming";
     timezone?: string;
     limit: number;
     cursor: number;
@@ -84,6 +86,42 @@ function parseCliInfoResult(payload: ApiResponseBody): CliInfoResult {
   return result as CliInfoResult;
 }
 
+export async function fetchDrafts(
+  apiUrl: string,
+  token: string,
+  status?: DraftStatus,
+): Promise<DraftListItem[]> {
+  const path = status ? `/api/drafts?status=${encodeURIComponent(status)}` : "/api/drafts";
+  const response = await fetch(buildApiUrl(apiUrl, path), {
+    method: "GET",
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${token}`,
+    },
+  });
+
+  const text = await response.text();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new CliApiError("Drafts fetch returned non-JSON response", { httpStatus: response.status });
+  }
+
+  if (!response.ok) {
+    const body = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed as ApiResponseBody : undefined;
+    throw new CliApiError(extractApiErrorMessage(body ?? {}, `Drafts fetch failed (${response.status})`), {
+      httpStatus: response.status,
+      body,
+    });
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new Error("Invalid API response: expected drafts array.");
+  }
+  return parsed as DraftListItem[];
+}
+
 function parseSearchEventsResult(payload: ApiResponseBody): SearchEventsResult {
   const result = payload as Partial<SearchEventsResult>;
   if (

package/src/lib/cli-read-types.ts

@@ -25,3 +25,15 @@ export type SearchEventsResult = {
   cursor: number;
   next_cursor: number | null;
 };
+
+export const DRAFT_STATUSES = ["uploading", "processing", "ready", "failed"] as const;
+export type DraftStatus = (typeof DRAFT_STATUSES)[number];
+
+export type DraftListItem = {
+  id: string;
+  status: DraftStatus;
+  error_message: string | null;
+  metadata: { event_title?: string; venue_name?: string; poster_id?: string } | null;
+  created_at: string;
+  updated_at: string;
+};

package/src/lib/research-schema.ts

@@ -60,29 +60,54 @@ export function generateResearchSkeleton(): ResearchPayload {
         name: "DJ Nobu",
         type: "DJ",
         genre: "techno",
-        socials: ["https://instagram.com/djnobu", "https://ra.co/dj/djnobu"],
-        context: "Berlin-based Japanese DJ, known for long hypnotic sets",
+        socials: [
+          "https://instagram.com/djnobu",
+          "https://ra.co/dj/djnobu",
+          "https://soundcloud.com/djnobu",
+          "https://djnobu.bandcamp.com",
+          "https://open.spotify.com/artist/0abc123",
+        ],
+        context:
+          "Berlin-based Japanese DJ, known for long hypnotic sets. Resident at Future Terror (Tokyo). Recent release: 'Prism' on Bitta (2025).",
+      },
+      {
+        name: "Nene H",
+        type: "DJ",
+        genre: "experimental electronic",
+        socials: [
+          "https://instagram.com/nenehmusic",
+          "https://ra.co/dj/neneh",
+        ],
+        context: "Support. Tehran-born, Berlin-based. Known for deconstructed club music.",
       },
     ],
     organizer: {
       name: "Dekmantel",
-      socials: ["https://instagram.com/daboratorium"],
-      context: "Amsterdam-based collective, running events since 2007",
+      socials: [
+        "https://instagram.com/daboratorium",
+        "https://www.dekmantel.com",
+        "https://ra.co/promoters/16478",
+      ],
+      context: "Amsterdam-based collective, running events since 2007. Annual festival + club nights.",
     },
     venue: {
       name: "Shelter Amsterdam",
       city: "Amsterdam",
       google_place_id: "",
-      context: "Underground club beneath A'DAM Tower, 350 capacity, one room",
+      context: "Underground club beneath A'DAM Tower, 350 capacity, one room, Funktion-One sound.",
     },
     event: {
       title: "Shelter Presents: DJ Nobu",
       date: "2026-03-14T22:00:00+01:00",
       type: "club night",
       price: "€15-25",
-      urls: ["https://ra.co/events/1234567"],
+      urls: [
+        "https://ra.co/events/1234567",
+        "https://www.dekmantel.com/events/shelter-nobu",
+      ],
       ticket_url: "https://tickets.example.com/shelter-nobu",
-      context: "Part of ADE week. Doors at 22:00. Cash only at door.",
+      context:
+        "Part of ADE week. Doors at 22:00. Cash only at door. DJ Nobu plays an extended 4-hour set.",
     },
     context: "",
   };

package/src/lib/upload-client.ts

@@ -23,8 +23,7 @@ export type IngestUploadOptions = {
   venue?: string;
   extraMedia?: string[];
   dryRun?: boolean;
-  /** When true, bypass drafts and upload directly to the ingestion pipeline. */
-  force?: boolean;
+  draftId?: string;
 };
 
 export type UploadDryRunResult = {
@@ -90,6 +89,7 @@ export async function uploadPoster(
   if (options.city) {
     setOptionalField(form, "venue_city", options.city);
   }
+  setOptionalField(form, "draft_id", options.draftId);
 
   if (options.extraMedia?.length) {
     const mediaTypes: string[] = [];