hedge-broker 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to `hedge-broker` are documented here. This project follows
 [Semantic Versioning](https://semver.org) and
 [Keep a Changelog](https://keepachangelog.com).
 
+## [0.2.0] - 2026-07-06
+
+### Added
+
+- `submit` now covers the full create schema: `--website`, `--fein`, `--entity-type`, `--naics`, `--business-phone`, `--business-email`, `--contact-first`, `--contact-last`, `--contact-email`, `--contact-phone`, `--address`, `--address2`, `--city`, `--zip`, `--tiv`, `--vehicles`, `--payroll`, `--insured-id`, `--producer-email`.
+- `submit --body <file|->` sends a full JSON request body from a file or stdin; explicit flags take precedence over matching top-level keys, applicant flags merge over the body's applicant, and address flags merge into its mailing_address.
+- `submit` sends an `Idempotency-Key` header: a random UUID per invocation by default, or your own via `--idempotency-key <key>`. Replay engages only when the same key is re-sent within 24h (per brokerage), so scripted retries that must not double-create should pass their own key.
+- `submit` fails fast with a clear message when a partial mailing address is given; the API requires `--address`, `--city`, `--state`, and `--zip` to resolve together (fields supplied via `--body` count).
+- `submissions` filters: `--limit`, `--offset`, `--updated-since` (alongside the existing `--status` and `--search`).
+- `policy <policyId>`: policy detail (term, net premium, total billed, commission, payment plan, documents).
+- `policy-doc <policyId> <kind> [-o file]`: download the binder, policy, or declarations PDF.
+- `documents <submissionId>`: list a submission's finalized documents.
+- `download <documentId> [-o file]`: download a finalized document PDF (filename from Content-Disposition when `-o` is omitted).
+- `market-requirements <marketId> --lob <slug> [--state ST] [--programs keys]`: what a market needs to quote a line.
+- `status` now renders the live per-carrier marketing table (carrier, line, status, quote premium), a status roll-up, the effective date, and the documents on file.
+- `policies` table gains effective and expiration columns; `payments` gains an invoice_url column.
+
+### Fixed
+
+- `submit --state` now actually sends the state (top-level `primary_state`, or the mailing address state when a mailing address is present). In 0.1.0 the flag was accepted but dropped.
+- Non-JSON API error bodies (HTML 502s from a proxy) no longer crash uploads with a SyntaxError; the raw text is surfaced instead.
+- API validation errors (FastAPI `detail` arrays/objects) render as readable `loc: message` lines instead of `[object Object]`.
+- Filenames taken from a server's Content-Disposition header are sanitized (path separators, control characters, and Windows-invalid characters stripped) before writing to disk.
+
 ## [0.1.0] - 2026-07-06
 
 ### Added

package/README.md

@@ -48,17 +48,22 @@ hedge status <submission-id>
 | Command | What it does |
 | --- | --- |
 | `hedge appetite <class> [--state ST] [--lob slug]` | Which markets have appetite for a class of business. |
-| `hedge submit --insured <name> --narrative <text> [--lob a,b] [--state ST] [--effective YYYY-MM-DD]` | Create a submission (does not market it yet). |
+| `hedge market-requirements <marketId> --lob <slug> [--state ST] [--programs keys]` | What a market needs to quote a line: the application package plus per-program requirements. Market ids come from `hedge appetite --json`. |
+| `hedge submit --insured <name> --narrative <text> [flags]` | Create a submission (does not market it yet). Applicant, contact, address, and exposure flags are listed in `hedge submit --help`; `--body <file\|->` sends a full JSON body, with explicit flags taking precedence. |
 | `hedge upload <submissionId> <file.pdf> [--name label]` | Attach an ACORD, loss runs, or supplement. |
 | `hedge requirements <submissionId>` | What the submission still needs (per market, forms, carrier questions). |
 | `hedge finalize <submissionId>` | Start marketing the submission to carriers. |
-| `hedge status <submissionId>` | Submission detail plus live marketing and quote status. |
-| `hedge submissions [--status state] [--search q]` | List your brokerage's submissions. |
+| `hedge status <submissionId>` | Submission detail plus the live per-carrier marketing table, status roll-up, and documents on file. |
+| `hedge submissions [--status state] [--search q] [--limit n] [--offset n] [--updated-since iso]` | List your brokerage's submissions, with filters and paging. |
+| `hedge documents <submissionId>` | List a submission's finalized documents (ACORDs, quotes, binders). |
+| `hedge download <documentId> [-o file]` | Download a finalized document PDF. |
 | `hedge quotes <submissionId>` | List instant-quote carrier sessions and their open questions. |
 | `hedge answer <submissionId> <sessionId> --set k=v [--set k=v ...]` | Answer a carrier session's questions. |
 | `hedge request-quote <submissionId> <sessionId>` | Close a carrier session, request an indication, then a quote. |
-| `hedge policies` | List bound policies. |
-| `hedge payments` | List payment and invoice status. |
+| `hedge policies` | List bound policies with term dates. |
+| `hedge policy <policyId>` | Policy detail: term, premium, commission, payment plan, documents. Policy ids come from `hedge policies --json`. |
+| `hedge policy-doc <policyId> <kind> [-o file]` | Download a policy PDF; kind is `binder`, `policy`, or `declarations`. |
+| `hedge payments` | List payment and invoice status, with invoice links. |
 | `hedge whoami` | Show the signed-in broker and brokerage. |
 | `hedge login` / `hedge logout` | Sign in and out. |
 
@@ -78,15 +83,39 @@ hedge appetite "roofing contractor" --state CA
 hedge submit \
   --insured "Peak Roofing LLC" \
   --narrative "Residential re-roofing, no hot tar, no work over 3 stories" \
-  --lob commercial_general_liability \
-  --state CA \
-  --effective 2026-08-01
+  --lob commercial_general_liability,commercial_property \
+  --effective 2026-08-01 \
+  --website https://peakroofing.example.com \
+  --fein 12-3456789 \
+  --entity-type llc \
+  --naics 238160 \
+  --business-phone "415-555-0100" \
+  --business-email office@peakroofing.example.com \
+  --contact-first Dana --contact-last Rivera \
+  --contact-email dana@peakroofing.example.com \
+  --contact-phone "415-555-0101" \
+  --address "1200 Harrison St" --address2 "Suite 4" \
+  --city Oakland --state CA --zip 94612 \
+  --tiv 250000 --payroll 900000 --vehicles 3
 hedge upload <submission-id> ./acord-125.pdf --name "ACORD 125"
 hedge requirements <submission-id>
 hedge finalize <submission-id>
 hedge status <submission-id>
+hedge documents <submission-id>
+hedge download <document-id> -o quote.pdf
 ```
 
+When a mailing address is in play, `--state` fills the mailing address state; the address must be complete (`--address`, `--city`, `--state`, `--zip`, counting fields supplied via `--body`). With `--state` alone it is sent as the submission's top-level `primary_state`.
+
+Prefer building the request in a file (or another program)? Send a full JSON body. Explicit flags still win: top-level flag values replace matching body keys, applicant flags merge over the body's applicant, and address flags merge into its mailing_address:
+
+```bash
+hedge submit --body ./submission.json
+cat submission.json | hedge submit --body - --effective 2026-09-01
+```
+
+Every `submit` sends an `Idempotency-Key` header (a random UUID each run). Replay only engages when the same key is re-sent within 24 hours, so a scripted retry that must not double-create should pass its own key with `--idempotency-key <key>`.
+
 ## Signing in
 
 The CLI signs in with OAuth 2.1, so there are no API keys to copy around for the interactive flow, and it works over SSH.
@@ -98,7 +127,7 @@ The CLI signs in with OAuth 2.1, so there are no API keys to copy around for the
 
 Credentials are stored per profile at `~/.config/taven-cli/hedge.<profile>.json` with `0600` permissions. Access tokens are refreshed automatically. Sign out with `hedge logout`.
 
-The CLI requests the `broker_mcp` and `broker_submit` scopes. Submitting on a brokerage's behalf requires that the brokerage has connected apps and programmatic submission enabled by Hedge. Read commands (appetite, submissions, status, requirements, policies, payments) work with either scope. `submit`, `upload`, `finalize`, and the carrier-quote commands require `broker_submit`.
+The CLI requests the `broker_mcp` and `broker_submit` scopes. Submitting on a brokerage's behalf requires that the brokerage has connected apps and programmatic submission enabled by Hedge. Read commands (appetite, market-requirements, submissions, status, requirements, documents, download, quotes, policies, policy, policy-doc, payments) work with either scope. `submit`, `upload`, `finalize`, `answer`, and `request-quote` require `broker_submit`.
 
 ## License
 

package/dist/index.js

@@ -103,7 +103,7 @@ async function deviceLogin(opts) {
     }
     throw new Error(pb.error === "access_denied" ? "Access was denied" : pb.error || `Login failed (${poll.status})`);
   }
-  throw new Error("Login timed out \u2014 run the command again");
+  throw new Error("Login timed out. Run the command again");
 }
 async function loopbackLogin(opts) {
   const { meta, clientId } = opts;
@@ -178,6 +178,7 @@ function sleep(ms) {
 }
 
 // src/core/http.ts
+import { writeFileSync as writeFileSync2 } from "fs";
 var ApiError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -185,11 +186,37 @@ var ApiError = class extends Error {
   }
   status;
 };
+function renderErrorDetail(detail, fallback) {
+  if (detail == null) return fallback;
+  if (typeof detail === "string") return detail.trim() || fallback;
+  if (Array.isArray(detail)) {
+    const lines = detail.map((entry) => {
+      if (entry && typeof entry === "object" && "msg" in entry) {
+        const loc = Array.isArray(entry.loc) ? entry.loc.join(".") : "";
+        return (loc ? loc + ": " : "") + String(entry.msg);
+      }
+      return JSON.stringify(entry);
+    });
+    return lines.join("\n") || fallback;
+  }
+  if (typeof detail === "object") return JSON.stringify(detail);
+  return String(detail);
+}
+function apiErrorFrom(status, parsed, fallback) {
+  let detail = void 0;
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed;
+    detail = obj.detail ?? obj.error;
+  } else if (typeof parsed === "string") {
+    detail = parsed;
+  }
+  return new ApiError(status, renderErrorDetail(detail, fallback));
+}
 async function bearer(cfg) {
   const tok = loadToken(cfg);
-  if (!tok) throw new ApiError(401, "Not signed in \u2014 run `login` first");
+  if (!tok) throw new ApiError(401, "Not signed in. Run `login` first");
   if (tok.expires_at - 60 > Math.floor(Date.now() / 1e3)) return tok.access_token;
-  if (!tok.refresh_token) throw new ApiError(401, "Session expired \u2014 run `login` again");
+  if (!tok.refresh_token) throw new ApiError(401, "Session expired. Run `login` again");
   try {
     const r = await refresh(tok.token_endpoint, tok.client_id, tok.refresh_token);
     const updated = {
@@ -203,7 +230,7 @@ async function bearer(cfg) {
     return updated.access_token;
   } catch {
     clearToken(cfg);
-    throw new ApiError(401, "Session expired \u2014 run `login` again");
+    throw new ApiError(401, "Session expired. Run `login` again");
   }
 }
 async function apiRequest(opts, method, path, init) {
@@ -230,10 +257,7 @@ async function apiRequest(opts, method, path, init) {
       parsed = text;
     }
   }
-  if (!res.ok) {
-    const detail = parsed && typeof parsed === "object" && "detail" in parsed && parsed.detail || parsed && typeof parsed === "object" && "error" in parsed && parsed.error || (typeof parsed === "string" ? parsed : `Request failed (${res.status})`);
-    throw new ApiError(res.status, String(detail));
-  }
+  if (!res.ok) throw apiErrorFrom(res.status, parsed, `Request failed (${res.status})`);
   return parsed;
 }
 async function multipartRequest(opts, method, path, form) {
@@ -243,13 +267,60 @@ async function multipartRequest(opts, method, path, form) {
   else headers.Authorization = `Bearer ${await bearer(opts.cfg)}`;
   const res = await fetch(url, { method, headers, body: form });
   const text = await res.text();
-  let parsed = text ? JSON.parse(text) : void 0;
-  if (!res.ok) {
-    const detail = parsed && typeof parsed === "object" && "detail" in parsed && parsed.detail || `Upload failed (${res.status})`;
-    throw new ApiError(res.status, String(detail));
+  let parsed = void 0;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
   }
+  if (!res.ok) throw apiErrorFrom(res.status, parsed, `Upload failed (${res.status})`);
   return parsed;
 }
+function sanitizeFilename(name) {
+  const last = name.replace(/\\/g, "/").split("/").pop() ?? "";
+  const cleaned = last.replace(/[:*?"<>|\u0000-\u001f]/g, "_").trim();
+  if (!cleaned || cleaned === "." || cleaned === "..") return "";
+  return cleaned;
+}
+function dispositionFilename(header) {
+  if (!header) return void 0;
+  const star = /filename\*=(?:UTF-8'')?"?([^";]+)"?/i.exec(header);
+  if (star) {
+    try {
+      return decodeURIComponent(star[1].trim());
+    } catch {
+    }
+  }
+  const plain = /filename="?([^";]+)"?/i.exec(header);
+  return plain ? plain[1].trim() : void 0;
+}
+async function downloadRequest(opts, method, path, outPath, fallbackName) {
+  const url = opts.apiBase.replace(/\/$/, "") + path;
+  const headers = {};
+  if (opts.apiKey) headers[opts.apiKeyHeader ?? "X-Api-Key"] = opts.apiKey;
+  else headers.Authorization = `Bearer ${await bearer(opts.cfg)}`;
+  const res = await fetch(url, { method, headers });
+  if (!res.ok) {
+    const text = await res.text();
+    let parsed = void 0;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    throw apiErrorFrom(res.status, parsed, `Download failed (${res.status})`);
+  }
+  const serverName = dispositionFilename(res.headers.get("content-disposition"));
+  const safeName = serverName ? sanitizeFilename(serverName) : "";
+  const target = outPath ?? (safeName || void 0) ?? fallbackName;
+  if (!target) throw new ApiError(500, "No output filename (pass -o <file>)");
+  writeFileSync2(target, Buffer.from(await res.arrayBuffer()));
+  return target;
+}
 
 // src/core/output.ts
 function printJson(data) {
@@ -377,18 +448,104 @@ function registerAuth(program2) {
 }
 
 // src/commands/submissions.ts
+import { randomUUID } from "crypto";
 import { readFileSync as readFileSync2 } from "fs";
 import { basename } from "path";
+var POLICY_DOC_KINDS = ["binder", "policy", "declarations"];
+function intFlag(value, flag) {
+  if (!/^\d+$/.test(String(value).trim())) throw new Error(`${flag} expects a whole number, got "${value}"`);
+  return Number.parseInt(String(value).trim(), 10);
+}
+function readJsonBody(source) {
+  const raw = source === "-" ? readFileSync2(0, "utf8") : readFileSync2(source, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`--body is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("--body must be a JSON object");
+  return parsed;
+}
+function formatBytes(size) {
+  const n = Number(size);
+  if (!Number.isFinite(n) || n <= 0) return "";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
 function registerSubmissions(program2) {
-  program2.command("submit").description("Create a submission (does not market it \u2014 run `finalize` when ready)").requiredOption("--insured <name>", "insured business name").requiredOption("--narrative <text>", "operations description of the risk").option("--lob <slugs>", "comma-separated lines of business, e.g. commercial_general_liability,workers_compensation").option("--effective <date>", "effective date, YYYY-MM-DD").option("--state <ST>", "primary state (2-letter)").action(async (opts) => {
+  program2.command("submit").description("Create a submission (does not market it; run `finalize` when ready)").option("--insured <name>", "insured business name (required unless --body supplies applicant.insured_name)").option("--narrative <text>", "operations description of the risk (required unless --body supplies narrative)").option("--lob <slugs>", "comma-separated lines of business, e.g. commercial_general_liability,workers_compensation").option("--effective <date>", "effective date, YYYY-MM-DD").option("--state <ST>", "primary state (2-letter); with any address flag it becomes the mailing address state instead").option("--website <url>", "insured website").option("--fein <id>", "FEIN (or SSN for a sole proprietor)").option("--entity-type <type>", "legal entity type, e.g. llc, corporation").option("--naics <code>", "NAICS code").option("--business-phone <phone>", "insured business phone").option("--business-email <email>", "insured business email").option("--contact-first <name>", "primary contact first name").option("--contact-last <name>", "primary contact last name").option("--contact-email <email>", "primary contact email").option("--contact-phone <phone>", "primary contact phone").option("--address <line1>", "mailing address line 1").option("--address2 <line2>", "mailing address line 2").option("--city <city>", "mailing address city").option("--zip <zip>", "mailing address ZIP code").option("--tiv <int>", "total insured property value in dollars (property_tiv_total)").option("--vehicles <int>", "number of vehicles (auto_vehicle_count)").option("--payroll <int>", "total annual payroll in dollars (wc_total_annual_payroll)").option("--insured-id <uuid>", "start from an existing insured in your book").option("--producer-email <email>", "producing broker to attribute (required for brokerage API-client credentials)").option(
+    "--body <file|->",
+    "full JSON request body from a file, or - for stdin. Precedence: flags win; a top-level flag value replaces the matching body key, applicant flags merge over the body's applicant, and address flags merge into its mailing_address"
+  ).option(
+    "--idempotency-key <key>",
+    "Idempotency-Key header value (default: a random UUID per invocation). Re-send the same key within 24h to replay the original response instead of creating a duplicate"
+  ).action(async (opts) => {
     const ctx = makeCtx(program2.opts());
-    const body = {
-      applicant: { insured_name: opts.insured, ...opts.state ? { mailing_address: void 0 } : {} },
-      narrative: opts.narrative,
-      lines_of_business: opts.lob ? String(opts.lob).split(",").map((s) => s.trim()) : []
-    };
+    const body = opts.body ? readJsonBody(opts.body) : { lines_of_business: [] };
+    const applicant = {};
+    if (opts.insured) applicant.insured_name = opts.insured;
+    if (opts.businessPhone) applicant.business_phone = opts.businessPhone;
+    if (opts.businessEmail) applicant.business_email = opts.businessEmail;
+    if (opts.website) applicant.website = opts.website;
+    if (opts.fein) applicant.fein_or_ssn = opts.fein;
+    if (opts.entityType) applicant.entity_type = opts.entityType;
+    if (opts.naics) applicant.naics = opts.naics;
+    if (opts.contactFirst) applicant.contact_first_name = opts.contactFirst;
+    if (opts.contactLast) applicant.contact_last_name = opts.contactLast;
+    if (opts.contactEmail) applicant.contact_email = opts.contactEmail;
+    if (opts.contactPhone) applicant.contact_phone = opts.contactPhone;
+    const addressFlags = {};
+    if (opts.address) addressFlags.line1 = opts.address;
+    if (opts.address2) addressFlags.line2 = opts.address2;
+    if (opts.city) addressFlags.city = opts.city;
+    if (opts.zip) addressFlags.zip = opts.zip;
+    const hasAddressFlags = Object.keys(addressFlags).length > 0;
+    const state = opts.state ? String(opts.state).trim().toUpperCase() : void 0;
+    const bodyApplicant = body.applicant && typeof body.applicant === "object" && !Array.isArray(body.applicant) ? body.applicant : void 0;
+    const bodyAddress = bodyApplicant?.mailing_address && typeof bodyApplicant.mailing_address === "object" && !Array.isArray(bodyApplicant.mailing_address) ? bodyApplicant.mailing_address : void 0;
+    let mailing = bodyAddress ? { ...bodyAddress } : void 0;
+    if (hasAddressFlags) mailing = { ...mailing ?? {}, ...addressFlags };
+    if (state) {
+      if (mailing) {
+        mailing.state = state;
+        if (body.primary_state != null) body.primary_state = state;
+      } else {
+        body.primary_state = state;
+      }
+    }
+    if (hasAddressFlags) {
+      const flagFor = { line1: "--address", city: "--city", state: "--state", zip: "--zip" };
+      const missing = Object.keys(flagFor).filter((k) => !mailing?.[k]).map((k) => flagFor[k]);
+      if (missing.length) {
+        throw new Error(
+          "--address, --city, --state and --zip must be provided together (missing " + missing.join(", ") + "; fields already in --body's mailing_address count)"
+        );
+      }
+    }
+    if (mailing && (hasAddressFlags || state)) applicant.mailing_address = mailing;
+    if (Object.keys(applicant).length > 0) {
+      body.applicant = { ...bodyApplicant ?? {}, ...applicant };
+    }
+    if (opts.narrative) body.narrative = opts.narrative;
+    if (opts.lob) body.lines_of_business = String(opts.lob).split(",").map((s) => s.trim()).filter(Boolean);
     if (opts.effective) body.effective_date = opts.effective;
-    const res = await apiRequest(ctx.client, "POST", "/broker/submissions", { body });
+    if (opts.tiv != null) body.property_tiv_total = intFlag(opts.tiv, "--tiv");
+    if (opts.vehicles != null) body.auto_vehicle_count = intFlag(opts.vehicles, "--vehicles");
+    if (opts.payroll != null) body.wc_total_annual_payroll = intFlag(opts.payroll, "--payroll");
+    if (opts.insuredId) body.insured_id = opts.insuredId;
+    if (opts.producerEmail) body.producer_email = opts.producerEmail;
+    const finalApplicant = body.applicant;
+    if (!finalApplicant?.insured_name) throw new Error("--insured is required (or supply applicant.insured_name via --body)");
+    if (!body.narrative) throw new Error("--narrative is required (or supply narrative via --body)");
+    const res = await apiRequest(ctx.client, "POST", "/broker/submissions", {
+      body,
+      // Random per invocation unless the caller supplies a key. The API
+      // replays the original response when the same key is re-sent within
+      // 24h (per brokerage), so scripted retries should pass their own key.
+      headers: { "Idempotency-Key": opts.idempotencyKey ?? randomUUID() }
+    });
     if (ctx.json) return printJson(res);
     process.stdout.write(kv({ submission_id: res.submission_id, state: res.state, status: res.status_label }) + "\n");
     process.stdout.write("\nNext: hedge upload " + res.submission_id + " <file.pdf>, hedge requirements " + res.submission_id + ", hedge finalize " + res.submission_id + "\n");
@@ -414,6 +571,17 @@ function registerSubmissions(program2) {
         ready: m.ready ? "yes" : "no",
         needs_from_you: (m.needs_from_you || []).join("; ")
       })), ["market", "ready", "needs_from_you"]) + "\n");
+    } else {
+      const hint = typeof r.marketing_hint === "string" && r.marketing_hint ? r.marketing_hint : null;
+      if (r.marketing_status === "matching") {
+        process.stdout.write("\nNo markets yet - " + (hint ?? "Hedge is matching carrier markets now (usually ~5 minutes after finalize); re-run this in a few minutes.") + "\n");
+      } else if (r.marketing_status === "not_started") {
+        process.stdout.write("\nNo markets yet - " + (hint ?? "run hedge finalize " + submissionId + " to start marketing.") + "\n");
+      } else if (r.marketing_status === "no_markets_matched") {
+        process.stdout.write("\nNo markets attached - " + (hint ?? "Hedge is reviewing options for this risk and will follow up.") + "\n");
+      } else {
+        process.stdout.write("\nNo markets yet. If you just finalized, matching usually completes within ~5 minutes - re-run this shortly or use hedge status " + submissionId + ".\n");
+      }
     }
     if (r.carrier_api_sessions?.length) {
       process.stdout.write("\nInstant-quote carriers:\n" + table(r.carrier_api_sessions.map((s) => ({
@@ -429,12 +597,29 @@ function registerSubmissions(program2) {
     const ctx = makeCtx(program2.opts());
     const s = await apiRequest(ctx.client, "GET", `/broker/submissions/${submissionId}`);
     if (ctx.json) return printJson(s);
-    process.stdout.write(kv({ insured: s.insured_name, lines: (s.lines || []).join(", "), state: s.state, status: s.status_label, premium: s.premium }) + "\n");
+    process.stdout.write(kv({ insured: s.insured_name, lines: (s.lines || []).join(", "), state: s.state, status: s.status_label, premium: s.premium, effective: s.effective_date }) + "\n");
+    if (s.markets?.length) {
+      process.stdout.write("\nMarkets:\n" + table(s.markets.flatMap((m) => (m.lines || []).map((l) => ({
+        carrier: m.carrier_name,
+        line: l.lob_label ?? l.lob_slug,
+        status: l.status_label ?? l.status,
+        quote: l.quote_premium ?? ""
+      }))), ["carrier", "line", "status", "quote"]) + "\n");
+    } else {
+      process.stdout.write("\nNo markets attached yet. Matching usually completes within ~5 minutes of finalize - re-run this shortly (or check hedge requirements " + submissionId + ").\n");
+    }
+    const byStatus = s.status_summary?.by_status;
+    if (byStatus && Object.keys(byStatus).length) {
+      process.stdout.write("\nSummary: " + Object.entries(byStatus).map(([k, v]) => `${k}=${v}`).join(", ") + "\n");
+    }
+    if (s.documents?.length) {
+      process.stdout.write("\nDocuments: " + s.documents.map((d) => d.display_name).join(", ") + "\n");
+    }
   });
-  program2.command("submissions").description("List your brokerage's submissions").option("--status <state>", "filter by state").option("--search <q>", "filter by insured name").action(async (opts) => {
+  program2.command("submissions").description("List your brokerage's submissions").option("--status <state>", "filter by state").option("--search <q>", "filter by insured name").option("--limit <n>", "max rows to return (1-500)").option("--offset <n>", "skip the first n rows (for paging)").option("--updated-since <iso>", "only rows updated at or after this ISO timestamp").action(async (opts) => {
     const ctx = makeCtx(program2.opts());
     const rows = await apiRequest(ctx.client, "GET", "/broker/submissions", {
-      query: { status: opts.status, search: opts.search }
+      query: { status: opts.status, search: opts.search, limit: opts.limit, offset: opts.offset, updated_since: opts.updatedSince }
     });
     if (ctx.json) return printJson(rows);
     process.stdout.write(table(rows.map((r) => ({
@@ -445,27 +630,131 @@ function registerSubmissions(program2) {
       premium: r.premium ?? ""
     })), ["id", "insured", "lines", "status", "premium"]) + "\n");
   });
-  program2.command("finalize <submissionId>").description("Start marketing the submission to carriers").action(async (submissionId) => {
+  program2.command("finalize <submissionId>").description("Start marketing the submission to carriers").option("--wait", "poll until markets attach (usually ~5 minutes), then print them").option("--timeout <minutes>", "how long --wait polls before giving up", "8").action(async (submissionId, opts) => {
     const ctx = makeCtx(program2.opts());
     const r = await apiRequest(ctx.client, "POST", `/broker/submissions/${submissionId}/finalize`);
-    if (ctx.json) return printJson(r);
-    process.stdout.write("Marketing started. Track with: hedge status " + submissionId + "\n");
+    if (ctx.json && !opts.wait) return printJson(r);
+    if (!opts.wait) {
+      const wait = Number(r.typical_wait_seconds) > 0 ? Math.round(Number(r.typical_wait_seconds) / 60) : 5;
+      process.stdout.write(
+        `Marketing started. Markets usually attach within ~${wait} minutes.
+Track with: hedge status ${submissionId}  (or use finalize --wait next time)
+`
+      );
+      return;
+    }
+    const timeoutMin = intFlag(opts.timeout, "--timeout");
+    const deadline = Date.now() + Math.max(1, timeoutMin) * 6e4;
+    process.stdout.write("Marketing started - waiting for markets to attach (usually ~5 minutes)");
+    let markets = [];
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 15e3));
+      process.stdout.write(".");
+      const s = await apiRequest(ctx.client, "GET", `/broker/submissions/${submissionId}`);
+      if (s.markets?.length) {
+        markets = s.markets;
+        break;
+      }
+    }
+    process.stdout.write("\n");
+    if (!markets.length) {
+      process.stdout.write(
+        `Still matching after ${timeoutMin} minutes - this can occasionally take longer.
+Check in with: hedge status ${submissionId}  or  hedge requirements ${submissionId}
+`
+      );
+      return;
+    }
+    const rows = markets.flatMap((m) => (m.lines || []).map((l) => ({
+      carrier: m.carrier_name,
+      line: l.lob_label ?? l.lob_slug,
+      status: l.status_label ?? l.status
+    })));
+    if (ctx.json) return printJson({ finalize: r, markets });
+    process.stdout.write(`Matched ${markets.length} market(s):
+
+` + table(rows, ["carrier", "line", "status"]) + "\n");
+    process.stdout.write("\nNext: hedge requirements " + submissionId + " shows what each market still needs from you.\n");
+  });
+  program2.command("documents <submissionId>").description("List a submission's finalized documents (ACORDs, quotes, binders)").action(async (submissionId) => {
+    const ctx = makeCtx(program2.opts());
+    const rows = await apiRequest(ctx.client, "GET", `/broker/submissions/${submissionId}/finalized-documents`);
+    if (ctx.json) return printJson(rows);
+    process.stdout.write(table(rows.map((d) => ({
+      id: d.id,
+      name: d.display_name,
+      kind: d.source_label ?? d.source,
+      size: formatBytes(d.size_bytes ?? d.size),
+      added: String(d.created_at ?? "").slice(0, 10)
+    })), ["id", "name", "kind", "size", "added"]) + "\n");
+  });
+  program2.command("download <documentId>").description("Download a finalized document PDF").option("-o, --output <file>", "output file (default: the server's filename, else <documentId>.pdf)").action(async (documentId, opts) => {
+    const ctx = makeCtx(program2.opts());
+    const out = await downloadRequest(ctx.client, "GET", `/broker/finalized-documents/${documentId}/pdf`, opts.output, `${documentId}.pdf`);
+    process.stdout.write("Saved " + out + "\n");
   });
   program2.command("policies").description("List bound policies").action(async () => {
     const ctx = makeCtx(program2.opts());
     const rows = await apiRequest(ctx.client, "GET", "/broker/policies");
     if (ctx.json) return printJson(rows);
-    process.stdout.write(table(rows.map((r) => ({ insured: r.insured_name, carrier: r.carrier_name, policy: r.policy_number, premium: r.premium ?? "", status: r.status_label ?? r.status })), ["insured", "carrier", "policy", "premium", "status"]) + "\n");
+    process.stdout.write(table(rows.map((r) => ({
+      insured: r.insured_name,
+      carrier: r.carrier_name,
+      policy: r.policy_number,
+      premium: r.premium ?? "",
+      effective: r.effective_date ?? "",
+      expiration: r.expiration_date ?? "",
+      status: r.status_label ?? r.status
+    })), ["insured", "carrier", "policy", "premium", "effective", "expiration", "status"]) + "\n");
+  });
+  program2.command("policy <policyId>").description("Policy detail: term, premium, commission, payment plan, documents").action(async (policyId) => {
+    const ctx = makeCtx(program2.opts());
+    const p = await apiRequest(ctx.client, "GET", `/broker/policies/${policyId}`);
+    if (ctx.json) return printJson(p);
+    process.stdout.write(kv({
+      insured: p.insured_name,
+      policy: p.policy_number,
+      carrier: p.carrier_name,
+      lines: (p.lines || []).join(", "),
+      term: [p.effective_date, p.expiration_date].filter(Boolean).join(" to "),
+      net_premium: p.net_premium,
+      total_billed: p.total_billed,
+      commission_rate: p.commission_rate,
+      commission_amount: p.commission_amount,
+      payment_plan: p.payment_plan
+    }) + "\n");
+    if (p.documents?.length) {
+      process.stdout.write("\nDocuments: " + p.documents.map((d) => d.kind).join(", ") + "\n");
+      process.stdout.write("Download with: hedge policy-doc " + policyId + " <kind>\n");
+    }
+  });
+  program2.command("policy-doc <policyId> <kind>").description("Download a policy PDF; kind is one of binder, policy, declarations").option("-o, --output <file>", "output file (default <policyId>-<kind>.pdf)").action(async (policyId, kind, opts) => {
+    if (!POLICY_DOC_KINDS.includes(kind)) throw new Error(`kind must be one of ${POLICY_DOC_KINDS.join(", ")} (got "${kind}")`);
+    const ctx = makeCtx(program2.opts());
+    const out = await downloadRequest(ctx.client, "GET", `/broker/policies/${policyId}/document/${kind}`, opts.output ?? `${policyId}-${kind}.pdf`);
+    process.stdout.write("Saved " + out + "\n");
   });
   program2.command("payments").description("List payment / invoice status").action(async () => {
     const ctx = makeCtx(program2.opts());
     const rows = await apiRequest(ctx.client, "GET", "/broker/payments");
     if (ctx.json) return printJson(rows);
-    process.stdout.write(table(rows.map((r) => ({ insured: r.insured_name, status: r.status_label ?? r.status, premium: r.premium ?? "" })), ["insured", "status", "premium"]) + "\n");
+    process.stdout.write(table(rows.map((r) => ({
+      insured: r.insured_name,
+      status: r.status_label ?? r.status,
+      premium: r.premium ?? "",
+      invoice_url: r.invoice_url ?? ""
+    })), ["insured", "status", "premium", "invoice_url"]) + "\n");
   });
 }
 
 // src/commands/appetite.ts
+function requirementRows(items) {
+  return items.map((q) => ({
+    requirement: q.label + (q.conditional ? " (conditional)" : ""),
+    severity: q.severity,
+    provided_by: q.provided_by
+  }));
+}
 function registerAppetite(program2) {
   program2.command("appetite <class>").description('Which markets have appetite for a class, e.g. hedge appetite "roofing contractor" --state CA').option("--state <ST>", "2-letter state").option("--lob <slug>", "line of business filter").action(async (klass, opts) => {
     const ctx = makeCtx(program2.opts());
@@ -481,6 +770,38 @@ function registerAppetite(program2) {
     }));
     process.stdout.write(table(rows, ["market", "lines", "programs", "turnaround"]) + "\n");
   });
+  program2.command("market-requirements <marketId>").description("What a market needs to quote a line: the application package plus per-program requirements (market ids come from `hedge appetite --json`)").requiredOption("--lob <slug>", "line of business, e.g. commercial_general_liability").option("--state <ST>", "2-letter state").option("--programs <keys>", "comma-separated program keys (matched_program_keys from the appetite result) to narrow the panel").action(async (marketId, opts) => {
+    const ctx = makeCtx(program2.opts());
+    const r = await apiRequest(ctx.client, "GET", `/broker/markets/${marketId}/requirements`, {
+      query: { lob: opts.lob, state: opts.state, programs: opts.programs }
+    });
+    if (ctx.json) return printJson(r);
+    process.stdout.write(kv({
+      market: r.market_name,
+      line: r.lob?.label ?? r.lob?.slug,
+      state: r.state ?? "",
+      channel: r.market_channel
+    }) + "\n");
+    if (r.baseline?.length) {
+      process.stdout.write("\nApplication package (Hedge prepares these):\n" + table(requirementRows(r.baseline), ["requirement", "severity", "provided_by"]) + "\n");
+    }
+    for (const p of r.programs || []) {
+      const lines = (p.lines || []).map((l) => l.label ?? l.slug).join(", ");
+      process.stdout.write(`
+Program: ${p.display_name} [${p.channel}]${lines ? " (" + lines + ")" : ""}
+`);
+      if (p.has_authored_requirements && p.requirements?.length) {
+        process.stdout.write(table(requirementRows(p.requirements), ["requirement", "severity", "provided_by"]) + "\n");
+      } else {
+        process.stdout.write("Standard application package; no carrier-specific requirements.\n");
+      }
+    }
+    if (r.other_program_count) {
+      process.stdout.write(`
+${r.other_program_count} more program(s) use the standard package.
+`);
+    }
+  });
 }
 
 // src/commands/quotes.ts
@@ -512,21 +833,21 @@ function registerQuotes(program2) {
     process.stdout.write(`status: ${res.status} | remaining questions: ${(res.missing_required_questions_json || []).length}
 `);
   });
-  program2.command("request-quote <submissionId> <sessionId>").description("Close a carrier session \u2014 request an indication then a quote").action(async (submissionId, sessionId) => {
+  program2.command("request-quote <submissionId> <sessionId>").description("Close a carrier session and request an indication then a quote").action(async (submissionId, sessionId) => {
     const ctx = makeCtx(program2.opts());
     const res = await apiRequest(ctx.client, "POST", `/broker/submissions/${submissionId}/api-quotes/sessions/${sessionId}/close`);
     if (ctx.json) return printJson(res);
     process.stdout.write(`outcome: ${res.outcome} | status: ${res.status}${res.quote_pdf_url ? " | quote: " + res.quote_pdf_url : ""}
 `);
     if ((res.missing_required_questions_json || []).length)
-      process.stdout.write(`still needs ${(res.missing_required_questions_json || []).length} answers \u2014 use \`hedge answer\`
+      process.stdout.write(`still needs ${(res.missing_required_questions_json || []).length} answers; use \`hedge answer\`
 `);
   });
 }
 
 // src/index.ts
 var program = new Command();
-program.name("hedge").description("Submit risks to Hedge and track them from your terminal.").version("0.1.0").option("--staging", "use the staging environment").option("--json", "output raw JSON (for scripting)");
+program.name("hedge").description("Submit risks to Hedge and track them from your terminal.").version("0.3.0").option("--staging", "use the staging environment").option("--json", "output raw JSON (for scripting)");
 registerAuth(program);
 registerSubmissions(program);
 registerAppetite(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hedge-broker",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Command-line tool for the Hedge broker portal. Submit risks, check appetite, track quotes and policies.",
   "type": "module",
   "bin": { "hedge": "dist/index.js" },