Add sales item labor/product route updates and permission docs

src/api/sales/[id]/addLabor.ts

@@ -0,0 +1,147 @@
+import { createRoute } from "../../../modules/api-utils/createRoute";
+import { opportunities } from "../../../managers/opportunities";
+import { procurement } from "../../../managers/procurement";
+import { apiResponse } from "../../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../../middleware/authorization";
+import { z } from "zod";
+
+const LABOR_DEFAULT_RATE = {
+  corporate: 100,
+  residential: 85,
+} as const;
+
+const roundMoney = (value: number) => Math.round(value * 100) / 100;
+
+const addLaborSchema = z
+  .object({
+    laborStyle: z.enum(["field", "tech"]),
+    customerType: z.enum(["corporate", "residential"]).optional(),
+    hours: z.number().positive().optional(),
+    rate: z.number().min(0).optional(),
+    ppu: z.number().min(0).optional(),
+    cpu: z.number().min(0).optional(),
+    taxable: z.boolean().optional(),
+    taxableFlag: z.boolean().optional(),
+    description: z.string().min(1).optional(),
+    customerDescription: z.string().min(1).optional(),
+    procurementNotes: z.string().optional(),
+    productNarrative: z.string().optional(),
+  })
+  .strict();
+
+/* POST /v1/sales/opportunities/:identifier/products/labor */
+export default createRoute(
+  "post",
+  ["/opportunities/:identifier/products/labor"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const body = await c.req.json();
+    const input = addLaborSchema.parse(body);
+
+    const laborCatalog = await procurement.fetchLaborCatalogItems();
+    const selectedCatalog =
+      input.laborStyle === "tech" ? laborCatalog.tech : laborCatalog.field;
+
+    const customerType = input.customerType ?? "corporate";
+    const defaultRate = LABOR_DEFAULT_RATE[customerType];
+    const quantity = input.hours ?? 1;
+    const ppu = input.ppu ?? input.rate ?? defaultRate;
+    const cpu = input.cpu ?? roundMoney(ppu * 0.5);
+    const taxableFlag =
+      input.taxable ?? input.taxableFlag ?? selectedCatalog.salesTaxable;
+
+    const makeCustomField = (
+      caption: string,
+      value: string,
+      fieldId: number,
+    ) => ({
+      id: fieldId,
+      caption,
+      type: "Text",
+      entryMethod: "EntryField",
+      value,
+    });
+
+    const payload = {
+      ...(input.procurementNotes || input.productNarrative
+        ? {
+            customFields: [
+              ...(input.procurementNotes
+                ? [
+                    makeCustomField(
+                      "Procurement Notes",
+                      input.procurementNotes,
+                      29,
+                    ),
+                  ]
+                : []),
+              ...(input.productNarrative
+                ? [
+                    makeCustomField(
+                      "Product Narrative",
+                      input.productNarrative,
+                      46,
+                    ),
+                  ]
+                : []),
+            ],
+          }
+        : {}),
+      catalogItem: { id: selectedCatalog.cwCatalogId },
+      description:
+        input.description ??
+        selectedCatalog.name ??
+        selectedCatalog.identifier ??
+        `${input.laborStyle.toUpperCase()} Labor`,
+      customerDescription: input.customerDescription,
+      quantity,
+      price: ppu,
+      cost: cpu,
+      taxableFlag,
+      dropshipFlag: false,
+      billableOption: "Billable",
+    };
+
+    const opportunity = await opportunities.fetchRecord(identifier);
+    const [created] = await opportunity.addProcurementProducts(payload);
+
+    const fields = Array.isArray(created?.customFields)
+      ? created.customFields
+      : [];
+    const procurementNotes =
+      fields.find((f: any) => f?.id === 29)?.value ?? null;
+    const productNarrative =
+      fields.find((f: any) => f?.id === 46)?.value ?? null;
+
+    const response = apiResponse.created(
+      "Labor added to opportunity successfully!",
+      {
+        id: created?.id ?? null,
+        forecastDetailId: created?.forecastDetailId ?? null,
+        laborStyle: input.laborStyle,
+        customerType,
+        catalogItem: {
+          id: selectedCatalog.cwCatalogId,
+          identifier: selectedCatalog.identifier,
+          name: selectedCatalog.name,
+        },
+        description: created?.description ?? payload.description,
+        customerDescription:
+          created?.customerDescription ?? input.customerDescription ?? null,
+        quantity: created?.quantity ?? quantity,
+        rate: ppu,
+        ppu,
+        cpu,
+        revenue: roundMoney((created?.quantity ?? quantity) * ppu),
+        cost: roundMoney((created?.quantity ?? quantity) * cpu),
+        taxableFlag: created?.taxableFlag ?? taxableFlag,
+        procurementNotes,
+        productNarrative,
+      },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.product.add.labor"] }),
+);

src/api/sales/[id]/cancelProduct.ts

@@ -0,0 +1,82 @@
+import { createRoute } from "../../../modules/api-utils/createRoute";
+import { opportunities } from "../../../managers/opportunities";
+import { apiResponse } from "../../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../../middleware/authorization";
+import GenericError from "../../../Errors/GenericError";
+import { z } from "zod";
+
+const cancelProductSchema = z
+  .object({
+    quantityCancelled: z.number().int().min(0),
+    cancellationReason: z.string().nullable().optional(),
+  })
+  .strict();
+
+/* PATCH /v1/sales/opportunities/:identifier/products/:productId/cancel */
+export default createRoute(
+  "patch",
+  ["/opportunities/:identifier/products/:productId/cancel"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const productId = Number(c.req.param("productId"));
+    const body = await c.req.json();
+
+    if (!Number.isInteger(productId) || productId <= 0) {
+      throw new GenericError({
+        status: 400,
+        name: "InvalidProductId",
+        message: "productId must be a positive integer",
+      });
+    }
+
+    const input = cancelProductSchema.parse(body);
+    const opportunity = await opportunities.fetchRecord(identifier);
+
+    const products = await opportunity.fetchProducts();
+    const product = products.find((item) => item.cwForecastId === productId);
+
+    if (!product) {
+      throw new GenericError({
+        status: 404,
+        name: "ForecastItemNotFound",
+        message: `Forecast item ${productId} not found on opportunity`,
+      });
+    }
+
+    const quantity = product.quantity ?? 0;
+    if (input.quantityCancelled > quantity) {
+      throw new GenericError({
+        status: 400,
+        name: "InvalidCancelledQuantity",
+        message: `quantityCancelled cannot exceed product quantity (${quantity})`,
+      });
+    }
+
+    await opportunity.setProductCancellation(productId, {
+      quantityCancelled: input.quantityCancelled,
+      cancellationReason: input.cancellationReason,
+    });
+
+    const refreshedProducts = await opportunity.fetchProducts({ fresh: true });
+    const updated = refreshedProducts.find((item) => item.cwForecastId === productId);
+
+    if (!updated) {
+      throw new GenericError({
+        status: 404,
+        name: "ForecastItemNotFound",
+        message: `Forecast item ${productId} not found on opportunity`,
+      });
+    }
+
+    const response = apiResponse.successful(
+      input.quantityCancelled === 0
+        ? "Product uncancelled successfully!"
+        : "Product cancellation updated successfully!",
+      updated.toJson(),
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.product.update"] }),
+);

src/api/sales/[id]/laborOptions.ts

@@ -0,0 +1,51 @@
+import { createRoute } from "../../../modules/api-utils/createRoute";
+import { opportunities } from "../../../managers/opportunities";
+import { procurement } from "../../../managers/procurement";
+import { apiResponse } from "../../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../../middleware/authorization";
+
+/* GET /v1/sales/opportunities/:identifier/products/labor/options */
+export default createRoute(
+  "get",
+  ["/opportunities/:identifier/products/labor/options"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+
+    await opportunities.fetchRecord(identifier);
+
+    const laborCatalog = await procurement.fetchLaborCatalogItems();
+
+    const response = apiResponse.successful(
+      "Labor product options fetched successfully!",
+      {
+        defaults: {
+          customerType: "corporate",
+          rates: {
+            corporate: 100,
+            residential: 85,
+          },
+          cpuMultiplier: 0.5,
+          quantity: 1,
+        },
+        options: {
+          field: {
+            cwCatalogId: laborCatalog.field.cwCatalogId,
+            identifier: laborCatalog.field.identifier,
+            name: laborCatalog.field.name,
+            taxableFlag: laborCatalog.field.salesTaxable,
+          },
+          tech: {
+            cwCatalogId: laborCatalog.tech.cwCatalogId,
+            identifier: laborCatalog.tech.identifier,
+            name: laborCatalog.tech.name,
+            taxableFlag: laborCatalog.tech.salesTaxable,
+          },
+        },
+      },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.product.add.labor"] }),
+);

src/api/sales/[id]/updateProduct.ts

@@ -0,0 +1,233 @@
+import { createRoute } from "../../../modules/api-utils/createRoute";
+import { opportunities } from "../../../managers/opportunities";
+import { apiResponse } from "../../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../../middleware/authorization";
+import GenericError from "../../../Errors/GenericError";
+import { z } from "zod";
+
+const PRODUCT_NARRATIVE_FIELD_ID = 46;
+const PROCUREMENT_NOTES_FIELD_ID = 29;
+
+const updateProductSchema = z
+  .object({
+    productDescription: z.string().min(1).optional(),
+    quantity: z.number().positive().optional(),
+    unitPrice: z.number().min(0).optional(),
+    unitCost: z.number().min(0).optional(),
+    customerDescription: z.string().nullable().optional(),
+    productNarrative: z.string().nullable().optional(),
+    procurementNotes: z.string().nullable().optional(),
+  })
+  .strict()
+  .refine(
+    (value) =>
+      Object.values(value).some(
+        (item) => item !== undefined && item !== null,
+      ),
+    "At least one editable field is required",
+  );
+
+const upsertCustomTextField = (
+  fields: Array<Record<string, unknown>>,
+  fieldId: number,
+  caption: string,
+  value: string,
+) => {
+  const next = [...fields];
+  const idx = next.findIndex((f) => Number(f.id) === fieldId);
+
+  const field = {
+    id: fieldId,
+    caption,
+    type: "Text",
+    entryMethod: "EntryField",
+    value,
+  };
+
+  if (idx === -1) {
+    next.push(field);
+    return next;
+  }
+
+  next[idx] = {
+    ...next[idx],
+    ...field,
+  };
+  return next;
+};
+
+/* PATCH /v1/sales/opportunities/:identifier/products/:productId/edit */
+export default createRoute(
+  "patch",
+  ["/opportunities/:identifier/products/:productId/edit"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const productId = Number(c.req.param("productId"));
+    const body = await c.req.json();
+
+    if (!Number.isInteger(productId) || productId <= 0) {
+      throw new GenericError({
+        status: 400,
+        name: "InvalidProductId",
+        message: "productId must be a positive integer",
+      });
+    }
+
+    const input = updateProductSchema.parse(body);
+    const opportunity = await opportunities.fetchRecord(identifier);
+
+    const forecastItems = await opportunity.fetchProducts();
+    const forecastItem = forecastItems.find(
+      (item) => item.cwForecastId === productId,
+    );
+
+    if (!forecastItem) {
+      throw new GenericError({
+        status: 404,
+        name: "ForecastItemNotFound",
+        message: `Forecast item ${productId} not found on opportunity`,
+      });
+    }
+
+    const forecastJson = forecastItem.toJson();
+    const effectiveQuantity = input.quantity ?? forecastJson.quantity ?? 1;
+
+    const forecastPatch: Record<string, unknown> = {};
+    if (input.productDescription !== undefined) {
+      forecastPatch.productDescription = input.productDescription;
+    }
+    if (input.quantity !== undefined) {
+      forecastPatch.quantity = input.quantity;
+    }
+    if (input.customerDescription !== undefined && input.customerDescription !== null) {
+      forecastPatch.customerDescription = input.customerDescription;
+    }
+    if (input.unitPrice !== undefined) {
+      forecastPatch.revenue = Number(
+        (input.unitPrice * effectiveQuantity).toFixed(2),
+      );
+    }
+    if (input.unitCost !== undefined) {
+      forecastPatch.cost = Number((input.unitCost * effectiveQuantity).toFixed(2));
+    }
+
+    const existingProcurement =
+      await opportunity.fetchProcurementProductByForecastItem(productId);
+
+    if (
+      (input.productNarrative !== undefined ||
+        input.procurementNotes !== undefined) &&
+      !existingProcurement
+    ) {
+      throw new GenericError({
+        status: 400,
+        name: "ProcurementLinkRequired",
+        message:
+          "Product Narrative and Procurement Notes can only be updated on products linked to a procurement record",
+      });
+    }
+
+    let updatedProcurement = existingProcurement;
+    if (existingProcurement) {
+      const procurementPatch: Record<string, unknown> = {};
+      if (input.productDescription !== undefined) {
+        procurementPatch.description = input.productDescription;
+      }
+      if (input.quantity !== undefined) {
+        procurementPatch.quantity = input.quantity;
+      }
+      if (input.unitPrice !== undefined) {
+        procurementPatch.price = input.unitPrice;
+      }
+      if (input.unitCost !== undefined) {
+        procurementPatch.cost = input.unitCost;
+      }
+      if (
+        input.customerDescription !== undefined &&
+        input.customerDescription !== null
+      ) {
+        procurementPatch.customerDescription = input.customerDescription;
+      }
+
+      const existingFields = Array.isArray(existingProcurement.customFields)
+        ? existingProcurement.customFields.map((field) => ({ ...field }))
+        : [];
+
+      let updatedFields = existingFields as Array<Record<string, unknown>>;
+      if (input.procurementNotes !== undefined && input.procurementNotes !== null) {
+        updatedFields = upsertCustomTextField(
+          updatedFields,
+          PROCUREMENT_NOTES_FIELD_ID,
+          "Procurement Notes",
+          input.procurementNotes,
+        );
+      }
+      if (input.productNarrative !== undefined && input.productNarrative !== null) {
+        updatedFields = upsertCustomTextField(
+          updatedFields,
+          PRODUCT_NARRATIVE_FIELD_ID,
+          "Product Narrative",
+          input.productNarrative,
+        );
+      }
+      if (
+        (input.procurementNotes !== undefined &&
+          input.procurementNotes !== null) ||
+        (input.productNarrative !== undefined &&
+          input.productNarrative !== null)
+      ) {
+        procurementPatch.customFields = updatedFields;
+      }
+
+      if (Object.keys(procurementPatch).length > 0) {
+        updatedProcurement =
+          await opportunity.updateProcurementProductByForecastItem(
+            productId,
+            procurementPatch,
+          );
+      }
+    }
+
+    let updatedForecast = forecastJson;
+    if (Object.keys(forecastPatch).length > 0) {
+      const patched = await opportunity.updateProduct(productId, forecastPatch);
+      updatedForecast = patched.toJson();
+    }
+
+    const updatedFields = Array.isArray(updatedProcurement?.customFields)
+      ? updatedProcurement.customFields
+      : [];
+    const procurementNotes =
+      updatedFields.find((field: any) => field?.id === PROCUREMENT_NOTES_FIELD_ID)
+        ?.value ?? null;
+    const productNarrative =
+      updatedFields.find((field: any) => field?.id === PRODUCT_NARRATIVE_FIELD_ID)
+        ?.value ?? null;
+
+    const quantity = updatedProcurement?.quantity ?? updatedForecast.quantity ?? null;
+    const unitPrice = updatedProcurement?.price ?? null;
+    const unitCost = updatedProcurement?.cost ?? null;
+
+    const response = apiResponse.successful(
+      "Product updated successfully!",
+      {
+        ...updatedForecast,
+        productDescription:
+          updatedProcurement?.description ?? updatedForecast.productDescription,
+        customerDescription:
+          updatedProcurement?.customerDescription ??
+          updatedForecast.customerDescription ??
+          null,
+        quantity,
+        unitPrice,
+        unitCost,
+        procurementNotes,
+        productNarrative,
+      },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.product.update"] }),
+);

src/api/sales/index.ts

@@ -6,7 +6,11 @@ import { default as refresh } from "./[id]/refresh";
 import { default as products } from "./[id]/products";
 import { default as addProduct } from "./[id]/addProduct";
 import { default as addSpecialOrderProduct } from "./[id]/addSpecialOrderProduct";
+import { default as addLabor } from "./[id]/addLabor";
+import { default as laborOptions } from "./[id]/laborOptions";
 import { default as resequenceProducts } from "./[id]/resequenceProducts";
+import { default as updateProduct } from "./[id]/updateProduct";
+import { default as cancelProduct } from "./[id]/cancelProduct";
 import { default as notes } from "./[id]/notes";
 import { default as fetchNote } from "./[id]/fetchNote";
 import { default as createNote } from "./[id]/createNote";
@@ -16,6 +20,8 @@ import { default as contacts } from "./[id]/contacts";
 
 export {
   addProduct,
+  addLabor,
+  laborOptions,
   addSpecialOrderProduct,
   count,
   fetch,
@@ -23,6 +29,8 @@ export {
   fetchOpportunityTypes,
   products,
   resequenceProducts,
+  updateProduct,
+  cancelProduct,
   notes,
   fetchNote,
   createNote,

src/controllers/OpportunityController.ts

@@ -782,6 +782,41 @@ export class OpportunityController {
     return this.fetchProducts();
   }
 
+  /**
+   * Append Product Sequence IDs
+   *
+   * Adds newly created forecast item IDs to the end of the local
+   * productSequence array, preserving existing order and avoiding duplicates.
+   */
+  private async appendProductSequenceIds(ids: number[]): Promise<void> {
+    const normalizedIds = ids.filter(
+      (id): id is number => Number.isInteger(id) && id > 0,
+    );
+    if (normalizedIds.length === 0) return;
+
+    const current = await prisma.opportunity.findUnique({
+      where: { id: this.id },
+      select: { productSequence: true },
+    });
+
+    const existing = current?.productSequence ?? [];
+    const existingSet = new Set(existing);
+    const idsToAppend = normalizedIds.filter((id) => !existingSet.has(id));
+    if (idsToAppend.length === 0) {
+      this.productSequence = existing;
+      return;
+    }
+
+    const updatedSequence = [...existing, ...idsToAppend];
+
+    await prisma.opportunity.update({
+      where: { id: this.id },
+      data: { productSequence: updatedSequence },
+    });
+
+    this.productSequence = updatedSequence;
+  }
+
   /**
    * Add Products
    *
@@ -800,6 +835,7 @@ export class OpportunityController {
         this.cwOpportunityId,
         data,
       );
+      await this.appendProductSequenceIds(created.map((item) => item.id));
       await invalidateProductsCache(this.cwOpportunityId);
       return created.map((item) => new ForecastProductController(item));
     } catch (err: any) {
@@ -845,6 +881,11 @@ export class OpportunityController {
       }));
 
       const created = await opportunityCw.createProcurementProducts(normalized);
+      await this.appendProductSequenceIds(
+        created
+          .map((item) => item.forecastDetailId)
+          .filter((id): id is number => typeof id === "number"),
+      );
       await invalidateProductsCache(this.cwOpportunityId);
       return created;
     } catch (err: any) {
@@ -873,6 +914,91 @@ export class OpportunityController {
     }
   }
 
+  /**
+   * Fetch Procurement Product By Forecast Item
+   *
+   * Returns the linked procurement product for a forecast item ID,
+   * or null when no procurement record exists.
+   */
+  public async fetchProcurementProductByForecastItem(
+    forecastItemId: number,
+  ): Promise<CWProcurementProduct | null> {
+    return opportunityCw.fetchProcurementProductByForecastDetail(
+      this.cwOpportunityId,
+      forecastItemId,
+    );
+  }
+
+  /**
+   * Update Procurement Product By Forecast Item
+   *
+   * Finds the linked procurement product for a forecast item and updates it.
+   * Returns null when no linked procurement product exists.
+   */
+  public async updateProcurementProductByForecastItem(
+    forecastItemId: number,
+    data: Record<string, unknown>,
+  ): Promise<CWProcurementProduct | null> {
+    const linked =
+      await this.fetchProcurementProductByForecastItem(forecastItemId);
+    if (!linked?.id) return null;
+
+    const updated = await opportunityCw.updateProcurementProduct(
+      linked.id,
+      data,
+    );
+    await invalidateProductsCache(this.cwOpportunityId);
+    return updated;
+  }
+
+  /**
+   * Set Product Cancellation
+   *
+   * Updates cancellation fields on the procurement product linked to a
+   * forecast item. A quantity of 0 is treated as uncancelled.
+   */
+  public async setProductCancellation(
+    forecastItemId: number,
+    opts: { quantityCancelled: number; cancellationReason?: string | null },
+  ): Promise<CWProcurementProduct> {
+    const linked =
+      await this.fetchProcurementProductByForecastItem(forecastItemId);
+
+    if (!linked?.id) {
+      throw new GenericError({
+        status: 404,
+        name: "ProcurementProductNotFound",
+        message:
+          "No linked procurement product found for the specified forecast item",
+      });
+    }
+
+    const quantityCancelled = Math.max(0, Math.trunc(opts.quantityCancelled));
+    const cancelledFlag = quantityCancelled > 0;
+
+    const updated = await this.updateProcurementProductByForecastItem(
+      forecastItemId,
+      {
+        quantityCancelled,
+        cancelledFlag,
+        cancelledReason: cancelledFlag
+          ? (opts.cancellationReason ?? null)
+          : null,
+      },
+    );
+
+    if (!updated) {
+      throw new GenericError({
+        status: 404,
+        name: "ProcurementProductNotFound",
+        message:
+          "No linked procurement product found for the specified forecast item",
+      });
+    }
+
+    return updated;
+  }
+
   /**
    * Add Note
    *
@@ -938,7 +1064,7 @@ export class OpportunityController {
       id: this.id,
       cwOpportunityId: this.cwOpportunityId,
       name: this.name,
-      notes: this.notes,
+      description: this.notes,
       type: this.typeCwId ? { id: this.typeCwId, name: this.typeName } : null,
       stage: this.stageCwId
         ? { id: this.stageCwId, name: this.stageName }

src/managers/procurement.ts

@@ -17,6 +17,61 @@ const catalogItemInclude = {
   linkedItems: true,
 } as const;
 
+const LABOR_STYLE_CANDIDATES = {
+  field: ["LABOR & INSTALLATION - FIELD", "LABOR - FIELD", "LABOR FIELD"],
+  tech: ["LABOR & INSTALLATION - TECH", "LABOR - TECH", "LABOR TECH"],
+} as const;
+
+async function findCatalogByExactCandidates(
+  candidates: readonly string[],
+): Promise<CatalogItemController | null> {
+  for (const candidate of candidates) {
+    const item = await prisma.catalogItem.findFirst({
+      where: {
+        inactive: false,
+        OR: [
+          { identifier: { equals: candidate, mode: "insensitive" } },
+          { name: { equals: candidate, mode: "insensitive" } },
+        ],
+      },
+      include: catalogItemInclude,
+    });
+
+    if (item) return new CatalogItemController(item);
+  }
+
+  return null;
+}
+
+async function findCatalogByLaborStyle(
+  style: "field" | "tech",
+): Promise<CatalogItemController | null> {
+  const fallback = await prisma.catalogItem.findFirst({
+    where: {
+      inactive: false,
+      AND: [
+        {
+          OR: [
+            { identifier: { contains: "labor", mode: "insensitive" } },
+            { name: { contains: "labor", mode: "insensitive" } },
+          ],
+        },
+        {
+          OR: [
+            { identifier: { contains: style, mode: "insensitive" } },
+            { name: { contains: style, mode: "insensitive" } },
+          ],
+        },
+      ],
+    },
+    include: catalogItemInclude,
+    orderBy: { name: "asc" },
+  });
+
+  if (!fallback) return null;
+  return new CatalogItemController(fallback);
+}
+
 /**
  * Filter options for catalog item queries.
  */
@@ -204,6 +259,36 @@ export const procurement = {
     return new CatalogItemController(item);
   },
 
+  /**
+   * Fetch Labor Catalog Items
+   *
+   * Resolves canonical Field and Tech labor products from the local catalog.
+   * Prefers exact identifier/name matches, then falls back to keyword matching.
+   */
+  async fetchLaborCatalogItems(): Promise<{
+    field: CatalogItemController;
+    tech: CatalogItemController;
+  }> {
+    const fieldItem =
+      (await findCatalogByExactCandidates(LABOR_STYLE_CANDIDATES.field)) ??
+      (await findCatalogByLaborStyle("field"));
+    const techItem =
+      (await findCatalogByExactCandidates(LABOR_STYLE_CANDIDATES.tech)) ??
+      (await findCatalogByLaborStyle("tech"));
+
+    if (!fieldItem || !techItem) {
+      throw new GenericError({
+        message: "Labor catalog products are not configured",
+        name: "LaborCatalogProductsNotFound",
+        cause:
+          "Expected active FIELD and TECH labor catalog items in the local catalog",
+        status: 500,
+      });
+    }
+
+    return { field: fieldItem, tech: techItem };
+  },
+
   /**
    * Fetch All Catalog Items (Paginated)
    *

src/modules/cw-utils/opportunities/opportunities.ts

@@ -381,4 +381,45 @@ export const opportunityCw = {
 
     return created;
   },
+
+  /**
+   * Fetch Procurement Product by Forecast Detail
+   *
+   * Finds the procurement product linked to a given forecast item ID
+   * on an opportunity.
+   */
+  fetchProcurementProductByForecastDetail: async (
+    opportunityId: number,
+    forecastDetailId: number,
+  ): Promise<CWProcurementProduct | null> => {
+    const conditions = `opportunity/id=${opportunityId} and forecastDetailId=${forecastDetailId}`;
+    const response = await connectWiseApi.get(
+      `/procurement/products?conditions=${encodeURIComponent(conditions)}&fields=id,forecastDetailId,description,customerDescription,quantity,price,cost,taxableFlag,specialOrderFlag,customFields`,
+    );
+
+    const items = (response.data ?? []) as CWProcurementProduct[];
+    return items[0] ?? null;
+  },
+
+  /**
+   * Update Procurement Product
+   *
+   * Applies a JSON Patch update to a procurement product record.
+   */
+  updateProcurementProduct: async (
+    procurementProductId: number,
+    data: Record<string, unknown>,
+  ): Promise<CWProcurementProduct> => {
+    const operations = Object.entries(data).map(([key, value]) => ({
+      op: "replace" as const,
+      path: key,
+      value,
+    }));
+
+    const response = await connectWiseApi.patch(
+      `/procurement/products/${procurementProductId}`,
+      operations,
+    );
+    return response.data as CWProcurementProduct;
+  },
 };

src/types/PermissionNodes.ts

@@ -444,7 +444,11 @@ export const PERMISSION_NODES = {
         node: "sales.opportunity.product.update",
         description:
           "Update products (forecast items) on an opportunity, including resequencing",
-        usedIn: ["src/api/sales/[id]/resequenceProducts.ts"],
+        usedIn: [
+          "src/api/sales/[id]/resequenceProducts.ts",
+          "src/api/sales/[id]/updateProduct.ts",
+          "src/api/sales/[id]/cancelProduct.ts",
+        ],
         dependencies: ["sales.opportunity.fetch"],
       },
       {
@@ -480,6 +484,16 @@ export const PERMISSION_NODES = {
         usedIn: ["src/api/sales/[id]/addSpecialOrderProduct.ts"],
         dependencies: ["sales.opportunity.fetch"],
       },
+      {
+        node: "sales.opportunity.product.add.labor",
+        description:
+          "Add labor products to an opportunity using the dedicated labor route with Field/Tech catalog selection and pricing inputs.",
+        usedIn: [
+          "src/api/sales/[id]/addLabor.ts",
+          "src/api/sales/[id]/laborOptions.ts",
+        ],
+        dependencies: ["sales.opportunity.fetch"],
+      },
     ],
   },