@opsrev/acculynx-cli 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpsRev.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @opsrev/acculynx-cli
+
+[![CI](https://github.com/opsrev/acculynx-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/opsrev/acculynx-cli/actions/workflows/ci.yml)
+
+CLI for the AccuLynx roofing CRM API. Designed for AI agent consumption -- all output is JSON.
+
+## Installation
+
+```bash
+npm install -g @opsrev/acculynx-cli
+```
+
+## Configuration
+
+Copy the example env file and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+Your `.env` is gitignored and will never be committed.
+
+### Official API
+
+| Env Var | Flag | Description |
+|---------|------|-------------|
+| `ACCULYNX_API_KEY` | `--api-key` | AccuLynx API key (required) |
+
+API keys are created by your AccuLynx account administrator under Account Settings.
+
+### Unofficial Web API
+
+The `unofficial` commands use cookie-based authentication against AccuLynx's internal web APIs. These provide access to features not available in the official API (job documents, messages, etc.).
+
+| Env Var | Flag | Description |
+|---------|------|-------------|
+| `ACCULYNX_EMAIL` | `--email` | Your AccuLynx login email |
+| `ACCULYNX_PASSWORD` | `--password` | Your AccuLynx password |
+| `ACCULYNX_COMPANY_ID` | `--company-id` | Company GUID from location selector |
+
+> **Note:** These endpoints are reverse-engineered from the AccuLynx web app and may break without notice.
+
+## Commands
+
+```
+acculynx ping                                  # Health check / verify API key
+acculynx jobs list [--limit <n>] [--all]         # List jobs (default: 25 results)
+acculynx jobs get <jobId>                       # Get job details
+acculynx jobs create                            # Create a job (JSON from stdin)
+acculynx jobs search --query <text>             # Search jobs
+acculynx jobs contacts <jobId>                  # List job contacts
+acculynx jobs estimates <jobId>                 # List job estimates
+acculynx jobs financials <jobId>                # Get job financials
+acculynx jobs invoices <jobId>                  # List job invoices
+acculynx jobs milestones <jobId>                # List job milestone history
+acculynx jobs payments <jobId>                  # List job payments
+acculynx jobs history <jobId>                   # Get job change history
+acculynx contacts list [--limit <n>] [--all]    # List contacts (default: 25 results)
+acculynx contacts get <contactId>               # Get contact details
+acculynx contacts create                        # Create a contact (JSON from stdin)
+acculynx contacts search --query <text>         # Search contacts
+acculynx contacts emails <contactId>            # List contact email addresses
+acculynx contacts phones <contactId>            # List contact phone numbers
+acculynx estimates list [--limit <n>] [--all]   # List estimates (default: 25 results)
+acculynx estimates get <estimateId>             # Get estimate details
+acculynx estimates sections <estimateId>        # List sections for an estimate
+acculynx estimates section <estimateId> <secId> # Get section details
+acculynx estimates items <estimateId> <secId>   # List items in a section
+```
+
+### Unofficial commands
+
+Requires `ACCULYNX_EMAIL`, `ACCULYNX_PASSWORD`, and `ACCULYNX_COMPANY_ID` in your `.env` (or passed as flags).
+
+```
+acculynx unofficial companies                          # List available companies (discover your company ID)
+acculynx unofficial login                              # Authenticate and cache session
+acculynx unofficial logout                             # Remove cached session
+acculynx unofficial sessions                           # List cached sessions
+acculynx unofficial documents list <jobId>             # List all document folders/files for a job
+acculynx unofficial documents download <jobId> <fileId> [--output ./file.pdf]  # Download a document
+acculynx unofficial messages list <jobId>              # List all messages/comments for a job
+acculynx unofficial messages list <jobId> --type Email # Filter by type: Comment, Email, or Signatures
+acculynx unofficial messages list <jobId> --count-only # Get message count only
+acculynx unofficial messages post <jobId> <message>    # Post a comment to a job
+acculynx unofficial messages post <jobId> <message> --notify <userId,...>  # Post and notify users
+```
+
+#### Messages
+
+List all messages, comments, and emails on a job. HTML email content is automatically converted to lightweight markdown (headers, links, lists preserved; images and styles stripped) for clean AI agent consumption.
+
+```bash
+acculynx unofficial messages list <jobId>                          # all messages, newest first
+acculynx unofficial messages list <jobId> --sort "createdDate|asc" # oldest first
+acculynx unofficial messages list <jobId> --type Email             # only emails
+acculynx unofficial messages list <jobId> --count-only             # just the count
+```
+
+Post a comment to a job, optionally notifying (tagging) users:
+
+```bash
+acculynx unofficial messages post <jobId> "Your message here"
+acculynx unofficial messages post <jobId> "Check this out" --notify "userId1,userId2"
+```
+
+User IDs for `--notify` come from the official users API (`/api/v2/users`).
+
+**Getting started:** If you don't know your company ID, run `companies` first -- it logs in and returns all companies available to your account:
+
+```bash
+npm run dev -- unofficial companies
+# [{"id":"f104ba56-...","name":"My Roofing Co"},{"id":"7749e90f-...","name":"Sandbox"}]
+```
+
+Copy the `id` into your `.env` as `ACCULYNX_COMPANY_ID`, then run `login` to cache the session.
+
+Login caches session cookies to `~/.config/acculynx-cli/sessions/` so you only need to re-authenticate when the session expires. Multiple accounts/companies are supported -- each gets its own cached session.
+
+### Pagination
+
+All list commands default to **25 results**. Use `--limit <n>` for a custom count or `--all` to fetch everything:
+
+```bash
+acculynx jobs list                  # 25 results (default)
+acculynx jobs list --limit 100      # 100 results
+acculynx jobs list --all            # all results
+```
+
+### Jobs list filters
+
+- `--start-date <YYYY-MM-DD>` -- filter by start date
+- `--end-date <YYYY-MM-DD>` -- filter by end date
+- `--date-filter-type <type>` -- date field to filter on (default: CreatedDate)
+- `--milestones <milestones>` -- filter by milestones
+- `--sort-by <field>` -- CreatedDate, MilestoneDate, or ModifiedDate
+- `--sort-order <order>` -- Ascending or Descending
+- `--includes <fields>` -- contact, initialAppointment
+
+### Search
+
+```bash
+acculynx jobs search --query "smith"
+acculynx contacts search --query "smith"
+acculynx contacts search --query "smith" --sort-by LastName --sort-order Descending
+```
+
+### Stdin commands
+
+Commands that create resources accept JSON piped via stdin:
+
+```bash
+echo '{"name": "New Job"}' | acculynx jobs create
+```
+
+## Output
+
+All output is JSON to stdout. Errors are `{"error": "..."}` to stderr with exit code 1.
+
+```bash
+# Pipe to jq for pretty-printing
+acculynx jobs list --limit 5 | jq .
+
+# Use in scripts
+JOB_ID=$(acculynx jobs list --limit 1 | jq -r '.[0].id')
+acculynx jobs get "$JOB_ID" | jq .
+```
+
+## Development
+
+```bash
+cp .env.example .env  # fill in your credentials
+npm install
+npm test              # run unit tests
+npm run dev -- --help # run in dev mode (auto-loads .env)
+npm run build         # build to dist/
+./test-integration.sh # run integration tests (requires ACCULYNX_API_KEY)
+```
+
+The `npm run dev` script automatically loads your `.env` file via Node's `--env-file` flag (Node 20.6+). Examples:
+
+```bash
+npm run dev -- unofficial login
+npm run dev -- unofficial documents list <jobId>
+npm run dev -- jobs list --limit 5
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -84,7 +84,8 @@ function registerPingCommand(parentCmd, getClient2) {
 
 // src/api-helpers.ts
 var DEFAULT_PAGE_SIZE = 25;
-async function paginate(client, path, params, limit) {
+var DEFAULT_LIMIT = 25;
+async function paginate(client, path, params, limit = DEFAULT_LIMIT) {
   const results = [];
   let pageStartIndex = 0;
   while (true) {
@@ -95,7 +96,7 @@ async function paginate(client, path, params, limit) {
     };
     const data = await client.get(path, pageParams);
     results.push(...data.items);
-    if (limit && results.length >= limit) {
+    if (limit !== Infinity && results.length >= limit) {
       return results.slice(0, limit);
     }
     if (data.items.length < DEFAULT_PAGE_SIZE) {
@@ -126,7 +127,7 @@ async function readStdin(stream = process.stdin) {
 // src/commands/jobs.ts
 function registerJobsCommands(parentCmd, getClient2) {
   const jobs = parentCmd.command("jobs").description("Job operations");
-  jobs.command("list").description("List jobs (paginated)").option("--start-date <date>", "Start date (YYYY-MM-DD)").option("--end-date <date>", "End date (YYYY-MM-DD)").option("--date-filter-type <type>", "Date field to filter on").option("--milestones <milestones>", "Filter by milestones").option("--sort-by <field>", "Sort by: CreatedDate, MilestoneDate, ModifiedDate").option("--sort-order <order>", "Ascending or Descending").option("--includes <fields>", "Include: contact, initialAppointment").option("--limit <n>", "Max total results").action(async (opts) => {
+  jobs.command("list").description("List jobs (paginated)").option("--start-date <date>", "Start date (YYYY-MM-DD)").option("--end-date <date>", "End date (YYYY-MM-DD)").option("--date-filter-type <type>", "Date field to filter on").option("--milestones <milestones>", "Filter by milestones").option("--sort-by <field>", "Sort by: CreatedDate, MilestoneDate, ModifiedDate").option("--sort-order <order>", "Ascending or Descending").option("--includes <fields>", "Include: contact, initialAppointment").option("--limit <n>", "Max total results (default: 25)").option("--all", "Fetch all results (no limit)").action(async (opts) => {
     const params = {};
     if (opts.startDate) params.startDate = opts.startDate;
     if (opts.endDate) params.endDate = opts.endDate;
@@ -135,7 +136,7 @@ function registerJobsCommands(parentCmd, getClient2) {
     if (opts.sortBy) params.sortBy = opts.sortBy;
     if (opts.sortOrder) params.sortOrder = opts.sortOrder;
     if (opts.includes) params.includes = opts.includes;
-    const limit = opts.limit ? parseInt(opts.limit, 10) : void 0;
+    const limit = opts.all ? Infinity : opts.limit ? parseInt(opts.limit, 10) : void 0;
     const result = await paginate(getClient2(), "/jobs", params, limit);
     console.log(JSON.stringify(result));
   });
@@ -148,9 +149,10 @@ function registerJobsCommands(parentCmd, getClient2) {
     const result = await getClient2().post("/jobs", body);
     console.log(JSON.stringify(result));
   });
-  jobs.command("search").description("Search jobs (pipe JSON search criteria to stdin)").action(async () => {
-    const body = await readStdin();
-    const result = await getClient2().post("/jobs/search", body);
+  jobs.command("search").description("Search jobs").requiredOption("--query <text>", "Search term (required)").action(async (opts) => {
+    const result = await getClient2().post("/jobs/search", {
+      SearchTerm: opts.query
+    });
     console.log(JSON.stringify(result));
   });
   const subResources = [
@@ -173,8 +175,8 @@ function registerJobsCommands(parentCmd, getClient2) {
 // src/commands/contacts.ts
 function registerContactsCommands(parentCmd, getClient2) {
   const contacts = parentCmd.command("contacts").description("Contact operations");
-  contacts.command("list").description("List contacts (paginated)").option("--limit <n>", "Max total results").action(async (opts) => {
-    const limit = opts.limit ? parseInt(opts.limit, 10) : void 0;
+  contacts.command("list").description("List contacts (paginated)").option("--limit <n>", "Max total results (default: 25)").option("--all", "Fetch all results (no limit)").action(async (opts) => {
+    const limit = opts.all ? Infinity : opts.limit ? parseInt(opts.limit, 10) : void 0;
     const result = await paginate(getClient2(), "/contacts", {}, limit);
     console.log(JSON.stringify(result));
   });
@@ -187,9 +189,12 @@ function registerContactsCommands(parentCmd, getClient2) {
     const result = await getClient2().post("/contacts", body);
     console.log(JSON.stringify(result));
   });
-  contacts.command("search").description("Search contacts (pipe JSON search criteria to stdin)").action(async () => {
-    const body = await readStdin();
-    const result = await getClient2().post("/contacts/search", body);
+  contacts.command("search").description("Search contacts").requiredOption("--query <text>", "Search term (required)").option("--sort-by <field>", "Sort by field (default: LastName)", "LastName").option("--sort-order <order>", "Ascending or Descending (default: Ascending)", "Ascending").action(async (opts) => {
+    const result = await getClient2().post("/contacts/search", {
+      SearchTerm: opts.query,
+      SortBy: opts.sortBy,
+      SortOrder: opts.sortOrder
+    });
     console.log(JSON.stringify(result));
   });
   contacts.command("emails").argument("<contactId>", "Contact ID").description("List contact email addresses").action(async (contactId) => {
@@ -205,8 +210,8 @@ function registerContactsCommands(parentCmd, getClient2) {
 // src/commands/estimates.ts
 function registerEstimatesCommands(parentCmd, getClient2) {
   const estimates = parentCmd.command("estimates").description("Estimate operations");
-  estimates.command("list").description("List estimates (paginated)").option("--limit <n>", "Max total results").action(async (opts) => {
-    const limit = opts.limit ? parseInt(opts.limit, 10) : void 0;
+  estimates.command("list").description("List estimates (paginated)").option("--limit <n>", "Max total results (default: 25)").option("--all", "Fetch all results (no limit)").action(async (opts) => {
+    const limit = opts.all ? Infinity : opts.limit ? parseInt(opts.limit, 10) : void 0;
     const result = await paginate(getClient2(), "/estimates", {}, limit);
     console.log(JSON.stringify(result));
   });
@@ -228,11 +233,584 @@ function registerEstimatesCommands(parentCmd, getClient2) {
   });
 }
 
+// src/unofficial/session-store.ts
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  unlinkSync
+} from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// src/unofficial/cookie-jar.ts
+var CookieJar = class _CookieJar {
+  cookies = /* @__PURE__ */ new Map();
+  /** Extract and store cookies from a response's Set-Cookie headers. */
+  capture(url, response) {
+    const domain = new URL(url).hostname;
+    const jar = this.cookies.get(domain) ?? /* @__PURE__ */ new Map();
+    for (const header of response.headers.getSetCookie()) {
+      const [pair] = header.split(";");
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) continue;
+      jar.set(pair.slice(0, eqIdx).trim(), pair.slice(eqIdx + 1).trim());
+    }
+    this.cookies.set(domain, jar);
+  }
+  /** Get a specific cookie value by name for a given URL. */
+  getCookie(url, name) {
+    const domain = new URL(url).hostname;
+    for (const [d, jar] of this.cookies) {
+      if (domain === d || domain.endsWith("." + d)) {
+        if (jar.has(name)) return jar.get(name);
+      }
+    }
+    return void 0;
+  }
+  /** Build a Cookie header string for a given URL. */
+  headerFor(url) {
+    const domain = new URL(url).hostname;
+    const parts = [];
+    for (const [d, jar] of this.cookies) {
+      if (domain === d || domain.endsWith("." + d)) {
+        for (const [k, v] of jar) parts.push(`${k}=${v}`);
+      }
+    }
+    return parts.join("; ");
+  }
+  /** Serialize for disk caching. */
+  toJSON() {
+    const out = {};
+    for (const [d, jar] of this.cookies) {
+      out[d] = Object.fromEntries(jar);
+    }
+    return out;
+  }
+  /** Restore from disk cache. */
+  static fromJSON(data) {
+    const jar = new _CookieJar();
+    for (const [d, pairs] of Object.entries(data)) {
+      jar.cookies.set(d, new Map(Object.entries(pairs)));
+    }
+    return jar;
+  }
+};
+
+// src/unofficial/session-store.ts
+var CONFIG_DIR = join(
+  process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+  "acculynx-cli"
+);
+var SESSIONS_DIR = join(CONFIG_DIR, "sessions");
+function sessionKey(email, companyId) {
+  const slug = email.replace(/[@.]/g, "-").toLowerCase();
+  const prefix = companyId.slice(0, 8);
+  return `${slug}--${prefix}.json`;
+}
+function loadSession(email, companyId) {
+  const file = join(SESSIONS_DIR, sessionKey(email, companyId));
+  if (!existsSync(file)) return null;
+  try {
+    const data = JSON.parse(readFileSync(file, "utf-8"));
+    return {
+      jar: CookieJar.fromJSON(data.cookies),
+      companyId: data.companyId,
+      email: data.email
+    };
+  } catch {
+    return null;
+  }
+}
+function saveSession(session) {
+  mkdirSync(SESSIONS_DIR, { recursive: true, mode: 448 });
+  writeFileSync(
+    join(SESSIONS_DIR, sessionKey(session.email, session.companyId)),
+    JSON.stringify(
+      {
+        email: session.email,
+        companyId: session.companyId,
+        cookies: session.jar.toJSON()
+      },
+      null,
+      2
+    ),
+    { mode: 384 }
+  );
+}
+function deleteSession(email, companyId) {
+  const file = join(SESSIONS_DIR, sessionKey(email, companyId));
+  if (!existsSync(file)) return false;
+  unlinkSync(file);
+  return true;
+}
+function listSessions() {
+  if (!existsSync(SESSIONS_DIR)) return [];
+  return readdirSync(SESSIONS_DIR).filter((f) => f.endsWith(".json")).map((f) => {
+    try {
+      const data = JSON.parse(
+        readFileSync(join(SESSIONS_DIR, f), "utf-8")
+      );
+      return { email: data.email, companyId: data.companyId, file: f };
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+}
+
+// src/unofficial/unofficial-client.ts
+function createUnofficialClient(session) {
+  const base = "https://my.acculynx.com";
+  async function doGet(path) {
+    const url = `${base}${path}`;
+    const resp = await fetch(url, {
+      headers: {
+        Cookie: session.jar.headerFor(url),
+        Accept: "application/json"
+      }
+    });
+    if (resp.status === 401 || resp.status === 302) {
+      throw new Error(
+        "Session expired \u2014 run `acculynx unofficial login` to re-authenticate"
+      );
+    }
+    if (!resp.ok) {
+      throw new Error(
+        `Unofficial API error (${resp.status}): ${await resp.text()}`
+      );
+    }
+    return resp.json();
+  }
+  async function doPost(path, body) {
+    const url = `${base}${path}`;
+    const headers = {
+      Cookie: session.jar.headerFor(url),
+      Accept: "application/json",
+      "Content-Type": "application/json"
+    };
+    const xsrf = session.jar.getCookie(url, "XSRF-TOKEN");
+    if (xsrf) {
+      headers["X-XSRF-TOKEN"] = xsrf;
+    }
+    const resp = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    if (resp.status === 401 || resp.status === 302) {
+      throw new Error(
+        "Session expired \u2014 run `acculynx unofficial login` to re-authenticate"
+      );
+    }
+    if (!resp.ok) {
+      throw new Error(
+        `Unofficial API error (${resp.status}): ${await resp.text()}`
+      );
+    }
+    const text = await resp.text();
+    if (!text) return {};
+    return JSON.parse(text);
+  }
+  async function doGetBuffer(url) {
+    const fullUrl = url.startsWith("http") ? url : `${base}${url}`;
+    const resp = await fetch(fullUrl, {
+      headers: { Cookie: session.jar.headerFor(fullUrl) }
+    });
+    if (!resp.ok) {
+      throw new Error(`Download failed (${resp.status}): ${fullUrl}`);
+    }
+    return Buffer.from(await resp.arrayBuffer());
+  }
+  return { get: doGet, post: doPost, getBuffer: doGetBuffer };
+}
+
+// src/unofficial/session.ts
+async function fetchFollowingCookies(jar, url, init) {
+  let currentUrl = url;
+  let response;
+  for (let i = 0; i < 10; i++) {
+    response = await fetch(currentUrl, {
+      ...init,
+      redirect: "manual",
+      headers: {
+        ...Object.fromEntries(
+          Object.entries(init?.headers ?? {})
+        ),
+        Cookie: jar.headerFor(currentUrl)
+      }
+    });
+    jar.capture(currentUrl, response);
+    const location = response.headers.get("Location");
+    if (!location || response.status < 300 || response.status >= 400) {
+      return response;
+    }
+    currentUrl = new URL(location, currentUrl).href;
+    init = { redirect: "manual" };
+  }
+  throw new Error("Too many redirects");
+}
+async function authenticate(email, password) {
+  const jar = new CookieJar();
+  const signinResp = await fetchFollowingCookies(
+    jar,
+    "https://my.acculynx.com/signin/"
+  );
+  const html = await signinResp.text();
+  const actionMatch = html.match(/<form[^>]*action="([^"]*)"/);
+  if (!actionMatch) throw new Error("Could not find login form action");
+  const formAction = actionMatch[1].replace(/&amp;/g, "&");
+  const thumbprint = html.match(/name="DeviceThumbprint"[^>]*value="([^"]*)"/)?.[1] ?? "";
+  const deviceName = html.match(/name="DeviceName"[^>]*value="([^"]*)"/)?.[1] ?? "Node.js CLI";
+  const body = new URLSearchParams({
+    Email: email,
+    Password: password,
+    DeviceThumbprint: thumbprint,
+    DeviceName: deviceName
+  });
+  const loginResp = await fetchFollowingCookies(jar, formAction, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
+  });
+  const locationResp = await fetchFollowingCookies(
+    jar,
+    "https://my.acculynx.com/signin/LocationSelector"
+  );
+  const locationHtml = await locationResp.text();
+  return { jar, locationHtml };
+}
+async function listCompanies(email, password) {
+  const { locationHtml } = await authenticate(email, password);
+  const companyPattern = /SwitchCompany\?CompanyID=([0-9a-f-]+)"[^>]*>([^<]+)/gi;
+  const companies = [];
+  let match;
+  while ((match = companyPattern.exec(locationHtml)) !== null) {
+    companies.push({ id: match[1], name: match[2].trim() });
+  }
+  return companies;
+}
+async function login(email, password, companyId) {
+  const { jar } = await authenticate(email, password);
+  await fetchFollowingCookies(
+    jar,
+    `https://my.acculynx.com/signin/SwitchCompany?CompanyID=${companyId}`
+  );
+  return { jar, companyId, email };
+}
+
+// src/unofficial/commands/login.ts
+function getCredentials(opts) {
+  const email = opts.email ?? process.env.ACCULYNX_EMAIL;
+  const password = opts.password ?? process.env.ACCULYNX_PASSWORD;
+  const companyId = opts.companyId ?? process.env.ACCULYNX_COMPANY_ID;
+  if (!email) {
+    throw new Error(
+      "Missing email: pass --email or set ACCULYNX_EMAIL"
+    );
+  }
+  if (!password) {
+    throw new Error(
+      "Missing password: pass --password or set ACCULYNX_PASSWORD"
+    );
+  }
+  if (!companyId) {
+    throw new Error(
+      "Missing company ID: pass --company-id or set ACCULYNX_COMPANY_ID"
+    );
+  }
+  return { email, password, companyId };
+}
+function registerLoginCommands(parentCmd) {
+  parentCmd.command("login").description("Authenticate and cache session cookies").option("--email <email>", "AccuLynx email (env: ACCULYNX_EMAIL)").option(
+    "--password <password>",
+    "AccuLynx password (env: ACCULYNX_PASSWORD)"
+  ).option(
+    "--company-id <id>",
+    "Company GUID (env: ACCULYNX_COMPANY_ID)"
+  ).action(async (opts) => {
+    const { email, password, companyId } = getCredentials(opts);
+    const session = await login(email, password, companyId);
+    saveSession(session);
+    console.log(
+      JSON.stringify({
+        status: "ok",
+        email,
+        companyId,
+        message: "Session cached successfully"
+      })
+    );
+  });
+  parentCmd.command("companies").description(
+    "List available companies for your account (discovers company IDs)"
+  ).option("--email <email>", "AccuLynx email (env: ACCULYNX_EMAIL)").option(
+    "--password <password>",
+    "AccuLynx password (env: ACCULYNX_PASSWORD)"
+  ).action(async (opts) => {
+    const email = opts.email ?? process.env.ACCULYNX_EMAIL;
+    const password = opts.password ?? process.env.ACCULYNX_PASSWORD;
+    if (!email) {
+      throw new Error(
+        "Missing email: pass --email or set ACCULYNX_EMAIL"
+      );
+    }
+    if (!password) {
+      throw new Error(
+        "Missing password: pass --password or set ACCULYNX_PASSWORD"
+      );
+    }
+    const companies = await listCompanies(email, password);
+    console.log(JSON.stringify(companies));
+  });
+  parentCmd.command("sessions").description("List cached sessions").action(() => {
+    const sessions = listSessions();
+    console.log(JSON.stringify(sessions));
+  });
+  parentCmd.command("logout").description("Remove a cached session").option("--email <email>", "AccuLynx email (env: ACCULYNX_EMAIL)").option(
+    "--company-id <id>",
+    "Company GUID (env: ACCULYNX_COMPANY_ID)"
+  ).action((opts) => {
+    const email = opts.email ?? process.env.ACCULYNX_EMAIL;
+    const companyId = opts.companyId ?? process.env.ACCULYNX_COMPANY_ID;
+    if (!email || !companyId) {
+      throw new Error(
+        "Both --email and --company-id are required (or set env vars)"
+      );
+    }
+    const removed = deleteSession(email, companyId);
+    console.log(
+      JSON.stringify({
+        status: removed ? "removed" : "not_found",
+        email,
+        companyId
+      })
+    );
+  });
+}
+
+// src/unofficial/commands/documents.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+function registerDocumentsCommands(parentCmd, getClient2) {
+  const docs = parentCmd.command("documents").description("Job document operations");
+  docs.command("list").argument("<jobId>", "Job ID (GUID)").description("List all document folders and files for a job").action(async (jobId) => {
+    const folders = await getClient2().get(
+      `/api/v4/job-documents/${jobId}/job-document-folders`
+    );
+    const result = folders.map((folder) => ({
+      folder: folder.Name,
+      folderId: folder.Id,
+      fileCount: folder.FileCount,
+      files: folder.Files.map((f) => ({
+        id: f.Id,
+        name: f.Name,
+        extension: f.Extension,
+        size: f.Size,
+        mimeType: f.MIMEType,
+        href: f.Href,
+        createdBy: f.CreatedByDisplayName,
+        modifiedDate: f.ModifiedDateUTC
+      }))
+    }));
+    console.log(JSON.stringify(result));
+  });
+  docs.command("download").argument("<jobId>", "Job ID (GUID)").argument("<fileId>", "File ID (GUID)").option("--output <path>", "Write to file instead of stdout").description("Download a document file").action(async (jobId, fileId, opts) => {
+    const folders = await getClient2().get(
+      `/api/v4/job-documents/${jobId}/job-document-folders`
+    );
+    let targetFile;
+    for (const folder of folders) {
+      targetFile = folder.Files.find((f) => f.Id === fileId);
+      if (targetFile) break;
+    }
+    if (!targetFile) {
+      throw new Error(
+        `File ${fileId} not found in job ${jobId} documents`
+      );
+    }
+    const buffer = await getClient2().getBuffer(targetFile.Href);
+    if (opts.output) {
+      writeFileSync2(opts.output, buffer);
+      console.error(
+        JSON.stringify({
+          status: "ok",
+          file: targetFile.Name,
+          size: buffer.length,
+          output: opts.output
+        })
+      );
+    } else {
+      process.stdout.write(buffer);
+    }
+  });
+}
+
+// src/unofficial/commands/messages.ts
+import TurndownService from "turndown";
+function createTurndown() {
+  const td = new TurndownService({
+    headingStyle: "atx",
+    bulletListMarker: "-"
+  });
+  td.addRule("removeImages", {
+    filter: "img",
+    replacement: () => ""
+  });
+  td.addRule("removeStyle", {
+    filter: ["style", "script"],
+    replacement: () => ""
+  });
+  return td;
+}
+var looksLikeHtml = /<[a-z][\s\S]*?>/i;
+function cleanMessage(html) {
+  if (!looksLikeHtml.test(html)) return html;
+  const td = createTurndown();
+  return td.turndown(html).replace(/\n{3,}/g, "\n\n").trim();
+}
+function registerMessagesCommands(parentCmd, getClient2) {
+  const messages = parentCmd.command("messages").description("Job message/comment operations");
+  messages.command("list").argument("<jobId>", "Job ID (GUID)").option(
+    "--sort <sort>",
+    "Sort field and direction (field|asc or field|desc)",
+    "createdDate|desc"
+  ).option("--count-only", "Return only the total count of messages").option(
+    "--type <type>",
+    "Filter by message type: Comment, Email, or Signatures"
+  ).description("List all messages and comments for a job").action(async (jobId, opts) => {
+    const params = new URLSearchParams({ sort: opts.sort });
+    if (opts.countOnly) {
+      params.set("countOnly", "true");
+    }
+    if (opts.type) {
+      params.append("filters", `type=${opts.type}`);
+    }
+    const data = await getClient2().get(
+      `/api/jobs/${jobId}/JobMessageFeed?${params.toString()}`
+    );
+    if (opts.countOnly) {
+      console.log(JSON.stringify({ totalRecords: data.TotalRecords }));
+      return;
+    }
+    const result = {
+      totalRecords: data.TotalRecords,
+      currentPage: data.CurrentPage,
+      totalPages: data.TotalPages,
+      messages: data.results.map((msg) => ({
+        id: msg.id,
+        jobId: msg.JobId,
+        type: msg.Type,
+        messageType: msg.MessageType,
+        message: cleanMessage(msg.Message),
+        subject: msg.Subject,
+        createdBy: msg.CreatedBy,
+        createdById: msg.CreatedByID,
+        createdDate: msg.CreatedDate,
+        latestMessage: msg.LatestMessage,
+        parentMessageId: msg.ParentMessageId,
+        attachmentOnly: msg.AttachmentOnly,
+        replyEmail: msg.ReplyEmail,
+        sentDate: msg.SentDate,
+        recipients: msg.Recipients.map((r) => ({
+          id: r.id,
+          companyUserId: r.companyUserId,
+          sent: r.Sent,
+          sentDate: r.SentDate,
+          delivered: r.Delivered,
+          deliveredDate: r.DeliveredDate,
+          failed: r.Failed,
+          failedDate: r.FailedDate,
+          failedDescription: r.FailedDescription
+        })),
+        attachments: msg.Attachments,
+        childMessageCount: msg.ChildMessages.length,
+        childMessages: msg.ChildMessages.map((child) => ({
+          id: child.id,
+          type: child.Type,
+          message: cleanMessage(child.Message),
+          createdBy: child.CreatedBy,
+          createdDate: child.CreatedDate
+        }))
+      }))
+    };
+    console.log(JSON.stringify(result));
+  });
+  messages.command("post").argument("<jobId>", "Job ID (GUID)").argument("<message>", "Message text to post").option(
+    "--notify <userIds>",
+    "Comma-separated user IDs (GUIDs) to notify"
+  ).description("Post a comment/message to a job, optionally notifying users").action(async (jobId, message, opts) => {
+    const emailRecipients = opts.notify ? opts.notify.split(",").map((id) => id.trim()) : [];
+    const data = await getClient2().post(
+      `/api/jobs/${jobId}/Messages`,
+      {
+        JobId: jobId,
+        Message: message,
+        RoleId: "1111111",
+        MessageType: "General Comment",
+        emailRecipients,
+        index: -1
+      }
+    );
+    console.log(
+      JSON.stringify({
+        id: data.JobMessageId,
+        jobId: data.JobId,
+        message: data.Message,
+        messageType: data.MessageType,
+        createdDate: data.CreatedDate,
+        notified: emailRecipients.length
+      })
+    );
+  });
+}
+
+// src/unofficial/commands/index.ts
+function getSessionFromEnv() {
+  const email = process.env.ACCULYNX_EMAIL;
+  const companyId = process.env.ACCULYNX_COMPANY_ID;
+  if (!email || !companyId) {
+    throw new Error(
+      "Set ACCULYNX_EMAIL and ACCULYNX_COMPANY_ID (or run `acculynx unofficial login` first)"
+    );
+  }
+  const session = loadSession(email, companyId);
+  if (!session) {
+    throw new Error(
+      `No cached session for ${email} / ${companyId}. Run \`acculynx unofficial login\` first.`
+    );
+  }
+  return session;
+}
+function registerUnofficialCommands(parentCmd) {
+  const unofficial = parentCmd.command("unofficial").description(
+    "Unofficial web API commands (cookie-based auth, reverse-engineered)"
+  );
+  registerLoginCommands(unofficial);
+  let _client2 = null;
+  function getClient2() {
+    if (!_client2) {
+      _client2 = createUnofficialClient(getSessionFromEnv());
+    }
+    return _client2;
+  }
+  registerDocumentsCommands(unofficial, getClient2);
+  registerMessagesCommands(unofficial, getClient2);
+}
+
 // src/index.ts
 var program = new Command();
 program.name("acculynx").description("AccuLynx CRM CLI for AI agents").version("0.1.0").exitOverride().configureOutput({
   writeOut: (str) => process.stdout.write(str),
-  writeErr: (str) => process.stderr.write(JSON.stringify({ error: str.trim() }) + "\n")
+  writeErr: (str) => {
+    const trimmed = str.trim();
+    if (trimmed === "(outputHelp)") {
+      return;
+    } else if (trimmed.startsWith("Usage:") || trimmed.startsWith("error:")) {
+      process.stderr.write(str);
+    } else {
+      process.stderr.write(JSON.stringify({ error: trimmed }) + "\n");
+    }
+  }
 }).option("--api-key <key>", "AccuLynx API key (env: ACCULYNX_API_KEY)");
 var _client = null;
 function getConfigFromProgram() {
@@ -249,7 +827,11 @@ registerPingCommand(program, getClient);
 registerJobsCommands(program, getClient);
 registerContactsCommands(program, getClient);
 registerEstimatesCommands(program, getClient);
+registerUnofficialCommands(program);
 program.parseAsync().catch((err) => {
+  if (err.message === "(outputHelp)" || err.message === "(version)") {
+    return;
+  }
   console.error(JSON.stringify({ error: err.message }));
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsrev/acculynx-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "CLI for the AccuLynx roofing CRM API",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsx src/index.ts",
+    "dev": "tsx --env-file=.env src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build"
@@ -28,10 +28,12 @@
     "dist"
   ],
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "turndown": "^7.2.2"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",
+    "@types/turndown": "^5.0.6",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",