@opsrev/acculynx-cli 1.1.0 → 1.3.0

package/README.md

@@ -30,7 +30,7 @@ API keys are created by your AccuLynx account administrator under Account Settin
 
 ### 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, dashboard, etc.).
+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 |
 |---------|------|-------------|
@@ -79,8 +79,73 @@ 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
+acculynx unofficial milestones list <jobId>            # List workflow milestones/statuses for a job
+acculynx unofficial milestones set <jobId> <status>    # Set a job's milestone/status by name
+acculynx unofficial milestones set <jobId> <status> --message "note"  # Set with comment
+acculynx unofficial jobs list                          # List jobs (unofficial)
+acculynx unofficial jobs list --status <name>           # Filter by workflow status name
+acculynx unofficial jobs list --milestone <name>        # Filter by milestone name
 ```
 
+#### 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`).
+
+#### Milestones
+
+AccuLynx workflows have milestones (Lead, Prospect, Approved, etc.) that contain custom statuses (Estimate Sent, Contract Signed, etc.). The official API only filters by top-level milestones. The unofficial milestones commands let you work with the granular workflow statuses.
+
+List all milestones and their statuses for a job:
+
+```bash
+acculynx unofficial milestones list <jobId>
+```
+
+Set a job to a specific workflow status by name (case-insensitive):
+
+```bash
+acculynx unofficial milestones set <jobId> "Estimate Sent"
+acculynx unofficial milestones set <jobId> "OpsRev: Estimate Ready for Review"
+acculynx unofficial milestones set <jobId> "Contract Signed" --message "Moving to contract phase"
+```
+
+If the status name doesn't match, the command returns the list of available statuses.
+
+#### Jobs (unofficial)
+
+The official `jobs list --milestones` filter only accepts top-level milestone names (Lead, Prospect, Approved, etc.). The unofficial `jobs list` command supports filtering by custom workflow status names.
+
+```bash
+acculynx unofficial jobs list --status "Estimate Sent"                    # jobs in a specific status
+acculynx unofficial jobs list --status "OpsRev: Estimate Ready for Review" # custom status names work
+acculynx unofficial jobs list --milestone Prospect                        # filter by milestone
+acculynx unofficial jobs list --status "Estimate Sent" --query "Smith"    # combine with search
+acculynx unofficial jobs list --sort "lastTouched|desc" --page 2          # sort and paginate
+```
+
+The `--status` flag resolves the status name (case-insensitive) to a GUID via the company workflow configuration, then queries the internal job list API. If the name doesn't match, the command returns the list of available statuses.
+
 **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

package/dist/index.js

@@ -260,6 +260,16 @@ var CookieJar = class _CookieJar {
     }
     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;
@@ -373,6 +383,36 @@ function createUnofficialClient(session) {
     }
     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, {
@@ -383,7 +423,7 @@ function createUnofficialClient(session) {
     }
     return Buffer.from(await resp.arrayBuffer());
   }
-  return { get: doGet, getBuffer: doGetBuffer };
+  return { get: doGet, post: doPost, getBuffer: doGetBuffer };
 }
 
 // src/unofficial/session.ts
@@ -605,6 +645,277 @@ function registerDocumentsCommands(parentCmd, getClient2) {
   });
 }
 
