feat: add product to opportunity route, local product sequencing

- Add POST /v1/sales/opportunities/:identifier/products with field-level permission gating
- Add CWForecastItemCreate type for forecast item creation
- Store product display order locally (productSequence Int[] on Opportunity)
- Rewrite resequenceProducts to be local-only (no CW PUT, stable IDs)
- Remove reorderProducts CW util (PUT regenerated IDs & broke procurement)
- Update fetchProducts to apply local ordering with CW sequenceNumber fallback
- Add productSequence to OpportunityController.toJson()
- Update API_ROUTES.md, PERMISSIONS.md, PermissionNodes.ts

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

@@ -0,0 +1,69 @@
+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 { processObjectValuePerms } from "../../../modules/permission-utils/processObjectPermissions";
+import { z } from "zod";
+
+const productItemSchema = z
+  .object({
+    catalogItem: z.object({ id: z.number().int().positive() }).optional(),
+    forecastDescription: z.string().optional(),
+    productDescription: z.string().optional(),
+    quantity: z.number().positive().optional(),
+    status: z.object({ id: z.number().int().positive() }).optional(),
+    productClass: z.string().optional(),
+    forecastType: z.string().optional(),
+    revenue: z.number().optional(),
+    cost: z.number().optional(),
+    includeFlag: z.boolean().optional(),
+    linkFlag: z.boolean().optional(),
+    recurringFlag: z.boolean().optional(),
+    taxableFlag: z.boolean().optional(),
+    recurringRevenue: z.number().optional(),
+    recurringCost: z.number().optional(),
+    cycles: z.number().int().min(0).optional(),
+    sequenceNumber: z.number().int().min(0).optional(),
+  })
+  .strict();
+
+const addProductSchema = z.union([
+  productItemSchema,
+  z.array(productItemSchema).min(1, "At least one product is required"),
+]);
+
+/* POST /v1/sales/opportunities/:identifier/products */
+export default createRoute(
+  "post",
+  ["/opportunities/:identifier/products"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const body = await c.req.json();
+
+    const validated = addProductSchema.parse(body);
+    const inputItems = Array.isArray(validated) ? validated : [validated];
+
+    // Gate each submitted field against user permissions.
+    // Only fields the user has permission for are forwarded to ConnectWise.
+    const user = c.get("user");
+    const gatedItems = await Promise.all(
+      inputItems.map((item) =>
+        processObjectValuePerms(item, "sales.opportunity.product.field", user),
+      ),
+    );
+
+    const item = await opportunities.fetchItem(identifier);
+    const created = await item.addProducts(gatedItems);
+
+    const isBatch = Array.isArray(body);
+    const response = apiResponse.created(
+      isBatch
+        ? `${created.length} product(s) added to opportunity successfully!`
+        : "Product added to opportunity successfully!",
+      isBatch ? created.map((p) => p.toJson()) : created[0]!.toJson(),
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.product.add"] }),
+);

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

@@ -24,17 +24,10 @@ export default createRoute(
     const item = await opportunities.fetchItem(identifier);
     const updated = await item.resequenceProducts(orderedIds);
 
-    // Map original IDs to the new IDs returned by ConnectWise
-    const idMap: Record<number, number> = {};
-    for (let i = 0; i < orderedIds.length; i++) {
-      idMap[orderedIds[i]!] = updated[i]!.cwForecastId;
-    }
-
     const response = apiResponse.successful(
       "Product sequence updated successfully!",
       {
         products: updated.map((p) => p.toJson()),
-        idMap,
       },
     );
 

src/api/sales/index.ts

@@ -4,6 +4,7 @@ import { default as count } from "./count";
 import { default as fetch } from "./[id]/fetch";
 import { default as refresh } from "./[id]/refresh";
 import { default as products } from "./[id]/products";
+import { default as addProduct } from "./[id]/addProduct";
 import { default as resequenceProducts } from "./[id]/resequenceProducts";
 import { default as notes } from "./[id]/notes";
 import { default as fetchNote } from "./[id]/fetchNote";
@@ -13,6 +14,7 @@ import { default as deleteNote } from "./[id]/deleteNote";
 import { default as contacts } from "./[id]/contacts";
 
 export {
+  addProduct,
   count,
   fetch,
   fetchAll,