@opsrev/acculynx-cli 1.2.0 → 1.4.0

package/README.md

@@ -84,6 +84,12 @@ acculynx unofficial messages list <jobId> --type Email # Filter by type: Comment
 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
@@ -106,6 +112,40 @@ acculynx unofficial messages post <jobId> "Check this out" --notify "userId1,use
 
 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

@@ -127,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 (default: 25)").option("--all", "Fetch all results (no limit)").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("--assignment <type>", "Filter by assignment: assigned, unassigned").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;
@@ -136,6 +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;
+    if (opts.assignment) params.assignment = opts.assignment;
     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));
@@ -764,6 +765,158 @@ function registerMessagesCommands(parentCmd, getClient2) {
   });
 }
 
+// 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;
@@ -795,6 +948,8 @@ function registerUnofficialCommands(parentCmd) {
   }
   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.2.0",
+  "version": "1.4.0",
   "description": "CLI for the AccuLynx roofing CRM API",
   "type": "module",
   "bin": {