+// 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/milestones.ts
+function registerMilestonesCommands(parentCmd, getClient2) {
+  const milestones = parentCmd.command("milestones").description("Job milestone/status operations");
+  milestones.command("list").argument("<jobId>", "Job ID (GUID)").description("List all milestones and statuses for a job's workflow").action(async (jobId) => {
+    const data = await getClient2().get(
+      `/api/v3/job-workflows/${jobId}`
+    );
+    const result = data.Milestones.map((m) => ({
+      milestoneId: m.MilestoneId,
+      name: m.Name,
+      isCurrent: m.IsCurrent,
+      done: m.Done,
+      statuses: m.Statuses.map((s) => ({
+        statusId: s.StatusId,
+        name: s.Name.trim(),
+        isCurrent: s.IsCurrent,
+        done: s.Done
+      }))
+    }));
+    console.log(JSON.stringify(result));
+  });
+  milestones.command("set").argument("<jobId>", "Job ID (GUID)").argument("<statusName>", "Destination milestone/status name (case-insensitive)").option("--message <message>", "Optional comment when advancing", "").description("Set a job's milestone/status by name").action(async (jobId, statusName, opts) => {
+    const data = await getClient2().get(
+      `/api/v3/job-workflows/${jobId}`
+    );
+    const needle = statusName.toLowerCase().trim();
+    let matchedMilestoneId = null;
+    let matchedStatus = null;
+    for (const m of data.Milestones) {
+      if (m.Name.toLowerCase().trim() === needle) {
+        matchedMilestoneId = m.MilestoneId;
+        matchedStatus = m.Statuses[0] ?? null;
+        break;
+      }
+      for (const s of m.Statuses) {
+        if (s.Name.toLowerCase().trim() === needle) {
+          matchedMilestoneId = m.MilestoneId;
+          matchedStatus = s;
+          break;
+        }
+      }
+      if (matchedStatus) break;
+    }
+    if (!matchedMilestoneId || !matchedStatus) {
+      const available = data.Milestones.flatMap(
+        (m) => m.Statuses.map((s) => s.Name.trim())
+      );
+      console.error(
+        JSON.stringify({
+          error: `Status "${statusName}" not found`,
+          available
+        })
+      );
+      process.exitCode = 1;
+      return;
+    }
+    await getClient2().post(
+      `/api/v3/job-workflows/${jobId}/set-state`,
+      {
+        MilestoneId: matchedMilestoneId,
+        StatusId: matchedStatus.StatusId,
+        Message: opts.message
+      }
+    );
+    console.log(
+      JSON.stringify({
+        jobId,
+        milestoneId: matchedMilestoneId,
+        statusId: matchedStatus.StatusId,
+        statusName: matchedStatus.Name.trim(),
+        message: opts.message || null
+      })
+    );
+  });
+}
+
+// src/unofficial/commands/jobs.ts
+async function resolveStatusId(client, statusName) {
+  const workflow = await client.get(
+    "/api/v3/workflows"
+  );
+  const needle = statusName.toLowerCase().trim();
+  for (const m of workflow.Milestones) {
+    for (const s of m.Statuses) {
+      if (s.Name.toLowerCase().trim() === needle) {
+        return { statusId: s.StatusId, milestoneName: m.Name };
+      }
+    }
+  }
+  return null;
+}
+async function getAvailableStatuses(client) {
+  const workflow = await client.get(
+    "/api/v3/workflows"
+  );
+  return workflow.Milestones.flatMap(
+    (m) => m.Statuses.map((s) => s.Name.trim())
+  );
+}
+function registerUnofficialJobsCommands(parentCmd, getClient2) {
+  const jobs = parentCmd.command("jobs").description("Unofficial job search with workflow status filtering");
+  jobs.command("list").description("List jobs, optionally filtered by workflow status or milestone").option("--status <name>", "Filter by workflow status name (case-insensitive)").option("--milestone <name>", "Filter by milestone name (e.g. Prospect, Approved)").option("--query <text>", "Search term").option("--sort <field>", "Sort: milestoneStart|desc, lastTouched|desc, createdDate|desc", "milestoneStart|desc").option("--page <n>", "Page number", "1").action(async (opts) => {
+    const client = getClient2();
+    const params = new URLSearchParams();
+    if (opts.status) {
+      const resolved = await resolveStatusId(client, opts.status);
+      if (!resolved) {
+        const available = await getAvailableStatuses(client);
+        console.error(
+          JSON.stringify({
+            error: `Status "${opts.status}" not found`,
+            available
+          })
+        );
+        process.exitCode = 1;
+        return;
+      }
+      params.append("filters", `currentStatusId=${resolved.statusId}`);
+    }
+    if (opts.milestone) {
+      params.append("filters", `currentMilestoneList=${opts.milestone}`);
+    }
+    params.set("sort", opts.sort);
+    params.set("page", opts.page);
+    params.set("type", "2");
+    params.set("loadAll", "false");
+    if (opts.query) params.set("query", opts.query);
+    const data = await client.get(
+      `/api/joblist?${params.toString()}`
+    );
+    const result = {
+      totalRecords: data.TotalRecords,
+      currentPage: data.CurrentPage,
+      totalPages: data.TotalPages,
+      jobs: data.results.map((j) => ({
+        id: j.Id,
+        name: j.Name,
+        address: j.FullAddress,
+        cityState: j.CityState,
+        milestone: j.CurrentMilestone,
+        status: j.CurrentStatus,
+        salesPerson: j.SalesPerson,
+        createdDate: j.CreatedDate,
+        lastTouched: j.LastTouched,
+        workTypes: j.WorkTypes,
+        trades: j.Trades
+      }))
+    };
+    console.log(JSON.stringify(result));
+  });
+}
+
 // src/unofficial/commands/index.ts
 function getSessionFromEnv() {
   const email = process.env.ACCULYNX_EMAIL;
@@ -635,6 +946,9 @@ function registerUnofficialCommands(parentCmd) {
     return _client2;
   }
   registerDocumentsCommands(unofficial, getClient2);
+  registerMessagesCommands(unofficial, getClient2);
+  registerMilestonesCommands(unofficial, getClient2);
+  registerUnofficialJobsCommands(unofficial, getClient2);
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsrev/acculynx-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "CLI for the AccuLynx roofing CRM API",
   "type": "module",
   "bin": {
@@ -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",