perf: cache-only strategy for list views, cache-then-cw for single fetch

- Add data-source hierarchy to opportunity manager (cache-only, cache-then-cw, cw-first)
- fetchPages/search/fetchByCompany use cache-only: Redis → DB (no CW calls)
- fetchItem uses cache-then-cw by default, cw-first when fresh=true
- Add idleTimeout: 255 to Bun.serve to prevent request timeouts
- Map CW status 57 (04. Confirmed Quote) to Active equivalency
- Add computeCacheTTL algorithm and opportunityCache module

.github/copilot-instructions.md

@@ -24,9 +24,10 @@ Keep each layer focused:
 
 ## Runtime / tooling
 
-The project runs on **Bun**. DB tooling uses **Prisma**; the generated client lives under `generated/prisma` (do NOT edit generated files). Key scripts in `package.json`:
+The project runs on **Bun** exclusively — **always use `bun` commands, never `npm`, `npx`, or `yarn`**. DB tooling uses **Prisma**; the generated client lives under `generated/prisma` (do NOT edit generated files). Test preloads are configured in `bunfig.toml` so bare `bun test` works. Key scripts in `package.json`:
 
 - `dev` — `NODE_ENV=development bun --watch src/index.ts` (start dev server with hot reload)
+- `test` — `bun test` (runs all tests with preload from `bunfig.toml`)
 - `db:gen` — `prisma generate`
 - `db:push` — `prisma migrate dev --skip-generate`
 - `utils:dev` — `docker compose -f .docker/docker-compose.yml up --build`
@@ -36,7 +37,7 @@ The project runs on **Bun**. DB tooling uses **Prisma**; the generated client li
 
 ## Data layer
 
-Prisma schema is at `prisma/schema.prisma`. The app imports the generated Prisma client from `generated/prisma/client.ts` (or `generated/prisma/browser.ts` for browser type contexts). The shared `prisma` instance is exported from `src/constants.ts`. Always run `npm run db:gen` after updating `schema.prisma`.
+Prisma schema is at `prisma/schema.prisma`. The app imports the generated Prisma client from `generated/prisma/client.ts` (or `generated/prisma/browser.ts` for browser type contexts). The shared `prisma` instance is exported from `src/constants.ts`. Always run `bun run db:gen` after updating `schema.prisma`.
 
 ## Shared constants (`src/constants.ts`)
 
@@ -174,13 +175,14 @@ The `UnifiClient` class in `src/modules/unifi-api/UnifiClient.ts` wraps all UniF
 
 ## Local dev / quick checks
 
-- Start dev server: `npm run dev`
+- Start dev server: `bun run dev`
-- Regenerate Prisma client: `npm run db:gen`
+- Run tests: `bun test`
-- Apply DB migrations locally: `npm run db:push`
+- Regenerate Prisma client: `bun run db:gen`
-- Docker dev utilities: `npm run utils:dev`
+- Apply DB migrations locally: `bun run db:push`
-- Generate private keys: `npm run utils:gen_private_keys`
+- Docker dev utilities: `bun run utils:dev`
-- Create admin role: `npm run utils:create_admin_role`
+- Generate private keys: `bun run utils:gen_private_keys`
-- Assign user role: `npm run utils:assign_user_role`
+- Create admin role: `bun run utils:create_admin_role`
+- Assign user role: `bun run utils:assign_user_role`
 
 ## When editing generated or infra files
 

Opportunity Activity.md

@@ -0,0 +1,148 @@
+setInternalReview - The quote is ready to be review before it is ready to be sent.
+setInternalApproved - The quote has been approved and is ready to be sent out.
+setQuoteSent - The Quote has been sent to the customer.
+setQuoteConfirmed - The quote has been recieved by the customer.
+setRevisionNeeded - The quote needs to be revised and is set to stage revision
+setFinalized - This locks any non-admins from modifying the quote saying that is the final iteration of the quote.
+convert - This converts the quote to a ticket. It will also update all the necessary fields.
+
+addTime(activityId, user: string)
+
+fetchProducts
+updateProduct
+addProduct
+
+fetchNotes
+addNotes(note: string, user: string)
+
+# Cat/SubCat/Bucket
+
+## Ecosystems vs Categories
+
+## Ecosystem Tree
+
+- Networking
+  - Manufacturer: Ubiquiti
+    - Category: Technology
+    - Subcategory: Network-\*
+  - Manufacturer: TP-Link
+    - Category: Technology
+    - Subcategory: Network-\*
+- Video Surveillance
+  - Manufacturer: Uniview
+    - Category: Field
+    - Subcategory: Surveillance-\*
+  - Manufacturer: Hikvision
+    - Category: Field
+    - Subcategory: Surveillance-\*
+  - Manufacturer: Alarm.com
+    - Category: Field
+    - Subcategory: Surveillance-\*
+- Burg/Alarm
+  - Manufacturer: Qolsys
+    - Category: Field
+    - Subcategory: AlarmBurg-\*
+  - DSC
+    - Category: Field
+    - Subcategory: AlarmBurg-\*
+
+## Category Tree
+
+- Technology
+  - GeneralEquip
+  - Home Entertainment
+  - Monitor
+  - Printers
+  - Storage
+  - Network
+    - Network-Other
+    - Network-Router
+    - Network-Switch
+    - Network-Wireless
+  - Computer
+    - Computer-Components
+    - Computer-Desktop
+    - Computer-Laptop
+  - Recurring
+    - Recurring - Online
+    - Recurring - Other
+    - Recurring - Protection
+    - Recurring - Telephone
+  - Telephone
+    - Tele-HSet-Digital
+    - Tele-HSet-IP
+    - Tele-HSet-SLT
+    - Tele-Misc
+    - Tele-Paging
+    - Tele-SystemCards
+    - Tele-Systems
+- General
+  - Batteries
+  - Battery Backups
+  - BulkWire
+  - Cables
+    - Cables-Adapters
+    - Cables-HDMI
+    - Cables-Network
+    - Cables-Other
+    - Cables-USB
+    - Cables-VGA
+  - Elec Cords & Adapters
+  - Enclosures
+  - PowerSupply
+  - RackEquip
+    - RackEquip-Rack
+    - RackEquip-Shelves
+- Field
+  - Conduit
+  - Electric
+  - GateControl
+  - Locksets
+  - Other
+  - Relays
+  - AccessControl
+    - AccessControl-Controllers
+    - AccessControl-Credential
+    - AccessControl-LockDevices
+    - AccessControl-Other
+    - AccessControl-Readers
+    - AccessControl-VideoEntry
+  - AlarmBurg
+    - AlarmBurg-Communicators
+    - AlarmBurg-Keypads
+    - AlarmBurg-Modules
+    - AlarmBurg-Other
+    - AlarmBurg-Panels
+    - AlarmBurg-Sensors
+      - AlarmBurg-Sensors-Wireless
+      - AlarmBurg-Sensors-Wired
+    - AlarmBurg-Siren
+  - AlarmFire
+    - AlarmFire-Communicators
+    - AlarmFire-Devices
+    - AlarmFire-Modules
+    - AlarmFire-Other
+    - AlarmFire-Panels
+    - AlarmFire-Sensors
+  - Automation
+    - Automation-General
+    - Automation-HVAC
+    - Automation-Lights
+    - Automation-Locks
+    - Automation-Thermostat
+  - AV
+    - AV-Adapters&Cables
+    - AV-Components
+    - AV-Mounts
+    - AV-Other
+    - AV-Speakers
+    - AV-Television
+  - StrCbl?
+    - StrCbl-Jacks
+    - StrCbl-PatchPanel
+    - StrCbl-Plates
+  - Surveillance
+    - Surveillance-Accs
+    - Surveillance-CamerasAnalog
+    - Surveillance-CamerasIP
+    - Surveillance-NVR

PERMISSIONS.md

@@ -117,22 +117,54 @@ Admin-specific UI permissions that control visibility and data loading for admin
 
 ### Procurement Permissions
 
-| Permission Node                         | Description                                                   | Used In                                                                                                                                        | Dependencies                |
+| Permission Node                         | Description                                                                  | Used In                                                                                                                                                                                                                                                                    | Dependencies                |
-| --------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| --------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
-| `procurement.catalog.fetch`             | Fetch a single catalog item                                   | [src/api/procurement/[id]/fetch.ts](src/api/procurement/[id]/fetch.ts)                                                                         |                             |
+| `procurement.catalog.fetch`             | Fetch a single catalog item                                                  | [src/api/procurement/[id]/fetch.ts](src/api/procurement/[id]/fetch.ts)                                                                                                                                                                                                     |                             |
-| `procurement.catalog.fetch.many`        | Fetch multiple catalog items or count                         | [src/api/procurement/fetchAll.ts](src/api/procurement/fetchAll.ts), [src/api/procurement/count.ts](src/api/procurement/count.ts)               |                             |
+| `procurement.catalog.fetch.many`        | Fetch multiple catalog items, count, categories/ecosystems, or filter values | [src/api/procurement/fetchAll.ts](src/api/procurement/fetchAll.ts), [src/api/procurement/count.ts](src/api/procurement/count.ts), [src/api/procurement/categories.ts](src/api/procurement/categories.ts), [src/api/procurement/filters.ts](src/api/procurement/filters.ts) |                             |
-| `procurement.catalog.inventory.refresh` | Refresh on-hand inventory for a catalog item from ConnectWise | [src/api/procurement/[id]/refreshInventory.ts](src/api/procurement/[id]/refreshInventory.ts)                                                   | `procurement.catalog.fetch` |
+| `procurement.catalog.inventory.refresh` | Refresh on-hand inventory for a catalog item from ConnectWise                | [src/api/procurement/[id]/refreshInventory.ts](src/api/procurement/[id]/refreshInventory.ts)                                                                                                                                                                               | `procurement.catalog.fetch` |
-| `procurement.catalog.link`              | Link or unlink catalog items to each other                    | [src/api/procurement/[id]/link.ts](src/api/procurement/[id]/link.ts), [src/api/procurement/[id]/unlink.ts](src/api/procurement/[id]/unlink.ts) | `procurement.catalog.fetch` |
+| `procurement.catalog.link`              | Link or unlink catalog items to each other                                   | [src/api/procurement/[id]/link.ts](src/api/procurement/[id]/link.ts), [src/api/procurement/[id]/unlink.ts](src/api/procurement/[id]/unlink.ts)                                                                                                                             | `procurement.catalog.fetch` |
 
 ### Sales Permissions
 
-Permissions for accessing and managing sales opportunities. Opportunities are synced from ConnectWise and stored locally; sub-resources (forecasts, notes, contacts) are fetched live from CW.
+Permissions for accessing and managing sales opportunities. Opportunities are synced from ConnectWise and stored locally; sub-resources (products, notes, contacts) are fetched live from CW.
 
-| Permission Node                | Description                                                                      | Used In                                                                                                                                                                                                                                                      | Dependencies              |
+| Permission Node                    | Description                                                                                                                            | Used In                                                                                                                                                                                                                                                                                                                        | Dependencies              |
-| ------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
-| `sales.opportunity.fetch`      | Fetch a single opportunity and its CW sub-resources (forecasts, notes, contacts) | [src/api/sales/[id]/fetch.ts](src/api/sales/[id]/fetch.ts), [src/api/sales/[id]/forecasts.ts](src/api/sales/[id]/forecasts.ts), [src/api/sales/[id]/notes.ts](src/api/sales/[id]/notes.ts), [src/api/sales/[id]/contacts.ts](src/api/sales/[id]/contacts.ts) |                           |
+| `sales.opportunity.fetch`          | Fetch a single opportunity and its CW sub-resources (products, notes, contacts)                                                        | [src/api/sales/[id]/fetch.ts](src/api/sales/[id]/fetch.ts), [src/api/sales/[id]/products.ts](src/api/sales/[id]/products.ts), [src/api/sales/[id]/notes.ts](src/api/sales/[id]/notes.ts), [src/api/sales/[id]/fetchNote.ts](src/api/sales/[id]/fetchNote.ts), [src/api/sales/[id]/contacts.ts](src/api/sales/[id]/contacts.ts) |                           |
-| `sales.opportunity.fetch.many` | Fetch multiple opportunities (paginated/searchable) or get opportunity count     | [src/api/sales/fetchAll.ts](src/api/sales/fetchAll.ts), [src/api/sales/count.ts](src/api/sales/count.ts)                                                                                                                                                     |                           |
+| `sales.opportunity.fetch.many`     | Fetch multiple opportunities (paginated/searchable), count, or opportunity types                                                       | [src/api/sales/fetchAll.ts](src/api/sales/fetchAll.ts), [src/api/sales/count.ts](src/api/sales/count.ts), [src/api/sales/fetchOpportunityTypes.ts](src/api/sales/fetchOpportunityTypes.ts)                                                                                                                                     |                           |
-| `sales.opportunity.refresh`    | Refresh a single opportunity's local data from ConnectWise                       | [src/api/sales/[id]/refresh.ts](src/api/sales/[id]/refresh.ts)                                                                                                                                                                                               | `sales.opportunity.fetch` |
+| `sales.opportunity.refresh`        | Refresh a single opportunity's local data from ConnectWise                                                                             | [src/api/sales/[id]/refresh.ts](src/api/sales/[id]/refresh.ts)                                                                                                                                                                                                                                                                 | `sales.opportunity.fetch` |
+| `sales.opportunity.note.create`    | Create a new note on an opportunity                                                                                                    | [src/api/sales/[id]/createNote.ts](src/api/sales/[id]/createNote.ts)                                                                                                                                                                                                                                                           | `sales.opportunity.fetch` |
+| `sales.opportunity.note.update`    | Update an existing note on an opportunity                                                                                              | [src/api/sales/[id]/updateNote.ts](src/api/sales/[id]/updateNote.ts)                                                                                                                                                                                                                                                           | `sales.opportunity.fetch` |
+| `sales.opportunity.note.delete`    | Delete a note from an opportunity                                                                                                      | [src/api/sales/[id]/deleteNote.ts](src/api/sales/[id]/deleteNote.ts)                                                                                                                                                                                                                                                           | `sales.opportunity.fetch` |
+| `sales.opportunity.product.update` | Update products (forecast items) on an opportunity, including resequencing                                                             | [src/api/sales/[id]/resequenceProducts.ts](src/api/sales/[id]/resequenceProducts.ts)                                                                                                                                                                                                                                           | `sales.opportunity.fetch` |
+| `sales.opportunity.product.add`    | Add a new product (forecast item) to an opportunity. Individual fields gated by `sales.opportunity.product.field.<field>` permissions. | [src/api/sales/[id]/addProduct.ts](src/api/sales/[id]/addProduct.ts)                                                                                                                                                                                                                                                           | `sales.opportunity.fetch` |
+
+<details>
+<summary><strong>Field-level permissions for <code>sales.opportunity.product.add</code></strong></summary>
+
+Each submitted field is gated by a `sales.opportunity.product.field.<field>` permission node. Only fields the user has permission for are forwarded to ConnectWise.
+
+| Field Permission Node                                 | Description                                              |
+| ----------------------------------------------------- | -------------------------------------------------------- |
+| `sales.opportunity.product.field.catalogItem`         | Set the catalog item reference                           |
+| `sales.opportunity.product.field.forecastDescription` | Set the forecast description                             |
+| `sales.opportunity.product.field.productDescription`  | Set the product description                              |
+| `sales.opportunity.product.field.quantity`            | Set the quantity                                         |
+| `sales.opportunity.product.field.status`              | Set the status reference                                 |
+| `sales.opportunity.product.field.productClass`        | Set the product class (e.g. Product, Service, Agreement) |
+| `sales.opportunity.product.field.forecastType`        | Set the forecast type                                    |
+| `sales.opportunity.product.field.revenue`             | Set the revenue amount                                   |
+| `sales.opportunity.product.field.cost`                | Set the cost amount                                      |
+| `sales.opportunity.product.field.includeFlag`         | Set the include flag                                     |
+| `sales.opportunity.product.field.linkFlag`            | Set the link flag                                        |
+| `sales.opportunity.product.field.recurringFlag`       | Set the recurring flag                                   |
+| `sales.opportunity.product.field.taxableFlag`         | Set the taxable flag                                     |
+| `sales.opportunity.product.field.recurringRevenue`    | Set the recurring revenue amount                         |
+| `sales.opportunity.product.field.recurringCost`       | Set the recurring cost amount                            |
+| `sales.opportunity.product.field.cycles`              | Set the number of recurring cycles                       |
+| `sales.opportunity.product.field.sequenceNumber`      | Set the sequence number (display order)                  |
+
+</details>
 
 ### UniFi Permissions
 
@@ -171,6 +203,177 @@ The WiFi fetch route uses `processObjectValuePerms` to filter each WLAN object o
 | `unifi.site.wifi.ppsk` | View private pre-shared keys (PPSKs) for a specific WiFi network | [src/api/unifi/site/wifi/ppskFetchAll.ts](src/api/unifi/site/wifi/ppskFetchAll.ts), [src/api/unifi/site/wifi/ppskCreate.ts](src/api/unifi/site/wifi/ppskCreate.ts) | `unifi.access`, `unifi.site.wifi` |
 | `unifi.site.wifi.ppsk.create` | Create a private pre-shared key on a specific WiFi network | [src/api/unifi/site/wifi/ppskCreate.ts](src/api/unifi/site/wifi/ppskCreate.ts) | `unifi.access`, `unifi.site.wifi`, `unifi.site.wifi.ppsk` |
 
+---
+
+## Object Type Permissions (Field-Level Gating)
+
+All fetch and fetchAll routes gate response object keys using `processObjectValuePerms`. For each object type, only fields whose corresponding `<scope>.<field>` permission the user holds are included in the response. Grant `<scope>.*` to allow all fields on that object type.
+
+### Company (`obj.company`)
+
+| Field Permission            | Description                               |
+| --------------------------- | ----------------------------------------- |
+| `obj.company.id`            | View company ID                           |
+| `obj.company.name`          | View company name                         |
+| `obj.company.cw_Identifier` | View ConnectWise identifier               |
+| `obj.company.cw_CompanyId`  | View ConnectWise company ID               |
+| `obj.company.cw_Data`       | View ConnectWise data (address, contacts) |
+| `obj.company.createdAt`     | View creation timestamp                   |
+| `obj.company.updatedAt`     | View last-updated timestamp               |
+
+**Used in:** [src/api/companies/[id]/fetch.ts](src/api/companies/[id]/fetch.ts), [src/api/companies/fetchAll.ts](src/api/companies/fetchAll.ts)
+
+### Credential (`obj.credential`)
+
+| Field Permission                   | Description                   |
+| ---------------------------------- | ----------------------------- |
+| `obj.credential.id`                | View credential ID            |
+| `obj.credential.name`              | View credential name          |
+| `obj.credential.notes`             | View credential notes         |
+| `obj.credential.typeId`            | View credential type ID       |
+| `obj.credential.companyId`         | View linked company ID        |
+| `obj.credential.subCredentialOfId` | View parent credential ID     |
+| `obj.credential.fields`            | View credential field values  |
+| `obj.credential.type`              | View credential type object   |
+| `obj.credential.company`           | View linked company object    |
+| `obj.credential.subCredentials`    | View sub-credentials array    |
+| `obj.credential.secureFieldIds`    | View secure field identifiers |
+| `obj.credential.createdAt`         | View creation timestamp       |
+| `obj.credential.updatedAt`         | View last-updated timestamp   |
+
+**Used in:** [src/api/credentials/fetch.ts](src/api/credentials/fetch.ts), [src/api/credentials/fetchByCompany.ts](src/api/credentials/fetchByCompany.ts), [src/api/credentials/fetchSubCredentials.ts](src/api/credentials/fetchSubCredentials.ts), [src/api/credential-types/fetchCredentials.ts](src/api/credential-types/fetchCredentials.ts)
+
+### Credential Type (`obj.credentialType`)
+
+| Field Permission                     | Description                               |
+| ------------------------------------ | ----------------------------------------- |
+| `obj.credentialType.id`              | View credential type ID                   |
+| `obj.credentialType.name`            | View credential type name                 |
+| `obj.credentialType.permissionScope` | View permission scope                     |
+| `obj.credentialType.icon`            | View icon                                 |
+| `obj.credentialType.fields`          | View field definitions                    |
+| `obj.credentialType.credentialCount` | View count of credentials using this type |
+| `obj.credentialType.createdAt`       | View creation timestamp                   |
+| `obj.credentialType.updatedAt`       | View last-updated timestamp               |
+
+**Used in:** [src/api/credential-types/fetch.ts](src/api/credential-types/fetch.ts), [src/api/credential-types/fetchAll.ts](src/api/credential-types/fetchAll.ts)
+
+### User (`obj.user`)
+
+| Field Permission       | Description                      |
+| ---------------------- | -------------------------------- |
+| `obj.user.id`          | View user ID                     |
+| `obj.user.name`        | View user display name           |
+| `obj.user.roles`       | View assigned role monikers      |
+| `obj.user.permissions` | View aggregated permission nodes |
+| `obj.user.login`       | View login identifier            |
+| `obj.user.email`       | View email address               |
+| `obj.user.image`       | View profile image URL           |
+| `obj.user.createdAt`   | View creation timestamp          |
+| `obj.user.updatedAt`   | View last-updated timestamp      |
+
+**Used in:** [src/api/user/@me/fetch.ts](src/api/user/@me/fetch.ts), [src/api/user/fetch.ts](src/api/user/fetch.ts), [src/api/user/fetchAll.ts](src/api/user/fetchAll.ts), [src/api/roles/getUsers.ts](src/api/roles/getUsers.ts)
+
+### Role (`obj.role`)
+
+| Field Permission       | Description                      |
+| ---------------------- | -------------------------------- |
+| `obj.role.id`          | View role ID                     |
+| `obj.role.title`       | View role title                  |
+| `obj.role.moniker`     | View role moniker                |
+| `obj.role.permissions` | View role permission nodes       |
+| `obj.role.users`       | View users assigned to this role |
+| `obj.role.createdAt`   | View creation timestamp          |
+| `obj.role.updatedAt`   | View last-updated timestamp      |
+
+**Used in:** [src/api/roles/fetch.ts](src/api/roles/fetch.ts), [src/api/roles/fetchAll.ts](src/api/roles/fetchAll.ts), [src/api/user/fetchRoles.ts](src/api/user/fetchRoles.ts)
+
+### Catalog Item (`obj.catalogItem`)
+
+| Field Permission                      | Description                      |
+| ------------------------------------- | -------------------------------- |
+| `obj.catalogItem.id`                  | View catalog item ID             |
+| `obj.catalogItem.cwCatalogId`         | View ConnectWise catalog ID      |
+| `obj.catalogItem.identifier`          | View item identifier             |
+| `obj.catalogItem.name`                | View item name                   |
+| `obj.catalogItem.description`         | View description                 |
+| `obj.catalogItem.customerDescription` | View customer-facing description |
+| `obj.catalogItem.internalNotes`       | View internal notes              |
+| `obj.catalogItem.manufacturer`        | View manufacturer name           |
+| `obj.catalogItem.manufactureCwId`     | View manufacturer ConnectWise ID |
+| `obj.catalogItem.partNumber`          | View part number                 |
+| `obj.catalogItem.vendorName`          | View vendor name                 |
+| `obj.catalogItem.vendorSku`           | View vendor SKU                  |
+| `obj.catalogItem.vendorCwId`          | View vendor ConnectWise ID       |
+| `obj.catalogItem.price`               | View price                       |
+| `obj.catalogItem.cost`                | View cost                        |
+| `obj.catalogItem.inactive`            | View inactive flag               |
+| `obj.catalogItem.salesTaxable`        | View sales-taxable flag          |
+| `obj.catalogItem.onHand`              | View on-hand inventory count     |
+| `obj.catalogItem.cwLastUpdated`       | View CW last-updated timestamp   |
+| `obj.catalogItem.linkedItems`         | View linked catalog items        |
+| `obj.catalogItem.createdAt`           | View creation timestamp          |
+| `obj.catalogItem.updatedAt`           | View last-updated timestamp      |
+
+**Used in:** [src/api/procurement/fetchAll.ts](src/api/procurement/fetchAll.ts), [src/api/procurement/[id]/fetch.ts](src/api/procurement/[id]/fetch.ts), [src/api/procurement/[id]/fetchLinked.ts](src/api/procurement/[id]/fetchLinked.ts)
+
+### Opportunity (`obj.opportunity`)
+
+| Field Permission                     | Description                     |
+| ------------------------------------ | ------------------------------- |
+| `obj.opportunity.id`                 | View opportunity ID             |
+| `obj.opportunity.cwOpportunityId`    | View ConnectWise opportunity ID |
+| `obj.opportunity.name`               | View opportunity name           |
+| `obj.opportunity.notes`              | View notes                      |
+| `obj.opportunity.type`               | View opportunity type           |
+| `obj.opportunity.stage`              | View stage                      |
+| `obj.opportunity.status`             | View status                     |
+| `obj.opportunity.priority`           | View priority                   |
+| `obj.opportunity.rating`             | View rating                     |
+| `obj.opportunity.source`             | View source                     |
+| `obj.opportunity.campaign`           | View campaign                   |
+| `obj.opportunity.primarySalesRep`    | View primary sales rep          |
+| `obj.opportunity.secondarySalesRep`  | View secondary sales rep        |
+| `obj.opportunity.company`            | View company                    |
+| `obj.opportunity.contact`            | View contact                    |
+| `obj.opportunity.site`               | View site                       |
+| `obj.opportunity.customerPO`         | View customer PO                |
+| `obj.opportunity.totalSalesTax`      | View total sales tax            |
+| `obj.opportunity.location`           | View location                   |
+| `obj.opportunity.department`         | View department                 |
+| `obj.opportunity.expectedCloseDate`  | View expected close date        |
+| `obj.opportunity.pipelineChangeDate` | View pipeline change date       |
+| `obj.opportunity.dateBecameLead`     | View date became lead           |
+| `obj.opportunity.closedDate`         | View closed date                |
+| `obj.opportunity.closedFlag`         | View closed flag                |
+| `obj.opportunity.closedBy`           | View closed-by member           |
+| `obj.opportunity.companyId`          | View linked company ID          |
+| `obj.opportunity.cwLastUpdated`      | View CW last-updated timestamp  |
+| `obj.opportunity.createdAt`          | View creation timestamp         |
+| `obj.opportunity.updatedAt`          | View last-updated timestamp     |
+
+**Used in:** [src/api/sales/fetchAll.ts](src/api/sales/fetchAll.ts), [src/api/sales/[id]/fetch.ts](src/api/sales/[id]/fetch.ts)
+
+### UniFi Site (`obj.unifiSite`)
+
+| Field Permission          | Description                   |
+| ------------------------- | ----------------------------- |
+| `obj.unifiSite.id`        | View site internal ID         |
+| `obj.unifiSite.name`      | View site name                |
+| `obj.unifiSite.siteId`    | View UniFi controller site ID |
+| `obj.unifiSite.companyId` | View linked company ID        |
+| `obj.unifiSite.company`   | View linked company object    |
+| `obj.unifiSite.createdAt` | View creation timestamp       |
+| `obj.unifiSite.updatedAt` | View last-updated timestamp   |
+
+**Used in:** [src/api/unifi/sites/fetchAll.ts](src/api/unifi/sites/fetchAll.ts), [src/api/unifi/site/fetch.ts](src/api/unifi/site/fetch.ts), [src/api/companies/[id]/unifiSites.ts](src/api/companies/[id]/unifiSites.ts)
+
+### WiFi Network (`unifi.site.wifi.read`)
+
+See **UniFi Permissions > Field-Level Permission Gating** above for the full list of `unifi.site.wifi.read.<field>` nodes.
+
+---
+
 ## Permission Issuers
 
 Permissions can be issued by different sources:

bun.lock

@@ -16,6 +16,7 @@
         "cors": "^2.8.6",
         "cuid": "^3.0.0",
         "hono": "^4.11.5",
+        "ioredis": "^5.10.0",
         "jsonwebtoken": "^9.0.3",
         "keypair": "^1.0.4",
         "prisma": "^7.3.0",
@@ -57,6 +58,8 @@
 
     "@hono/node-server": ["@hono/node-server@1.19.9", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw=="],
 
+    "@ioredis/commands": ["@ioredis/commands@1.5.1", "", {}, "sha512-JH8ZL/ywcJyR9MmJ5BNqZllXNZQqQbnVZOqpPQqE1vHiFgAw4NHbvE0FOduNU8IX9babitBT46571OnPTT0Zcw=="],
+
     "@mrleebo/prisma-ast": ["@mrleebo/prisma-ast@0.13.1", "", { "dependencies": { "chevrotain": "^10.5.0", "lilconfig": "^2.1.0" } }, "sha512-XyroGQXcHrZdvmrGJvsA9KNeOOgGMg1Vg9OlheUsBOSKznLMDl+YChxbkboRHvtFYJEMRYmlV3uoo/njCw05iw=="],
 
     "@prisma/adapter-pg": ["@prisma/adapter-pg@7.3.0", "", { "dependencies": { "@prisma/driver-adapter-utils": "7.3.0", "pg": "^8.16.3", "postgres-array": "3.0.4" } }, "sha512-iuYQMbIPO6i9O45Fv8TB7vWu00BXhCaNAShenqF7gLExGDbnGp5BfFB4yz1K59zQ59jF6tQ9YHrg0P6/J3OoLg=="],
@@ -131,6 +134,8 @@
 
     "citty": ["citty@0.1.6", "", { "dependencies": { "consola": "^3.2.3" } }, "sha512-tskPPKEs8D2KPafUypv2gxwJP8h/OaJmC82QQGGDQcHvXX43xF2VDACcJVmZ0EuSxkpO9Kc4MlrA3q0+FG58AQ=="],
 
+    "cluster-key-slot": ["cluster-key-slot@1.1.2", "", {}, "sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA=="],
+
     "combined-stream": ["combined-stream@1.0.8", "", { "dependencies": { "delayed-stream": "~1.0.0" } }, "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg=="],
 
     "confbox": ["confbox@0.2.2", "", {}, "sha512-1NB+BKqhtNipMsov4xI/NnhCKp9XG9NamYp5PVm9klAT0fsrNPjaFICsCFhNhwZJKNh7zB/3q8qXz0E9oaMNtQ=="],
@@ -223,6 +228,8 @@
 
     "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
 
+    "ioredis": ["ioredis@5.10.0", "", { "dependencies": { "@ioredis/commands": "1.5.1", "cluster-key-slot": "^1.1.0", "debug": "^4.3.4", "denque": "^2.1.0", "lodash.defaults": "^4.2.0", "lodash.isarguments": "^3.1.0", "redis-errors": "^1.2.0", "redis-parser": "^3.0.0", "standard-as-callback": "^2.1.0" } }, "sha512-HVBe9OFuqs+Z6n64q09PQvP1/R4Bm+30PAyyD4wIEqssh3v9L21QjCVk4kRLucMBcDokJTcLjsGeVRlq/nH6DA=="],
+
     "is-property": ["is-property@1.0.2", "", {}, "sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g=="],
 
     "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
@@ -241,8 +248,12 @@
 
     "lodash": ["lodash@4.17.21", "", {}, "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=="],
 
+    "lodash.defaults": ["lodash.defaults@4.2.0", "", {}, "sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ=="],
+
     "lodash.includes": ["lodash.includes@4.3.0", "", {}, "sha512-W3Bx6mdkRTGtlJISOvVD/lbqjTlPPUDTMnlXZFnVwi9NKJ6tiAk6LVdlhZMm17VZisqhKcgzpO5Wz91PCt5b0w=="],
 
+    "lodash.isarguments": ["lodash.isarguments@3.1.0", "", {}, "sha512-chi4NHZlZqZD18a0imDHnZPrDeBbTtVN7GXMwuGdRH9qotxAjYs3aVLKc7zNOG9eddR5Ksd8rvFEBc9SsggPpg=="],
+
     "lodash.isboolean": ["lodash.isboolean@3.0.3", "", {}, "sha512-Bz5mupy2SVbPHURB98VAcw+aHh4vRV5IPNhILUCsOzRmsTmSQ17jIuqopAentWoehktxGd9e/hbIXq980/1QJg=="],
 
     "lodash.isinteger": ["lodash.isinteger@4.0.4", "", {}, "sha512-DBwtEWN2caHQ9/imiNeEA5ys1JoRtRfY3d7V9wkqtbycnAmTvRRmbHKDV4a0EYc678/dia0jrte4tjYwVBaZUA=="],
@@ -331,6 +342,10 @@
 
     "readdirp": ["readdirp@4.1.2", "", {}, "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg=="],
 
+    "redis-errors": ["redis-errors@1.2.0", "", {}, "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w=="],
+
+    "redis-parser": ["redis-parser@3.0.0", "", { "dependencies": { "redis-errors": "^1.0.0" } }, "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A=="],
+
     "regexp-to-ast": ["regexp-to-ast@0.5.0", "", {}, "sha512-tlbJqcMHnPKI9zSrystikWKwHkBqu2a/Sgw01h3zFjvYrMxEDYHzzoMZnUrbIfpTFEsoRnnviOXNCzFiSc54Qw=="],
 
     "remeda": ["remeda@2.33.4", "", {}, "sha512-ygHswjlc/opg2VrtiYvUOPLjxjtdKvjGz1/plDhkG66hjNjFr1xmfrs2ClNFo/E6TyUFiwYNh53bKV26oBoMGQ=="],
@@ -363,6 +378,8 @@
 
     "sqlstring": ["sqlstring@2.3.3", "", {}, "sha512-qC9iz2FlN7DQl3+wjwn3802RTyjCx7sDvfQEXchwa6CWOx07/WVfh91gBmQ9fahw8snwGEWU3xGzOt4tFyHLxg=="],
 
+    "standard-as-callback": ["standard-as-callback@2.1.0", "", {}, "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A=="],
+
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
     "tinyexec": ["tinyexec@1.0.2", "", {}, "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg=="],

bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+preload = ["./tests/setup.ts"]

generated/prisma/internal/prismaNamespace.ts

@@ -1213,6 +1213,7 @@ export const UserScalarFieldEnum = {
   email: 'email',
   emailVerified: 'emailVerified',
   image: 'image',
+  cwIdentifier: 'cwIdentifier',
   userId: 'userId',
   token: 'token',
   createdAt: 'createdAt',
@@ -1266,6 +1267,10 @@ export const CatalogItemScalarFieldEnum = {
   description: 'description',
   customerDescription: 'customerDescription',
   internalNotes: 'internalNotes',
+  category: 'category',
+  categoryCwId: 'categoryCwId',
+  subcategory: 'subcategory',
+  subcategoryCwId: 'subcategoryCwId',
   manufacturer: 'manufacturer',
   manufactureCwId: 'manufactureCwId',
   partNumber: 'partNumber',
@@ -1329,6 +1334,7 @@ export const OpportunityScalarFieldEnum = {
   closedByName: 'closedByName',
   closedByCwId: 'closedByCwId',
   companyId: 'companyId',
+  productSequence: 'productSequence',
   cwLastUpdated: 'cwLastUpdated',
   createdAt: 'createdAt',
   updatedAt: 'updatedAt'

generated/prisma/internal/prismaNamespaceBrowser.ts

@@ -100,6 +100,7 @@ export const UserScalarFieldEnum = {
   email: 'email',
   emailVerified: 'emailVerified',
   image: 'image',
+  cwIdentifier: 'cwIdentifier',
   userId: 'userId',
   token: 'token',
   createdAt: 'createdAt',
@@ -153,6 +154,10 @@ export const CatalogItemScalarFieldEnum = {
   description: 'description',
   customerDescription: 'customerDescription',
   internalNotes: 'internalNotes',
+  category: 'category',
+  categoryCwId: 'categoryCwId',
+  subcategory: 'subcategory',
+  subcategoryCwId: 'subcategoryCwId',
   manufacturer: 'manufacturer',
   manufactureCwId: 'manufactureCwId',
   partNumber: 'partNumber',
@@ -216,6 +221,7 @@ export const OpportunityScalarFieldEnum = {
   closedByName: 'closedByName',
   closedByCwId: 'closedByCwId',
   companyId: 'companyId',
+  productSequence: 'productSequence',
   cwLastUpdated: 'cwLastUpdated',
   createdAt: 'createdAt',
   updatedAt: 'updatedAt'

generated/prisma/models/CatalogItem.ts

@@ -28,6 +28,8 @@ export type AggregateCatalogItem = {
 
 export type CatalogItemAvgAggregateOutputType = {
   cwCatalogId: number | null
+  categoryCwId: number | null
+  subcategoryCwId: number | null
   manufactureCwId: number | null
   vendorCwId: number | null
   price: number | null
@@ -37,6 +39,8 @@ export type CatalogItemAvgAggregateOutputType = {
 
 export type CatalogItemSumAggregateOutputType = {
   cwCatalogId: number | null
+  categoryCwId: number | null
+  subcategoryCwId: number | null
   manufactureCwId: number | null
   vendorCwId: number | null
   price: number | null
@@ -52,6 +56,10 @@ export type CatalogItemMinAggregateOutputType = {
   description: string | null
   customerDescription: string | null
   internalNotes: string | null
+  category: string | null
+  categoryCwId: number | null
+  subcategory: string | null
+  subcategoryCwId: number | null
   manufacturer: string | null
   manufactureCwId: number | null
   partNumber: string | null
@@ -76,6 +84,10 @@ export type CatalogItemMaxAggregateOutputType = {
   description: string | null
   customerDescription: string | null
   internalNotes: string | null
+  category: string | null
+  categoryCwId: number | null
+  subcategory: string | null
+  subcategoryCwId: number | null
   manufacturer: string | null
   manufactureCwId: number | null
   partNumber: string | null
@@ -100,6 +112,10 @@ export type CatalogItemCountAggregateOutputType = {
   description: number
   customerDescription: number
   internalNotes: number
+  category: number
+  categoryCwId: number
+  subcategory: number
+  subcategoryCwId: number
   manufacturer: number
   manufactureCwId: number
   partNumber: number
@@ -120,6 +136,8 @@ export type CatalogItemCountAggregateOutputType = {
 
 export type CatalogItemAvgAggregateInputType = {
   cwCatalogId?: true
+  categoryCwId?: true
+  subcategoryCwId?: true
   manufactureCwId?: true
   vendorCwId?: true
   price?: true
@@ -129,6 +147,8 @@ export type CatalogItemAvgAggregateInputType = {
 
 export type CatalogItemSumAggregateInputType = {
   cwCatalogId?: true
+  categoryCwId?: true
+  subcategoryCwId?: true
   manufactureCwId?: true
   vendorCwId?: true
   price?: true
@@ -144,6 +164,10 @@ export type CatalogItemMinAggregateInputType = {
   description?: true
   customerDescription?: true
   internalNotes?: true
+  category?: true
+  categoryCwId?: true
+  subcategory?: true
+  subcategoryCwId?: true
   manufacturer?: true
   manufactureCwId?: true
   partNumber?: true
@@ -168,6 +192,10 @@ export type CatalogItemMaxAggregateInputType = {
   description?: true
   customerDescription?: true
   internalNotes?: true
+  category?: true
+  categoryCwId?: true
+  subcategory?: true
+  subcategoryCwId?: true
   manufacturer?: true
   manufactureCwId?: true
   partNumber?: true
@@ -192,6 +220,10 @@ export type CatalogItemCountAggregateInputType = {
   description?: true
   customerDescription?: true
   internalNotes?: true
+  category?: true
+  categoryCwId?: true
+  subcategory?: true
+  subcategoryCwId?: true
   manufacturer?: true
   manufactureCwId?: true
   partNumber?: true
@@ -303,6 +335,10 @@ export type CatalogItemGroupByOutputType = {
   description: string | null
   customerDescription: string | null
   internalNotes: string | null
+  category: string | null
+  categoryCwId: number | null
+  subcategory: string | null
+  subcategoryCwId: number | null
   manufacturer: string | null
   manufactureCwId: number | null
   partNumber: string | null
@@ -350,6 +386,10 @@ export type CatalogItemWhereInput = {
   description?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   customerDescription?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   internalNotes?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  category?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  categoryCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
+  subcategory?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  subcategoryCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
   manufacturer?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   manufactureCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
   partNumber?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
@@ -376,6 +416,10 @@ export type CatalogItemOrderByWithRelationInput = {
   description?: Prisma.SortOrderInput | Prisma.SortOrder
   customerDescription?: Prisma.SortOrderInput | Prisma.SortOrder
   internalNotes?: Prisma.SortOrderInput | Prisma.SortOrder
+  category?: Prisma.SortOrderInput | Prisma.SortOrder
+  categoryCwId?: Prisma.SortOrderInput | Prisma.SortOrder
+  subcategory?: Prisma.SortOrderInput | Prisma.SortOrder
+  subcategoryCwId?: Prisma.SortOrderInput | Prisma.SortOrder
   manufacturer?: Prisma.SortOrderInput | Prisma.SortOrder
   manufactureCwId?: Prisma.SortOrderInput | Prisma.SortOrder
   partNumber?: Prisma.SortOrderInput | Prisma.SortOrder
@@ -405,6 +449,10 @@ export type CatalogItemWhereUniqueInput = Prisma.AtLeast<{
   description?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   customerDescription?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   internalNotes?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  category?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  categoryCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
+  subcategory?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  subcategoryCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
   manufacturer?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   manufactureCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
   partNumber?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
@@ -431,6 +479,10 @@ export type CatalogItemOrderByWithAggregationInput = {
   description?: Prisma.SortOrderInput | Prisma.SortOrder
   customerDescription?: Prisma.SortOrderInput | Prisma.SortOrder
   internalNotes?: Prisma.SortOrderInput | Prisma.SortOrder
+  category?: Prisma.SortOrderInput | Prisma.SortOrder
+  categoryCwId?: Prisma.SortOrderInput | Prisma.SortOrder
+  subcategory?: Prisma.SortOrderInput | Prisma.SortOrder
+  subcategoryCwId?: Prisma.SortOrderInput | Prisma.SortOrder
   manufacturer?: Prisma.SortOrderInput | Prisma.SortOrder
   manufactureCwId?: Prisma.SortOrderInput | Prisma.SortOrder
   partNumber?: Prisma.SortOrderInput | Prisma.SortOrder
@@ -463,6 +515,10 @@ export type CatalogItemScalarWhereWithAggregatesInput = {
   description?: Prisma.StringNullableWithAggregatesFilter<"CatalogItem"> | string | null
   customerDescription?: Prisma.StringNullableWithAggregatesFilter<"CatalogItem"> | string | null
   internalNotes?: Prisma.StringNullableWithAggregatesFilter<"CatalogItem"> | string | null
+  category?: Prisma.StringNullableWithAggregatesFilter<"CatalogItem"> | string | null
+  categoryCwId?: Prisma.IntNullableWithAggregatesFilter<"CatalogItem"> | number | null
+  subcategory?: Prisma.StringNullableWithAggregatesFilter<"CatalogItem"> | string | null
+  subcategoryCwId?: Prisma.IntNullableWithAggregatesFilter<"CatalogItem"> | number | null
   manufacturer?: Prisma.StringNullableWithAggregatesFilter<"CatalogItem"> | string | null
   manufactureCwId?: Prisma.IntNullableWithAggregatesFilter<"CatalogItem"> | number | null
   partNumber?: Prisma.StringNullableWithAggregatesFilter<"CatalogItem"> | string | null
@@ -487,6 +543,10 @@ export type CatalogItemCreateInput = {
   description?: string | null
   customerDescription?: string | null
   internalNotes?: string | null
+  category?: string | null
+  categoryCwId?: number | null
+  subcategory?: string | null
+  subcategoryCwId?: number | null
   manufacturer?: string | null
   manufactureCwId?: number | null
   partNumber?: string | null
@@ -513,6 +573,10 @@ export type CatalogItemUncheckedCreateInput = {
   description?: string | null
   customerDescription?: string | null
   internalNotes?: string | null
+  category?: string | null
+  categoryCwId?: number | null
+  subcategory?: string | null
+  subcategoryCwId?: number | null
   manufacturer?: string | null
   manufactureCwId?: number | null
   partNumber?: string | null
@@ -539,6 +603,10 @@ export type CatalogItemUpdateInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -565,6 +633,10 @@ export type CatalogItemUncheckedUpdateInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -591,6 +663,10 @@ export type CatalogItemCreateManyInput = {
   description?: string | null
   customerDescription?: string | null
   internalNotes?: string | null
+  category?: string | null
+  categoryCwId?: number | null
+  subcategory?: string | null
+  subcategoryCwId?: number | null
   manufacturer?: string | null
   manufactureCwId?: number | null
   partNumber?: string | null
@@ -615,6 +691,10 @@ export type CatalogItemUpdateManyMutationInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -639,6 +719,10 @@ export type CatalogItemUncheckedUpdateManyInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -673,6 +757,10 @@ export type CatalogItemCountOrderByAggregateInput = {
   description?: Prisma.SortOrder
   customerDescription?: Prisma.SortOrder
   internalNotes?: Prisma.SortOrder
+  category?: Prisma.SortOrder
+  categoryCwId?: Prisma.SortOrder
+  subcategory?: Prisma.SortOrder
+  subcategoryCwId?: Prisma.SortOrder
   manufacturer?: Prisma.SortOrder
   manufactureCwId?: Prisma.SortOrder
   partNumber?: Prisma.SortOrder
@@ -691,6 +779,8 @@ export type CatalogItemCountOrderByAggregateInput = {
 
 export type CatalogItemAvgOrderByAggregateInput = {
   cwCatalogId?: Prisma.SortOrder
+  categoryCwId?: Prisma.SortOrder
+  subcategoryCwId?: Prisma.SortOrder
   manufactureCwId?: Prisma.SortOrder
   vendorCwId?: Prisma.SortOrder
   price?: Prisma.SortOrder
@@ -706,6 +796,10 @@ export type CatalogItemMaxOrderByAggregateInput = {
   description?: Prisma.SortOrder
   customerDescription?: Prisma.SortOrder
   internalNotes?: Prisma.SortOrder
+  category?: Prisma.SortOrder
+  categoryCwId?: Prisma.SortOrder
+  subcategory?: Prisma.SortOrder
+  subcategoryCwId?: Prisma.SortOrder
   manufacturer?: Prisma.SortOrder
   manufactureCwId?: Prisma.SortOrder
   partNumber?: Prisma.SortOrder
@@ -730,6 +824,10 @@ export type CatalogItemMinOrderByAggregateInput = {
   description?: Prisma.SortOrder
   customerDescription?: Prisma.SortOrder
   internalNotes?: Prisma.SortOrder
+  category?: Prisma.SortOrder
+  categoryCwId?: Prisma.SortOrder
+  subcategory?: Prisma.SortOrder
+  subcategoryCwId?: Prisma.SortOrder
   manufacturer?: Prisma.SortOrder
   manufactureCwId?: Prisma.SortOrder
   partNumber?: Prisma.SortOrder
@@ -748,6 +846,8 @@ export type CatalogItemMinOrderByAggregateInput = {
 
 export type CatalogItemSumOrderByAggregateInput = {
   cwCatalogId?: Prisma.SortOrder
+  categoryCwId?: Prisma.SortOrder
+  subcategoryCwId?: Prisma.SortOrder
   manufactureCwId?: Prisma.SortOrder
   vendorCwId?: Prisma.SortOrder
   price?: Prisma.SortOrder
@@ -855,6 +955,10 @@ export type CatalogItemCreateWithoutLinkedToInput = {
   description?: string | null
   customerDescription?: string | null
   internalNotes?: string | null
+  category?: string | null
+  categoryCwId?: number | null
+  subcategory?: string | null
+  subcategoryCwId?: number | null
   manufacturer?: string | null
   manufactureCwId?: number | null
   partNumber?: string | null
@@ -880,6 +984,10 @@ export type CatalogItemUncheckedCreateWithoutLinkedToInput = {
   description?: string | null
   customerDescription?: string | null
   internalNotes?: string | null
+  category?: string | null
+  categoryCwId?: number | null
+  subcategory?: string | null
+  subcategoryCwId?: number | null
   manufacturer?: string | null
   manufactureCwId?: number | null
   partNumber?: string | null
@@ -910,6 +1018,10 @@ export type CatalogItemCreateWithoutLinkedItemsInput = {
   description?: string | null
   customerDescription?: string | null
   internalNotes?: string | null
+  category?: string | null
+  categoryCwId?: number | null
+  subcategory?: string | null
+  subcategoryCwId?: number | null
   manufacturer?: string | null
   manufactureCwId?: number | null
   partNumber?: string | null
@@ -935,6 +1047,10 @@ export type CatalogItemUncheckedCreateWithoutLinkedItemsInput = {
   description?: string | null
   customerDescription?: string | null
   internalNotes?: string | null
+  category?: string | null
+  categoryCwId?: number | null
+  subcategory?: string | null
+  subcategoryCwId?: number | null
   manufacturer?: string | null
   manufactureCwId?: number | null
   partNumber?: string | null
@@ -984,6 +1100,10 @@ export type CatalogItemScalarWhereInput = {
   description?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   customerDescription?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   internalNotes?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  category?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  categoryCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
+  subcategory?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
+  subcategoryCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
   manufacturer?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
   manufactureCwId?: Prisma.IntNullableFilter<"CatalogItem"> | number | null
   partNumber?: Prisma.StringNullableFilter<"CatalogItem"> | string | null
@@ -1024,6 +1144,10 @@ export type CatalogItemUpdateWithoutLinkedToInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -1049,6 +1173,10 @@ export type CatalogItemUncheckedUpdateWithoutLinkedToInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -1074,6 +1202,10 @@ export type CatalogItemUncheckedUpdateManyWithoutLinkedToInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -1098,6 +1230,10 @@ export type CatalogItemUpdateWithoutLinkedItemsInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -1123,6 +1259,10 @@ export type CatalogItemUncheckedUpdateWithoutLinkedItemsInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -1148,6 +1288,10 @@ export type CatalogItemUncheckedUpdateManyWithoutLinkedItemsInput = {
   description?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   customerDescription?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   internalNotes?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  category?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  categoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  subcategory?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  subcategoryCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   manufacturer?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   manufactureCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   partNumber?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
@@ -1212,6 +1356,10 @@ export type CatalogItemSelect<ExtArgs extends runtime.Types.Extensions.InternalA
   description?: boolean
   customerDescription?: boolean
   internalNotes?: boolean
+  category?: boolean
+  categoryCwId?: boolean
+  subcategory?: boolean
+  subcategoryCwId?: boolean
   manufacturer?: boolean
   manufactureCwId?: boolean
   partNumber?: boolean
@@ -1239,6 +1387,10 @@ export type CatalogItemSelectCreateManyAndReturn<ExtArgs extends runtime.Types.E
   description?: boolean
   customerDescription?: boolean
   internalNotes?: boolean
+  category?: boolean
+  categoryCwId?: boolean
+  subcategory?: boolean
+  subcategoryCwId?: boolean
   manufacturer?: boolean
   manufactureCwId?: boolean
   partNumber?: boolean
@@ -1263,6 +1415,10 @@ export type CatalogItemSelectUpdateManyAndReturn<ExtArgs extends runtime.Types.E
   description?: boolean
   customerDescription?: boolean
   internalNotes?: boolean
+  category?: boolean
+  categoryCwId?: boolean
+  subcategory?: boolean
+  subcategoryCwId?: boolean
   manufacturer?: boolean
   manufactureCwId?: boolean
   partNumber?: boolean
@@ -1287,6 +1443,10 @@ export type CatalogItemSelectScalar = {
   description?: boolean
   customerDescription?: boolean
   internalNotes?: boolean
+  category?: boolean
+  categoryCwId?: boolean
+  subcategory?: boolean
+  subcategoryCwId?: boolean
   manufacturer?: boolean
   manufactureCwId?: boolean
   partNumber?: boolean
@@ -1303,7 +1463,7 @@ export type CatalogItemSelectScalar = {
   updatedAt?: boolean
 }
 
-export type CatalogItemOmit<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = runtime.Types.Extensions.GetOmit<"id" | "cwCatalogId" | "identifier" | "name" | "description" | "customerDescription" | "internalNotes" | "manufacturer" | "manufactureCwId" | "partNumber" | "vendorName" | "vendorSku" | "vendorCwId" | "price" | "cost" | "inactive" | "salesTaxable" | "onHand" | "cwLastUpdated" | "createdAt" | "updatedAt", ExtArgs["result"]["catalogItem"]>
+export type CatalogItemOmit<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = runtime.Types.Extensions.GetOmit<"id" | "cwCatalogId" | "identifier" | "name" | "description" | "customerDescription" | "internalNotes" | "category" | "categoryCwId" | "subcategory" | "subcategoryCwId" | "manufacturer" | "manufactureCwId" | "partNumber" | "vendorName" | "vendorSku" | "vendorCwId" | "price" | "cost" | "inactive" | "salesTaxable" | "onHand" | "cwLastUpdated" | "createdAt" | "updatedAt", ExtArgs["result"]["catalogItem"]>
 export type CatalogItemInclude<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = {
   linkedItems?: boolean | Prisma.CatalogItem$linkedItemsArgs<ExtArgs>
   linkedTo?: boolean | Prisma.CatalogItem$linkedToArgs<ExtArgs>
@@ -1326,6 +1486,10 @@ export type $CatalogItemPayload<ExtArgs extends runtime.Types.Extensions.Interna
     description: string | null
     customerDescription: string | null
     internalNotes: string | null
+    category: string | null
+    categoryCwId: number | null
+    subcategory: string | null
+    subcategoryCwId: number | null
     manufacturer: string | null
     manufactureCwId: number | null
     partNumber: string | null
@@ -1772,6 +1936,10 @@ export interface CatalogItemFieldRefs {
   readonly description: Prisma.FieldRef<"CatalogItem", 'String'>
   readonly customerDescription: Prisma.FieldRef<"CatalogItem", 'String'>
   readonly internalNotes: Prisma.FieldRef<"CatalogItem", 'String'>
+  readonly category: Prisma.FieldRef<"CatalogItem", 'String'>
+  readonly categoryCwId: Prisma.FieldRef<"CatalogItem", 'Int'>
+  readonly subcategory: Prisma.FieldRef<"CatalogItem", 'String'>
+  readonly subcategoryCwId: Prisma.FieldRef<"CatalogItem", 'Int'>
   readonly manufacturer: Prisma.FieldRef<"CatalogItem", 'String'>
   readonly manufactureCwId: Prisma.FieldRef<"CatalogItem", 'Int'>
   readonly partNumber: Prisma.FieldRef<"CatalogItem", 'String'>

generated/prisma/models/Opportunity.ts

@@ -43,6 +43,7 @@ export type OpportunityAvgAggregateOutputType = {
   locationCwId: number | null
   departmentCwId: number | null
   closedByCwId: number | null
+  productSequence: number | null
 }
 
 export type OpportunitySumAggregateOutputType = {
@@ -62,6 +63,7 @@ export type OpportunitySumAggregateOutputType = {
   locationCwId: number | null
   departmentCwId: number | null
   closedByCwId: number | null
+  productSequence: number[]
 }
 
 export type OpportunityMinAggregateOutputType = {
@@ -206,6 +208,7 @@ export type OpportunityCountAggregateOutputType = {
   closedByName: number
   closedByCwId: number
   companyId: number
+  productSequence: number
   cwLastUpdated: number
   createdAt: number
   updatedAt: number
@@ -230,6 +233,7 @@ export type OpportunityAvgAggregateInputType = {
   locationCwId?: true
   departmentCwId?: true
   closedByCwId?: true
+  productSequence?: true
 }
 
 export type OpportunitySumAggregateInputType = {
@@ -249,6 +253,7 @@ export type OpportunitySumAggregateInputType = {
   locationCwId?: true
   departmentCwId?: true
   closedByCwId?: true
+  productSequence?: true
 }
 
 export type OpportunityMinAggregateInputType = {
@@ -393,6 +398,7 @@ export type OpportunityCountAggregateInputType = {
   closedByName?: true
   closedByCwId?: true
   companyId?: true
+  productSequence?: true
   cwLastUpdated?: true
   createdAt?: true
   updatedAt?: true
@@ -529,6 +535,7 @@ export type OpportunityGroupByOutputType = {
   closedByName: string | null
   closedByCwId: number | null
   companyId: string | null
+  productSequence: number[]
   cwLastUpdated: Date | null
   createdAt: Date
   updatedAt: Date
@@ -601,6 +608,7 @@ export type OpportunityWhereInput = {
   closedByName?: Prisma.StringNullableFilter<"Opportunity"> | string | null
   closedByCwId?: Prisma.IntNullableFilter<"Opportunity"> | number | null
   companyId?: Prisma.StringNullableFilter<"Opportunity"> | string | null
+  productSequence?: Prisma.IntNullableListFilter<"Opportunity">
   cwLastUpdated?: Prisma.DateTimeNullableFilter<"Opportunity"> | Date | string | null
   createdAt?: Prisma.DateTimeFilter<"Opportunity"> | Date | string
   updatedAt?: Prisma.DateTimeFilter<"Opportunity"> | Date | string
@@ -651,6 +659,7 @@ export type OpportunityOrderByWithRelationInput = {
   closedByName?: Prisma.SortOrderInput | Prisma.SortOrder
   closedByCwId?: Prisma.SortOrderInput | Prisma.SortOrder
   companyId?: Prisma.SortOrderInput | Prisma.SortOrder
+  productSequence?: Prisma.SortOrder
   cwLastUpdated?: Prisma.SortOrderInput | Prisma.SortOrder
   createdAt?: Prisma.SortOrder
   updatedAt?: Prisma.SortOrder
@@ -704,6 +713,7 @@ export type OpportunityWhereUniqueInput = Prisma.AtLeast<{
   closedByName?: Prisma.StringNullableFilter<"Opportunity"> | string | null
   closedByCwId?: Prisma.IntNullableFilter<"Opportunity"> | number | null
   companyId?: Prisma.StringNullableFilter<"Opportunity"> | string | null
+  productSequence?: Prisma.IntNullableListFilter<"Opportunity">
   cwLastUpdated?: Prisma.DateTimeNullableFilter<"Opportunity"> | Date | string | null
   createdAt?: Prisma.DateTimeFilter<"Opportunity"> | Date | string
   updatedAt?: Prisma.DateTimeFilter<"Opportunity"> | Date | string
@@ -754,6 +764,7 @@ export type OpportunityOrderByWithAggregationInput = {
   closedByName?: Prisma.SortOrderInput | Prisma.SortOrder
   closedByCwId?: Prisma.SortOrderInput | Prisma.SortOrder
   companyId?: Prisma.SortOrderInput | Prisma.SortOrder
+  productSequence?: Prisma.SortOrder
   cwLastUpdated?: Prisma.SortOrderInput | Prisma.SortOrder
   createdAt?: Prisma.SortOrder
   updatedAt?: Prisma.SortOrder
@@ -811,6 +822,7 @@ export type OpportunityScalarWhereWithAggregatesInput = {
   closedByName?: Prisma.StringNullableWithAggregatesFilter<"Opportunity"> | string | null
   closedByCwId?: Prisma.IntNullableWithAggregatesFilter<"Opportunity"> | number | null
   companyId?: Prisma.StringNullableWithAggregatesFilter<"Opportunity"> | string | null
+  productSequence?: Prisma.IntNullableListFilter<"Opportunity">
   cwLastUpdated?: Prisma.DateTimeNullableWithAggregatesFilter<"Opportunity"> | Date | string | null
   createdAt?: Prisma.DateTimeWithAggregatesFilter<"Opportunity"> | Date | string
   updatedAt?: Prisma.DateTimeWithAggregatesFilter<"Opportunity"> | Date | string
@@ -859,6 +871,7 @@ export type OpportunityCreateInput = {
   closedFlag?: boolean
   closedByName?: string | null
   closedByCwId?: number | null
+  productSequence?: Prisma.OpportunityCreateproductSequenceInput | number[]
   cwLastUpdated?: Date | string | null
   createdAt?: Date | string
   updatedAt?: Date | string
@@ -909,6 +922,7 @@ export type OpportunityUncheckedCreateInput = {
   closedByName?: string | null
   closedByCwId?: number | null
   companyId?: string | null
+  productSequence?: Prisma.OpportunityCreateproductSequenceInput | number[]
   cwLastUpdated?: Date | string | null
   createdAt?: Date | string
   updatedAt?: Date | string
@@ -957,6 +971,7 @@ export type OpportunityUpdateInput = {
   closedFlag?: Prisma.BoolFieldUpdateOperationsInput | boolean
   closedByName?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   closedByCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  productSequence?: Prisma.OpportunityUpdateproductSequenceInput | number[]
   cwLastUpdated?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
   updatedAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -1007,6 +1022,7 @@ export type OpportunityUncheckedUpdateInput = {
   closedByName?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   closedByCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   companyId?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  productSequence?: Prisma.OpportunityUpdateproductSequenceInput | number[]
   cwLastUpdated?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
   updatedAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -1056,6 +1072,7 @@ export type OpportunityCreateManyInput = {
   closedByName?: string | null
   closedByCwId?: number | null
   companyId?: string | null
+  productSequence?: Prisma.OpportunityCreateproductSequenceInput | number[]
   cwLastUpdated?: Date | string | null
   createdAt?: Date | string
   updatedAt?: Date | string
@@ -1104,6 +1121,7 @@ export type OpportunityUpdateManyMutationInput = {
   closedFlag?: Prisma.BoolFieldUpdateOperationsInput | boolean
   closedByName?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   closedByCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  productSequence?: Prisma.OpportunityUpdateproductSequenceInput | number[]
   cwLastUpdated?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
   updatedAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -1153,6 +1171,7 @@ export type OpportunityUncheckedUpdateManyInput = {
   closedByName?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   closedByCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
   companyId?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  productSequence?: Prisma.OpportunityUpdateproductSequenceInput | number[]
   cwLastUpdated?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
   updatedAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -1168,6 +1187,14 @@ export type OpportunityOrderByRelationAggregateInput = {
   _count?: Prisma.SortOrder
 }
 
+export type IntNullableListFilter<$PrismaModel = never> = {
+  equals?: number[] | Prisma.ListIntFieldRefInput<$PrismaModel> | null
+  has?: number | Prisma.IntFieldRefInput<$PrismaModel> | null
+  hasEvery?: number[] | Prisma.ListIntFieldRefInput<$PrismaModel>
+  hasSome?: number[] | Prisma.ListIntFieldRefInput<$PrismaModel>
+  isEmpty?: boolean
+}
+
 export type OpportunityCountOrderByAggregateInput = {
   id?: Prisma.SortOrder
   cwOpportunityId?: Prisma.SortOrder
@@ -1212,6 +1239,7 @@ export type OpportunityCountOrderByAggregateInput = {
   closedByName?: Prisma.SortOrder
   closedByCwId?: Prisma.SortOrder
   companyId?: Prisma.SortOrder
+  productSequence?: Prisma.SortOrder
   cwLastUpdated?: Prisma.SortOrder
   createdAt?: Prisma.SortOrder
   updatedAt?: Prisma.SortOrder
@@ -1234,6 +1262,7 @@ export type OpportunityAvgOrderByAggregateInput = {
   locationCwId?: Prisma.SortOrder
   departmentCwId?: Prisma.SortOrder
   closedByCwId?: Prisma.SortOrder
+  productSequence?: Prisma.SortOrder
 }
 
 export type OpportunityMaxOrderByAggregateInput = {
@@ -1351,6 +1380,7 @@ export type OpportunitySumOrderByAggregateInput = {
   locationCwId?: Prisma.SortOrder
   departmentCwId?: Prisma.SortOrder
   closedByCwId?: Prisma.SortOrder
+  productSequence?: Prisma.SortOrder
 }
 
 export type OpportunityCreateNestedManyWithoutCompanyInput = {
@@ -1395,6 +1425,15 @@ export type OpportunityUncheckedUpdateManyWithoutCompanyNestedInput = {
   deleteMany?: Prisma.OpportunityScalarWhereInput | Prisma.OpportunityScalarWhereInput[]
 }
 
+export type OpportunityCreateproductSequenceInput = {
+  set: number[]
+}
+
+export type OpportunityUpdateproductSequenceInput = {
+  set?: number[]
+  push?: number | number[]
+}
+
 export type OpportunityCreateWithoutCompanyInput = {
   id?: string
   cwOpportunityId: number
@@ -1438,6 +1477,7 @@ export type OpportunityCreateWithoutCompanyInput = {
   closedFlag?: boolean
   closedByName?: string | null
   closedByCwId?: number | null
+  productSequence?: Prisma.OpportunityCreateproductSequenceInput | number[]
   cwLastUpdated?: Date | string | null
   createdAt?: Date | string
   updatedAt?: Date | string
@@ -1486,6 +1526,7 @@ export type OpportunityUncheckedCreateWithoutCompanyInput = {
   closedFlag?: boolean
   closedByName?: string | null
   closedByCwId?: number | null
+  productSequence?: Prisma.OpportunityCreateproductSequenceInput | number[]
   cwLastUpdated?: Date | string | null
   createdAt?: Date | string
   updatedAt?: Date | string
@@ -1564,6 +1605,7 @@ export type OpportunityScalarWhereInput = {
   closedByName?: Prisma.StringNullableFilter<"Opportunity"> | string | null
   closedByCwId?: Prisma.IntNullableFilter<"Opportunity"> | number | null
   companyId?: Prisma.StringNullableFilter<"Opportunity"> | string | null
+  productSequence?: Prisma.IntNullableListFilter<"Opportunity">
   cwLastUpdated?: Prisma.DateTimeNullableFilter<"Opportunity"> | Date | string | null
   createdAt?: Prisma.DateTimeFilter<"Opportunity"> | Date | string
   updatedAt?: Prisma.DateTimeFilter<"Opportunity"> | Date | string
@@ -1612,6 +1654,7 @@ export type OpportunityCreateManyCompanyInput = {
   closedFlag?: boolean
   closedByName?: string | null
   closedByCwId?: number | null
+  productSequence?: Prisma.OpportunityCreateproductSequenceInput | number[]
   cwLastUpdated?: Date | string | null
   createdAt?: Date | string
   updatedAt?: Date | string
@@ -1660,6 +1703,7 @@ export type OpportunityUpdateWithoutCompanyInput = {
   closedFlag?: Prisma.BoolFieldUpdateOperationsInput | boolean
   closedByName?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   closedByCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  productSequence?: Prisma.OpportunityUpdateproductSequenceInput | number[]
   cwLastUpdated?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
   updatedAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -1708,6 +1752,7 @@ export type OpportunityUncheckedUpdateWithoutCompanyInput = {
   closedFlag?: Prisma.BoolFieldUpdateOperationsInput | boolean
   closedByName?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   closedByCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  productSequence?: Prisma.OpportunityUpdateproductSequenceInput | number[]
   cwLastUpdated?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
   updatedAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -1756,6 +1801,7 @@ export type OpportunityUncheckedUpdateManyWithoutCompanyInput = {
   closedFlag?: Prisma.BoolFieldUpdateOperationsInput | boolean
   closedByName?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   closedByCwId?: Prisma.NullableIntFieldUpdateOperationsInput | number | null
+  productSequence?: Prisma.OpportunityUpdateproductSequenceInput | number[]
   cwLastUpdated?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
   updatedAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -1807,6 +1853,7 @@ export type OpportunitySelect<ExtArgs extends runtime.Types.Extensions.InternalA
   closedByName?: boolean
   closedByCwId?: boolean
   companyId?: boolean
+  productSequence?: boolean
   cwLastUpdated?: boolean
   createdAt?: boolean
   updatedAt?: boolean
@@ -1857,6 +1904,7 @@ export type OpportunitySelectCreateManyAndReturn<ExtArgs extends runtime.Types.E
   closedByName?: boolean
   closedByCwId?: boolean
   companyId?: boolean
+  productSequence?: boolean
   cwLastUpdated?: boolean
   createdAt?: boolean
   updatedAt?: boolean
@@ -1907,6 +1955,7 @@ export type OpportunitySelectUpdateManyAndReturn<ExtArgs extends runtime.Types.E
   closedByName?: boolean
   closedByCwId?: boolean
   companyId?: boolean
+  productSequence?: boolean
   cwLastUpdated?: boolean
   createdAt?: boolean
   updatedAt?: boolean
@@ -1957,12 +2006,13 @@ export type OpportunitySelectScalar = {
   closedByName?: boolean
   closedByCwId?: boolean
   companyId?: boolean
+  productSequence?: boolean
   cwLastUpdated?: boolean
   createdAt?: boolean
   updatedAt?: boolean
 }
 
-export type OpportunityOmit<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = runtime.Types.Extensions.GetOmit<"id" | "cwOpportunityId" | "name" | "notes" | "typeName" | "typeCwId" | "stageName" | "stageCwId" | "statusName" | "statusCwId" | "priorityName" | "priorityCwId" | "ratingName" | "ratingCwId" | "source" | "campaignName" | "campaignCwId" | "primarySalesRepName" | "primarySalesRepIdentifier" | "primarySalesRepCwId" | "secondarySalesRepName" | "secondarySalesRepIdentifier" | "secondarySalesRepCwId" | "companyCwId" | "companyName" | "contactCwId" | "contactName" | "siteCwId" | "siteName" | "customerPO" | "totalSalesTax" | "locationName" | "locationCwId" | "departmentName" | "departmentCwId" | "expectedCloseDate" | "pipelineChangeDate" | "dateBecameLead" | "closedDate" | "closedFlag" | "closedByName" | "closedByCwId" | "companyId" | "cwLastUpdated" | "createdAt" | "updatedAt", ExtArgs["result"]["opportunity"]>
+export type OpportunityOmit<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = runtime.Types.Extensions.GetOmit<"id" | "cwOpportunityId" | "name" | "notes" | "typeName" | "typeCwId" | "stageName" | "stageCwId" | "statusName" | "statusCwId" | "priorityName" | "priorityCwId" | "ratingName" | "ratingCwId" | "source" | "campaignName" | "campaignCwId" | "primarySalesRepName" | "primarySalesRepIdentifier" | "primarySalesRepCwId" | "secondarySalesRepName" | "secondarySalesRepIdentifier" | "secondarySalesRepCwId" | "companyCwId" | "companyName" | "contactCwId" | "contactName" | "siteCwId" | "siteName" | "customerPO" | "totalSalesTax" | "locationName" | "locationCwId" | "departmentName" | "departmentCwId" | "expectedCloseDate" | "pipelineChangeDate" | "dateBecameLead" | "closedDate" | "closedFlag" | "closedByName" | "closedByCwId" | "companyId" | "productSequence" | "cwLastUpdated" | "createdAt" | "updatedAt", ExtArgs["result"]["opportunity"]>
 export type OpportunityInclude<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = {
   company?: boolean | Prisma.Opportunity$companyArgs<ExtArgs>
 }
@@ -2022,6 +2072,7 @@ export type $OpportunityPayload<ExtArgs extends runtime.Types.Extensions.Interna
     closedByName: string | null
     closedByCwId: number | null
     companyId: string | null
+    productSequence: number[]
     cwLastUpdated: Date | null
     createdAt: Date
     updatedAt: Date
@@ -2492,6 +2543,7 @@ export interface OpportunityFieldRefs {
   readonly closedByName: Prisma.FieldRef<"Opportunity", 'String'>
   readonly closedByCwId: Prisma.FieldRef<"Opportunity", 'Int'>
   readonly companyId: Prisma.FieldRef<"Opportunity", 'String'>
+  readonly productSequence: Prisma.FieldRef<"Opportunity", 'Int[]'>
   readonly cwLastUpdated: Prisma.FieldRef<"Opportunity", 'DateTime'>
   readonly createdAt: Prisma.FieldRef<"Opportunity", 'DateTime'>
   readonly updatedAt: Prisma.FieldRef<"Opportunity", 'DateTime'>

generated/prisma/models/User.ts

@@ -32,6 +32,7 @@ export type UserMinAggregateOutputType = {
   email: string | null
   emailVerified: Date | null
   image: string | null
+  cwIdentifier: string | null
   userId: string | null
   token: string | null
   createdAt: Date | null
@@ -46,6 +47,7 @@ export type UserMaxAggregateOutputType = {
   email: string | null
   emailVerified: Date | null
   image: string | null
+  cwIdentifier: string | null
   userId: string | null
   token: string | null
   createdAt: Date | null
@@ -60,6 +62,7 @@ export type UserCountAggregateOutputType = {
   email: number
   emailVerified: number
   image: number
+  cwIdentifier: number
   userId: number
   token: number
   createdAt: number
@@ -76,6 +79,7 @@ export type UserMinAggregateInputType = {
   email?: true
   emailVerified?: true
   image?: true
+  cwIdentifier?: true
   userId?: true
   token?: true
   createdAt?: true
@@ -90,6 +94,7 @@ export type UserMaxAggregateInputType = {
   email?: true
   emailVerified?: true
   image?: true
+  cwIdentifier?: true
   userId?: true
   token?: true
   createdAt?: true
@@ -104,6 +109,7 @@ export type UserCountAggregateInputType = {
   email?: true
   emailVerified?: true
   image?: true
+  cwIdentifier?: true
   userId?: true
   token?: true
   createdAt?: true
@@ -191,6 +197,7 @@ export type UserGroupByOutputType = {
   email: string
   emailVerified: Date | null
   image: string | null
+  cwIdentifier: string | null
   userId: string
   token: string | null
   createdAt: Date
@@ -226,6 +233,7 @@ export type UserWhereInput = {
   email?: Prisma.StringFilter<"User"> | string
   emailVerified?: Prisma.DateTimeNullableFilter<"User"> | Date | string | null
   image?: Prisma.StringNullableFilter<"User"> | string | null
+  cwIdentifier?: Prisma.StringNullableFilter<"User"> | string | null
   userId?: Prisma.StringFilter<"User"> | string
   token?: Prisma.StringNullableFilter<"User"> | string | null
   createdAt?: Prisma.DateTimeFilter<"User"> | Date | string
@@ -242,6 +250,7 @@ export type UserOrderByWithRelationInput = {
   email?: Prisma.SortOrder
   emailVerified?: Prisma.SortOrderInput | Prisma.SortOrder
   image?: Prisma.SortOrderInput | Prisma.SortOrder
+  cwIdentifier?: Prisma.SortOrderInput | Prisma.SortOrder
   userId?: Prisma.SortOrder
   token?: Prisma.SortOrderInput | Prisma.SortOrder
   createdAt?: Prisma.SortOrder
@@ -262,6 +271,7 @@ export type UserWhereUniqueInput = Prisma.AtLeast<{
   name?: Prisma.StringNullableFilter<"User"> | string | null
   emailVerified?: Prisma.DateTimeNullableFilter<"User"> | Date | string | null
   image?: Prisma.StringNullableFilter<"User"> | string | null
+  cwIdentifier?: Prisma.StringNullableFilter<"User"> | string | null
   token?: Prisma.StringNullableFilter<"User"> | string | null
   createdAt?: Prisma.DateTimeFilter<"User"> | Date | string
   updatedAt?: Prisma.DateTimeFilter<"User"> | Date | string
@@ -277,6 +287,7 @@ export type UserOrderByWithAggregationInput = {
   email?: Prisma.SortOrder
   emailVerified?: Prisma.SortOrderInput | Prisma.SortOrder
   image?: Prisma.SortOrderInput | Prisma.SortOrder
+  cwIdentifier?: Prisma.SortOrderInput | Prisma.SortOrder
   userId?: Prisma.SortOrder
   token?: Prisma.SortOrderInput | Prisma.SortOrder
   createdAt?: Prisma.SortOrder
@@ -297,6 +308,7 @@ export type UserScalarWhereWithAggregatesInput = {
   email?: Prisma.StringWithAggregatesFilter<"User"> | string
   emailVerified?: Prisma.DateTimeNullableWithAggregatesFilter<"User"> | Date | string | null
   image?: Prisma.StringNullableWithAggregatesFilter<"User"> | string | null
+  cwIdentifier?: Prisma.StringNullableWithAggregatesFilter<"User"> | string | null
   userId?: Prisma.StringWithAggregatesFilter<"User"> | string
   token?: Prisma.StringNullableWithAggregatesFilter<"User"> | string | null
   createdAt?: Prisma.DateTimeWithAggregatesFilter<"User"> | Date | string
@@ -311,6 +323,7 @@ export type UserCreateInput = {
   email: string
   emailVerified?: Date | string | null
   image?: string | null
+  cwIdentifier?: string | null
   userId: string
   token?: string | null
   createdAt?: Date | string
@@ -327,6 +340,7 @@ export type UserUncheckedCreateInput = {
   email: string
   emailVerified?: Date | string | null
   image?: string | null
+  cwIdentifier?: string | null
   userId: string
   token?: string | null
   createdAt?: Date | string
@@ -343,6 +357,7 @@ export type UserUpdateInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -359,6 +374,7 @@ export type UserUncheckedUpdateInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -375,6 +391,7 @@ export type UserCreateManyInput = {
   email: string
   emailVerified?: Date | string | null
   image?: string | null
+  cwIdentifier?: string | null
   userId: string
   token?: string | null
   createdAt?: Date | string
@@ -389,6 +406,7 @@ export type UserUpdateManyMutationInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -403,6 +421,7 @@ export type UserUncheckedUpdateManyInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -422,6 +441,7 @@ export type UserCountOrderByAggregateInput = {
   email?: Prisma.SortOrder
   emailVerified?: Prisma.SortOrder
   image?: Prisma.SortOrder
+  cwIdentifier?: Prisma.SortOrder
   userId?: Prisma.SortOrder
   token?: Prisma.SortOrder
   createdAt?: Prisma.SortOrder
@@ -436,6 +456,7 @@ export type UserMaxOrderByAggregateInput = {
   email?: Prisma.SortOrder
   emailVerified?: Prisma.SortOrder
   image?: Prisma.SortOrder
+  cwIdentifier?: Prisma.SortOrder
   userId?: Prisma.SortOrder
   token?: Prisma.SortOrder
   createdAt?: Prisma.SortOrder
@@ -450,6 +471,7 @@ export type UserMinOrderByAggregateInput = {
   email?: Prisma.SortOrder
   emailVerified?: Prisma.SortOrder
   image?: Prisma.SortOrder
+  cwIdentifier?: Prisma.SortOrder
   userId?: Prisma.SortOrder
   token?: Prisma.SortOrder
   createdAt?: Prisma.SortOrder
@@ -530,6 +552,7 @@ export type UserCreateWithoutSessionsInput = {
   email: string
   emailVerified?: Date | string | null
   image?: string | null
+  cwIdentifier?: string | null
   userId: string
   token?: string | null
   createdAt?: Date | string
@@ -545,6 +568,7 @@ export type UserUncheckedCreateWithoutSessionsInput = {
   email: string
   emailVerified?: Date | string | null
   image?: string | null
+  cwIdentifier?: string | null
   userId: string
   token?: string | null
   createdAt?: Date | string
@@ -576,6 +600,7 @@ export type UserUpdateWithoutSessionsInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -591,6 +616,7 @@ export type UserUncheckedUpdateWithoutSessionsInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -606,6 +632,7 @@ export type UserCreateWithoutRolesInput = {
   email: string
   emailVerified?: Date | string | null
   image?: string | null
+  cwIdentifier?: string | null
   userId: string
   token?: string | null
   createdAt?: Date | string
@@ -621,6 +648,7 @@ export type UserUncheckedCreateWithoutRolesInput = {
   email: string
   emailVerified?: Date | string | null
   image?: string | null
+  cwIdentifier?: string | null
   userId: string
   token?: string | null
   createdAt?: Date | string
@@ -660,6 +688,7 @@ export type UserScalarWhereInput = {
   email?: Prisma.StringFilter<"User"> | string
   emailVerified?: Prisma.DateTimeNullableFilter<"User"> | Date | string | null
   image?: Prisma.StringNullableFilter<"User"> | string | null
+  cwIdentifier?: Prisma.StringNullableFilter<"User"> | string | null
   userId?: Prisma.StringFilter<"User"> | string
   token?: Prisma.StringNullableFilter<"User"> | string | null
   createdAt?: Prisma.DateTimeFilter<"User"> | Date | string
@@ -674,6 +703,7 @@ export type UserUpdateWithoutRolesInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -689,6 +719,7 @@ export type UserUncheckedUpdateWithoutRolesInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -704,6 +735,7 @@ export type UserUncheckedUpdateManyWithoutRolesInput = {
   email?: Prisma.StringFieldUpdateOperationsInput | string
   emailVerified?: Prisma.NullableDateTimeFieldUpdateOperationsInput | Date | string | null
   image?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
+  cwIdentifier?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   userId?: Prisma.StringFieldUpdateOperationsInput | string
   token?: Prisma.NullableStringFieldUpdateOperationsInput | string | null
   createdAt?: Prisma.DateTimeFieldUpdateOperationsInput | Date | string
@@ -758,6 +790,7 @@ export type UserSelect<ExtArgs extends runtime.Types.Extensions.InternalArgs = r
   email?: boolean
   emailVerified?: boolean
   image?: boolean
+  cwIdentifier?: boolean
   userId?: boolean
   token?: boolean
   createdAt?: boolean
@@ -775,6 +808,7 @@ export type UserSelectCreateManyAndReturn<ExtArgs extends runtime.Types.Extensio
   email?: boolean
   emailVerified?: boolean
   image?: boolean
+  cwIdentifier?: boolean
   userId?: boolean
   token?: boolean
   createdAt?: boolean
@@ -789,6 +823,7 @@ export type UserSelectUpdateManyAndReturn<ExtArgs extends runtime.Types.Extensio
   email?: boolean
   emailVerified?: boolean
   image?: boolean
+  cwIdentifier?: boolean
   userId?: boolean
   token?: boolean
   createdAt?: boolean
@@ -803,13 +838,14 @@ export type UserSelectScalar = {
   email?: boolean
   emailVerified?: boolean
   image?: boolean
+  cwIdentifier?: boolean
   userId?: boolean
   token?: boolean
   createdAt?: boolean
   updatedAt?: boolean
 }
 
-export type UserOmit<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = runtime.Types.Extensions.GetOmit<"id" | "permissions" | "login" | "name" | "email" | "emailVerified" | "image" | "userId" | "token" | "createdAt" | "updatedAt", ExtArgs["result"]["user"]>
+export type UserOmit<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = runtime.Types.Extensions.GetOmit<"id" | "permissions" | "login" | "name" | "email" | "emailVerified" | "image" | "cwIdentifier" | "userId" | "token" | "createdAt" | "updatedAt", ExtArgs["result"]["user"]>
 export type UserInclude<ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = {
   roles?: boolean | Prisma.User$rolesArgs<ExtArgs>
   sessions?: boolean | Prisma.User$sessionsArgs<ExtArgs>
@@ -832,6 +868,7 @@ export type $UserPayload<ExtArgs extends runtime.Types.Extensions.InternalArgs =
     email: string
     emailVerified: Date | null
     image: string | null
+    cwIdentifier: string | null
     userId: string
     token: string | null
     createdAt: Date
@@ -1268,6 +1305,7 @@ export interface UserFieldRefs {
   readonly email: Prisma.FieldRef<"User", 'String'>
   readonly emailVerified: Prisma.FieldRef<"User", 'DateTime'>
   readonly image: Prisma.FieldRef<"User", 'String'>
+  readonly cwIdentifier: Prisma.FieldRef<"User", 'String'>
   readonly userId: Prisma.FieldRef<"User", 'String'>
   readonly token: Prisma.FieldRef<"User", 'String'>
   readonly createdAt: Prisma.FieldRef<"User", 'DateTime'>

package.json

@@ -41,6 +41,7 @@
     "cors": "^2.8.6",
     "cuid": "^3.0.0",
     "hono": "^4.11.5",
+    "ioredis": "^5.10.0",
     "jsonwebtoken": "^9.0.3",
     "keypair": "^1.0.4",
     "prisma": "^7.3.0",

prisma/migrate-entrypoint.sh

@@ -3,42 +3,21 @@ set -e
 
 # ---------------------------------------------------------------------------
 # 1. Resolve any previously failed migrations so deploy can proceed.
-#    Prisma marks failed migrations in _prisma_migrations; we roll them back
+#    Only migrations explicitly marked as "Failed" in the status output are
-#    so the current run can re-apply them cleanly.
+#    resolved. We grep for lines containing "Failed" and extract the name.
 # ---------------------------------------------------------------------------
 echo "[migrate] Checking for failed migrations..."
-FAILED=$(bunx prisma migrate status 2>&1 || true)
+STATUS_OUTPUT=$(bunx prisma migrate status 2>&1 || true)
+echo "$STATUS_OUTPUT"
 
-# Extract failed migration names and mark them as rolled back
+# Only resolve migrations whose status line explicitly says "Failed"
-echo "$FAILED" | grep -oE '[0-9]{14}_[a-z_]+' | while read -r MIGRATION; do
+echo "$STATUS_OUTPUT" | grep -i "failed" | grep -oE '[0-9]{14}_[a-zA-Z_]+' | while read -r MIGRATION; do
-  # Only resolve if the status output says it failed
+  echo "[migrate] Resolving failed migration: $MIGRATION"
-  if echo "$FAILED" | grep -q "failed"; then
+  bunx prisma migrate resolve --rolled-back "$MIGRATION" || true
-    echo "[migrate] Resolving failed migration: $MIGRATION"
-    bunx prisma migrate resolve --rolled-back "$MIGRATION" 2>/dev/null || true
-  fi
 done
 
 # ---------------------------------------------------------------------------
-# 2. Generate diff SQL between current migrations and the Prisma schema.
+# 2. Deploy all pending migrations from the migrations directory.
-# ---------------------------------------------------------------------------
-DIFF_SQL=$(bunx prisma migrate diff \
-  --from-migrations prisma/migrations \
-  --to-schema-datamodel prisma/schema.prisma \
-  --script 2>/dev/null || true)
-
-# If there's a meaningful diff (not just empty/comments), create a migration
-if [ -n "$DIFF_SQL" ] && echo "$DIFF_SQL" | grep -qvE '^\s*$|^--'; then
-  TIMESTAMP=$(date -u +"%Y%m%d%H%M%S")
-  MIGRATION_DIR="prisma/migrations/${TIMESTAMP}_auto_generated"
-  mkdir -p "$MIGRATION_DIR"
-  echo "$DIFF_SQL" > "$MIGRATION_DIR/migration.sql"
-  echo "[migrate] Created migration: $MIGRATION_DIR"
-else
-  echo "[migrate] Schema and migrations are in sync — no migration needed."
-fi
-
-# ---------------------------------------------------------------------------
-# 3. Deploy all pending migrations.
 # ---------------------------------------------------------------------------
 echo "[migrate] Running prisma migrate deploy..."
 bunx prisma migrate deploy

prisma/migrations/20260228000000_add_catalog_item_identifier/migration.sql

@@ -0,0 +1,5 @@
+-- AlterTable
+ALTER TABLE "CatalogItem" ADD COLUMN "identifier" TEXT;
+
+-- CreateIndex
+CREATE UNIQUE INDEX "CatalogItem_identifier_key" ON "CatalogItem"("identifier");

prisma/migrations/20260302000000_add_missing_columns/migration.sql

@@ -0,0 +1,11 @@
+-- AlterTable: User
+ALTER TABLE "User" ADD COLUMN "cwIdentifier" TEXT;
+
+-- AlterTable: CatalogItem
+ALTER TABLE "CatalogItem" ADD COLUMN "category" TEXT;
+ALTER TABLE "CatalogItem" ADD COLUMN "categoryCwId" INTEGER;
+ALTER TABLE "CatalogItem" ADD COLUMN "subcategory" TEXT;
+ALTER TABLE "CatalogItem" ADD COLUMN "subcategoryCwId" INTEGER;
+
+-- AlterTable: Opportunity
+ALTER TABLE "Opportunity" ADD COLUMN "productSequence" INTEGER[] DEFAULT ARRAY[]::INTEGER[];

prisma/schema.prisma

@@ -34,6 +34,8 @@ model User {
   emailVerified DateTime?
   image         String?
 
+  cwIdentifier String?
+
   userId String  @unique
   token  String?
 
@@ -95,6 +97,11 @@ model CatalogItem {
   linkedItems CatalogItem[] @relation("LinkedItems")
   linkedTo    CatalogItem[] @relation("LinkedItems")
 
+  category        String?
+  categoryCwId    Int?
+  subcategory     String?
+  subcategoryCwId Int?
+
   manufacturer    String?
   manufactureCwId Int?
 
@@ -178,6 +185,10 @@ model Opportunity {
   companyId String?
   company   Company? @relation(fields: [companyId], references: [id])
 
+  // Local product sequence — array of CW forecast item IDs in display order.
+  // When present, fetchProducts() uses this order instead of CW sequenceNumber.
+  productSequence Int[] @default([])
+
   cwLastUpdated DateTime?
 
   createdAt DateTime @default(now())

src/api/companies/[id]/fetch.ts

@@ -5,6 +5,7 @@ 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 { processObjectValuePerms } from "../../../modules/permission-utils/processObjectPermissions";
 
 /* /v1/company/companies/[id] */
 export default createRoute(
@@ -42,13 +43,20 @@ export default createRoute(
       }
     }
 
+    const companyData = company.toJson({
+      includeAddress,
+      includePrimaryContact,
+      includeAllContacts,
+    });
+    const gatedData = await processObjectValuePerms(
+      companyData,
+      "obj.company",
+      c.get("user"),
+    );
+
     const response = apiResponse.successful(
       "Company Fetched Successfully!",
-      company.toJson({
+      gatedData,
-        includeAddress,
-        includePrimaryContact,
-        includeAllContacts,
-      }),
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/companies/[id]/unifiSites.ts

@@ -4,6 +4,7 @@ import { companies } from "../../../managers/companies";
 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";
 
 /* GET /v1/company/companies/:identifier/unifi/sites */
 export default createRoute(
@@ -12,9 +13,16 @@ export default createRoute(
   async (c) => {
     const company = await companies.fetch(c.req.param("identifier"));
     const sites = await unifiSites.fetchByCompany(company.id);
+
+    const gatedData = await Promise.all(
+      sites.map((site) =>
+        processObjectValuePerms(site, "obj.unifiSite", c.get("user")),
+      ),
+    );
+
     const response = apiResponse.successful(
       "Company UniFi Sites Fetched Successfully!",
-      sites,
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/companies/fetchAll.ts

@@ -4,6 +4,7 @@ import { companies } from "../../managers/companies";
 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";
 
 /* /v1/company/companies */
 export default createRoute(
@@ -22,9 +23,15 @@ export default createRoute(
       ? (await companies.search(search, 1, 999999)).length
       : await companies.count();
 
+    const gatedData = await Promise.all(
+      data.map((item) =>
+        processObjectValuePerms(item, "obj.company", c.get("user")),
+      ),
+    );
+
     let response = apiResponse.successful(
       "Companies Fetched Successfully!",
-      data,
+      gatedData,
       {
         pagination: {
           previousPage: page == 1 ? null : page - 1, // Previous Page

src/api/credential-types/fetch.ts

@@ -4,6 +4,7 @@ import { credentialTypes } from "../../managers/credentialTypes";
 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";
 
 /* /v1/credential-type/:identifier */
 export default createRoute(
@@ -15,9 +16,15 @@ export default createRoute(
       c.req.param("identifier"),
     );
 
+    const gatedData = await processObjectValuePerms(
+      credentialType.toJson({ includeCredentialCount: true }),
+      "obj.credentialType",
+      c.get("user"),
+    );
+
     const response = apiResponse.successful(
       "Credential Type Fetched Successfully!",
-      credentialType.toJson({ includeCredentialCount: true }),
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/credential-types/fetchAll.ts

@@ -4,6 +4,7 @@ import { credentialTypes } from "../../managers/credentialTypes";
 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";
 
 /* /v1/credential-type */
 export default createRoute(
@@ -13,11 +14,19 @@ export default createRoute(
   async (c) => {
     const allCredentialTypes = await credentialTypes.fetchAll();
 
+    const gatedData = await Promise.all(
+      allCredentialTypes.map((ct) =>
+        processObjectValuePerms(
+          ct.toJson({ includeCredentialCount: true }),
+          "obj.credentialType",
+          c.get("user"),
+        ),
+      ),
+    );
+
     const response = apiResponse.successful(
       "Credential Types Fetched Successfully!",
-      allCredentialTypes.map((ct) =>
+      gatedData,
-        ct.toJson({ includeCredentialCount: true }),
-      ),
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/credential-types/fetchCredentials.ts

@@ -4,6 +4,7 @@ import { credentialTypes } from "../../managers/credentialTypes";
 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";
 
 /* /v1/credential-type/:id/credentials */
 export default createRoute(
@@ -14,9 +15,15 @@ export default createRoute(
     const credentialType = await credentialTypes.fetch(c.req.param("id"));
     const credentials = await credentialType.fetchCredentials();
 
+    const gatedData = await Promise.all(
+      credentials.map((cred) =>
+        processObjectValuePerms(cred.toJson(), "obj.credential", c.get("user")),
+      ),
+    );
+
     const response = apiResponse.successful(
       "Credentials Fetched Successfully!",
-      credentials.map((cred) => cred.toJson()),
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/credentials/fetch.ts

@@ -4,6 +4,7 @@ import { credentials } from "../../managers/credentials";
 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";
 
 /* /v1/credential/:id */
 export default createRoute(
@@ -12,10 +13,15 @@ export default createRoute(
 
   async (c) => {
     const credential = await credentials.fetch(c.req.param("id"));
+    const gatedData = await processObjectValuePerms(
+      credential.toJson(),
+      "obj.credential",
+      c.get("user"),
+    );
 
     const response = apiResponse.successful(
       "Credential Fetched Successfully!",
-      credential.toJson(),
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/credentials/fetchByCompany.ts

@@ -4,6 +4,7 @@ import { credentials } from "../../managers/credentials";
 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";
 
 /* /v1/credential/company/:companyId */
 export default createRoute(
@@ -15,9 +16,15 @@ export default createRoute(
       c.req.param("companyId"),
     );
 
+    const gatedData = await Promise.all(
+      companyCredentials.map((cred) =>
+        processObjectValuePerms(cred.toJson(), "obj.credential", c.get("user")),
+      ),
+    );
+
     const response = apiResponse.successful(
       "Company Credentials Fetched Successfully!",
-      companyCredentials.map((cred) => cred.toJson()),
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/credentials/fetchSubCredentials.ts

@@ -3,6 +3,7 @@ import { credentials } from "../../managers/credentials";
 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";
 
 /* GET /v1/credential/credentials/:id/sub-credentials */
 export default createRoute(
@@ -17,9 +18,15 @@ export default createRoute(
 
     const subCredentials = await credentials.fetchSubCredentials(parentId);
 
+    const gatedData = await Promise.all(
+      subCredentials.map((sc) =>
+        processObjectValuePerms(sc.toJson(), "obj.credential", c.get("user")),
+      ),
+    );
+
     const response = apiResponse.successful(
       "Sub-Credentials Fetched Successfully!",
-      subCredentials.map((sc) => sc.toJson()),
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/procurement/[id]/fetch.ts

@@ -3,6 +3,7 @@ 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 { processObjectValuePerms } from "../../../modules/permission-utils/processObjectPermissions";
 
 /* /v1/procurement/items/:identifier */
 export default createRoute(
@@ -14,9 +15,15 @@ export default createRoute(
 
     const item = await procurement.fetchItem(identifier);
 
+    const gatedData = await processObjectValuePerms(
+      item.toJson({ includeLinkedItems }),
+      "obj.catalogItem",
+      c.get("user"),
+    );
+
     const response = apiResponse.successful(
       "Catalog item fetched successfully!",
-      item.toJson({ includeLinkedItems }),
+      gatedData,
     );
 
     return c.json(response, response.status as ContentfulStatusCode);

src/api/procurement/[id]/fetchLinked.ts

@@ -3,6 +3,7 @@ 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 { processObjectValuePerms } from "../../../modules/permission-utils/processObjectPermissions";
 
 /* GET /v1/procurement/items/:identifier/linked */
 export default createRoute(
@@ -14,9 +15,15 @@ export default createRoute(
 
     const linkedItems = item.getLinkedItems().map((linked) => linked.toJson());
 
+    const gatedData = await Promise.all(
+      linkedItems.map((linked) =>
+        processObjectValuePerms(linked, "obj.catalogItem", c.get("user")),
+      ),
+    );
+
     const response = apiResponse.successful(
       "Linked catalog items fetched successfully!",
-      linkedItems,
+      gatedData,
     );
 
     return c.json(response, response.status as ContentfulStatusCode);

src/api/procurement/categories.ts

@@ -0,0 +1,26 @@
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import {
+  serializeCategoryTree,
+  serializeEcosystemTree,
+} from "../../modules/catalog-categories/catalogCategories";
+
+/* /v1/procurement/categories */
+export default createRoute(
+  "get",
+  ["/categories"],
+  async (c) => {
+    const categories = serializeCategoryTree();
+    const ecosystems = serializeEcosystemTree();
+
+    const response = apiResponse.successful(
+      "Category and ecosystem data fetched successfully!",
+      { categories, ecosystems },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["procurement.catalog.fetch.many"] }),
+);

src/api/procurement/fetchAll.ts

@@ -1,8 +1,9 @@
 import { createRoute } from "../../modules/api-utils/createRoute";
-import { procurement } from "../../managers/procurement";
+import { procurement, CatalogFilterOpts } from "../../managers/procurement";
 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";
 
 /* /v1/procurement/items */
 export default createRoute(
@@ -14,17 +15,53 @@ export default createRoute(
     const search = c.req.query("search") as string;
     const includeInactive = c.req.query("includeInactive") === "true";
 
-    const data = search
+    // Category / filter params
-      ? await procurement.search(search, page, rpp, { includeInactive })
+    const category = c.req.query("category") as string | undefined;
-      : await procurement.fetchPages(page, rpp, { includeInactive });
+    const subcategory = c.req.query("subcategory") as string | undefined;
+    const group = c.req.query("group") as string | undefined;
+    const manufacturer = c.req.query("manufacturer") as string | undefined;
+    const ecosystem = c.req.query("ecosystem") as string | undefined;
+    const inStock = c.req.query("inStock") === "true" ? true : undefined;
+    const minPrice = c.req.query("minPrice")
+      ? Number(c.req.query("minPrice"))
+      : undefined;
+    const maxPrice = c.req.query("maxPrice")
+      ? Number(c.req.query("maxPrice"))
+      : undefined;
 
-    const totalRecords = await procurement.count({
+    const filterOpts: CatalogFilterOpts = {
-      activeOnly: !includeInactive,
+      includeInactive,
-    });
+      category,
+      subcategory,
+      group,
+      manufacturer,
+      ecosystem,
+      inStock,
+      minPrice,
+      maxPrice,
+    };
+
+    const data = search
+      ? await procurement.search(search, page, rpp, filterOpts)
+      : await procurement.fetchPages(page, rpp, filterOpts);
+
+    const totalRecords = search
+      ? await procurement.countSearch(search, filterOpts)
+      : await procurement.count(filterOpts);
+
+    const gatedData = await Promise.all(
+      data.map((item) =>
+        processObjectValuePerms(
+          item.toJson(),
+          "obj.catalogItem",
+          c.get("user"),
+        ),
+      ),
+    );
 
     const response = apiResponse.successful(
       "Catalog items fetched successfully!",
-      data.map((item) => item.toJson()),
+      gatedData,
       {
         pagination: {
           previousPage: page <= 1 ? null : page - 1,

src/api/procurement/filters.ts

@@ -0,0 +1,32 @@
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { procurement } from "../../managers/procurement";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+
+/* /v1/procurement/filters */
+export default createRoute(
+  "get",
+  ["/filters"],
+  async (c) => {
+    const category = c.req.query("category") as string | undefined;
+    const subcategory = c.req.query("subcategory") as string | undefined;
+    const includeInactive = c.req.query("includeInactive") === "true";
+
+    const filterOpts = { category, subcategory, includeInactive };
+
+    const [categories, subcategories, manufacturers] = await Promise.all([
+      procurement.fetchDistinctValues("category", filterOpts),
+      procurement.fetchDistinctValues("subcategory", filterOpts),
+      procurement.fetchDistinctValues("manufacturer", filterOpts),
+    ]);
+
+    const response = apiResponse.successful(
+      "Available filter values fetched successfully!",
+      { categories, subcategories, manufacturers },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["procurement.catalog.fetch.many"] }),
+);

src/api/procurement/index.ts

@@ -5,5 +5,17 @@ import { default as link } from "./[id]/link";
 import { default as unlink } from "./[id]/unlink";
 import { default as fetchLinked } from "./[id]/fetchLinked";
 import { default as count } from "./count";
+import { default as categories } from "./categories";
+import { default as filters } from "./filters";
 
-export { count, fetch, fetchAll, fetchLinked, link, refreshInventory, unlink };
+export {
+  categories,
+  count,
+  fetch,
+  fetchAll,
+  fetchLinked,
+  filters,
+  link,
+  refreshInventory,
+  unlink,
+};

src/api/roles/fetch.ts

@@ -4,6 +4,7 @@ import { roles } from "../../managers/roles";
 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";
 
 /* GET /v1/role/:identifier */
 export default createRoute(
@@ -15,9 +16,15 @@ export default createRoute(
 
     const role = await roles.fetch(identifier);
 
+    const gatedData = await processObjectValuePerms(
+      role.toJson({ viewPermissions: true }),
+      "obj.role",
+      c.get("user"),
+    );
+
     const response = apiResponse.successful(
       "Role Fetched Successfully!",
-      role.toJson({ viewPermissions: true }),
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/roles/fetchAll.ts

@@ -4,6 +4,7 @@ import { roles } from "../../managers/roles";
 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";
 
 /* GET /v1/role */
 export default createRoute(
@@ -13,13 +14,19 @@ export default createRoute(
   async (c) => {
     const allRoles = await roles.fetchAllRoles();
 
-    const rolesArray = allRoles.map((role) =>
+    const gatedData = await Promise.all(
-      role.toJson({ viewPermissions: true }),
+      allRoles.map((role) =>
+        processObjectValuePerms(
+          role.toJson({ viewPermissions: true }),
+          "obj.role",
+          c.get("user"),
+        ),
+      ),
     );
 
     const response = apiResponse.successful(
       "Roles Fetched Successfully!",
-      rolesArray,
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/roles/getUsers.ts

@@ -4,6 +4,7 @@ import { roles } from "../../managers/roles";
 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";
 
 /* GET /v1/role/:identifier/users */
 export default createRoute(
@@ -16,11 +17,15 @@ export default createRoute(
     const role = await roles.fetch(identifier);
     const users = role.getUsers();
 
-    const usersArray = users.map((user) => user.toJson());
+    const gatedData = await Promise.all(
+      users.map((user) =>
+        processObjectValuePerms(user.toJson(), "obj.user", c.get("user")),
+      ),
+    );
 
     const response = apiResponse.successful(
       "Users Fetched Successfully!",
-      usersArray,
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

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]/contacts.ts

@@ -3,7 +3,6 @@ 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 { opportunityCw } from "../../../modules/cw-utils/opportunities/opportunities";
 
 /* GET /v1/sales/opportunities/:identifier/contacts */
 export default createRoute(
@@ -13,22 +12,7 @@ export default createRoute(
     const identifier = c.req.param("identifier");
     const item = await opportunities.fetchItem(identifier);
 
-    const contacts = await opportunityCw.fetchContacts(item.cwOpportunityId);
+    const data = await item.fetchContacts();
-
-    const data = contacts.map((ct) => ({
-      id: ct.id,
-      contact: ct.contact ? { id: ct.contact.id, name: ct.contact.name } : null,
-      company: ct.company
-        ? {
-            id: ct.company.id,
-            identifier: ct.company.identifier,
-            name: ct.company.name,
-          }
-        : null,
-      role: ct.role ? { id: ct.role.id, name: ct.role.name } : null,
-      notes: ct.notes,
-      referralFlag: ct.referralFlag,
-    }));
 
     const response = apiResponse.successful(
       "Opportunity contacts fetched successfully!",

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

@@ -0,0 +1,47 @@
+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 { resolveMember } from "../../../modules/cw-utils/members/memberCache";
+import { z } from "zod";
+
+/* POST /v1/sales/opportunities/:identifier/notes */
+export default createRoute(
+  "post",
+  ["/opportunities/:identifier/notes"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const body = await c.req.json();
+
+    const schema = z.object({
+      text: z.string().min(1, "Note text is required"),
+      flagged: z.boolean().optional(),
+    });
+
+    const data = schema.parse(body);
+
+    const item = await opportunities.fetchItem(identifier);
+    const user = c.get("user");
+
+    const created = await item.addNote(data.text, user.login, {
+      flagged: data.flagged,
+    });
+
+    const response = apiResponse.created(
+      "Opportunity note created successfully!",
+      {
+        id: created.id,
+        text: created.text,
+        type: created.type
+          ? { id: created.type.id, name: created.type.name }
+          : null,
+        flagged: created.flagged,
+        enteredBy: await resolveMember(created.enteredBy),
+      },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.note.create"] }),
+);

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

@@ -0,0 +1,33 @@
+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";
+
+/* DELETE /v1/sales/opportunities/:identifier/notes/:noteId */
+export default createRoute(
+  "delete",
+  ["/opportunities/:identifier/notes/:noteId"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const noteId = Number(c.req.param("noteId"));
+
+    if (isNaN(noteId))
+      throw new GenericError({
+        status: 400,
+        name: "InvalidNoteId",
+        message: "Note ID must be a number",
+      });
+
+    const item = await opportunities.fetchItem(identifier);
+    await item.deleteNote(noteId);
+
+    const response = apiResponse.successful(
+      "Opportunity note deleted successfully!",
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.note.delete"] }),
+);

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

@@ -3,6 +3,7 @@ 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";
 
 /* GET /v1/sales/opportunities/:identifier */
 export default createRoute(
@@ -13,9 +14,18 @@ export default createRoute(
 
     const item = await opportunities.fetchItem(identifier);
 
+    // Eagerly load site data so toJson() includes full site info
+    await item.fetchSite();
+
+    const gatedData = await processObjectValuePerms(
+      item.toJson(),
+      "obj.opportunity",
+      c.get("user"),
+    );
+
     const response = apiResponse.successful(
       "Opportunity fetched successfully!",
-      item.toJson(),
+      gatedData,
     );
 
     return c.json(response, response.status as ContentfulStatusCode);

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

@@ -0,0 +1,34 @@
+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";
+
+/* GET /v1/sales/opportunities/:identifier/notes/:noteId */
+export default createRoute(
+  "get",
+  ["/opportunities/:identifier/notes/:noteId"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const noteId = Number(c.req.param("noteId"));
+
+    if (isNaN(noteId))
+      throw new GenericError({
+        status: 400,
+        name: "InvalidNoteId",
+        message: "Note ID must be a number",
+      });
+
+    const item = await opportunities.fetchItem(identifier);
+    const data = await item.fetchNote(noteId);
+
+    const response = apiResponse.successful(
+      "Opportunity note fetched successfully!",
+      data,
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.fetch"] }),
+);

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

@@ -1,39 +0,0 @@
-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 { opportunityCw } from "../../../modules/cw-utils/opportunities/opportunities";
-
-/* GET /v1/sales/opportunities/:identifier/forecasts */
-export default createRoute(
-  "get",
-  ["/opportunities/:identifier/forecasts"],
-  async (c) => {
-    const identifier = c.req.param("identifier");
-    const item = await opportunities.fetchItem(identifier);
-
-    const forecasts = await opportunityCw.fetchForecasts(item.cwOpportunityId);
-
-    const data = forecasts.map((f) => ({
-      id: f.id,
-      forecastType: f.forecastType,
-      forecastMonth: f.forecastMonth,
-      revenue: f.revenue,
-      cost: f.cost,
-      forecastPercentage: f.forecastPercentage,
-      status: f.status ? { id: f.status.id, name: f.status.name } : null,
-      includedFlag: f.includedFlag,
-      linkedFlag: f.linkedFlag,
-      recurringFlag: f.recurringFlag,
-    }));
-
-    const response = apiResponse.successful(
-      "Opportunity forecasts fetched successfully!",
-      data,
-    );
-
-    return c.json(response, response.status as ContentfulStatusCode);
-  },
-  authMiddleware({ permissions: ["sales.opportunity.fetch"] }),
-);

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

@@ -3,7 +3,6 @@ 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 { opportunityCw } from "../../../modules/cw-utils/opportunities/opportunities";
 
 /* GET /v1/sales/opportunities/:identifier/notes */
 export default createRoute(
@@ -13,15 +12,7 @@ export default createRoute(
     const identifier = c.req.param("identifier");
     const item = await opportunities.fetchItem(identifier);
 
-    const notes = await opportunityCw.fetchNotes(item.cwOpportunityId);
+    const data = await item.fetchNotes();
-
-    const data = notes.map((n) => ({
-      id: n.id,
-      text: n.text,
-      type: n.type ? { id: n.type.id, name: n.type.name } : null,
-      flagged: n.flagged,
-      enteredBy: n.enteredBy,
-    }));
 
     const response = apiResponse.successful(
       "Opportunity notes fetched successfully!",

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

@@ -0,0 +1,25 @@
+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";
+
+/* GET /v1/sales/opportunities/:identifier/products */
+export default createRoute(
+  "get",
+  ["/opportunities/:identifier/products"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const item = await opportunities.fetchItem(identifier);
+
+    const data = await item.fetchProducts();
+
+    const response = apiResponse.successful(
+      "Opportunity products fetched successfully!",
+      data.map((p) => p.toJson()),
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.fetch"] }),
+);

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

@@ -0,0 +1,37 @@
+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 { z } from "zod";
+
+/* PATCH /v1/sales/opportunities/:identifier/products/sequence */
+export default createRoute(
+  "patch",
+  ["/opportunities/:identifier/products/sequence"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const body = await c.req.json();
+
+    const schema = z.object({
+      orderedIds: z
+        .array(z.number().int().positive())
+        .min(1, "At least one forecast item ID is required"),
+    });
+
+    const { orderedIds } = schema.parse(body);
+
+    const item = await opportunities.fetchItem(identifier);
+    const updated = await item.resequenceProducts(orderedIds);
+
+    const response = apiResponse.successful(
+      "Product sequence updated successfully!",
+      {
+        products: updated.map((p) => p.toJson()),
+      },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.product.update"] }),
+);

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

@@ -0,0 +1,57 @@
+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 { resolveMember } from "../../../modules/cw-utils/members/memberCache";
+import { z } from "zod";
+
+/* PATCH /v1/sales/opportunities/:identifier/notes/:noteId */
+export default createRoute(
+  "patch",
+  ["/opportunities/:identifier/notes/:noteId"],
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const noteId = Number(c.req.param("noteId"));
+
+    if (isNaN(noteId))
+      throw new GenericError({
+        status: 400,
+        name: "InvalidNoteId",
+        message: "Note ID must be a number",
+      });
+
+    const body = await c.req.json();
+
+    const schema = z
+      .object({
+        text: z.string().min(1).optional(),
+        flagged: z.boolean().optional(),
+      })
+      .refine((d) => d.text !== undefined || d.flagged !== undefined, {
+        message: "At least one of 'text' or 'flagged' must be provided",
+      });
+
+    const data = schema.parse(body);
+
+    const item = await opportunities.fetchItem(identifier);
+    const updated = await item.updateNote(noteId, data);
+
+    const response = apiResponse.successful(
+      "Opportunity note updated successfully!",
+      {
+        id: updated.id,
+        text: updated.text,
+        type: updated.type
+          ? { id: updated.type.id, name: updated.type.name }
+          : null,
+        flagged: updated.flagged,
+        enteredBy: await resolveMember(updated.enteredBy),
+      },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.note.update"] }),
+);

src/api/sales/fetchAll.ts

@@ -3,6 +3,7 @@ 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";
 
 /* GET /v1/sales/opportunities */
 export default createRoute(
@@ -18,13 +19,23 @@ export default createRoute(
       ? await opportunities.search(search, page, rpp, { includeClosed })
       : await opportunities.fetchPages(page, rpp, { includeClosed });
 
-    const totalRecords = await opportunities.count({
+    const totalRecords = search
-      openOnly: !includeClosed,
+      ? await opportunities.searchCount(search, { includeClosed })
-    });
+      : await opportunities.count({ openOnly: !includeClosed });
+
+    const gatedData = await Promise.all(
+      data.map((item) =>
+        processObjectValuePerms(
+          item.toJson(),
+          "obj.opportunity",
+          c.get("user"),
+        ),
+      ),
+    );
 
     const response = apiResponse.successful(
       "Opportunities fetched successfully!",
-      data.map((item) => item.toJson()),
+      gatedData,
       {
         pagination: {
           previousPage: page <= 1 ? null : page - 1,

src/api/sales/fetchOpportunityTypes.ts

@@ -0,0 +1,20 @@
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { QUOTE_STATUSES } from "../../types/QuoteStatuses";
+
+/* GET /v1/sales/opportunity-types */
+export default createRoute(
+  "get",
+  ["/opportunity-types"],
+
+  async (c) => {
+    const response = apiResponse.successful(
+      "Opportunity Types Fetched Successfully!",
+      QUOTE_STATUSES,
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["sales.opportunity.fetch.many"] }),
+);

src/api/sales/index.ts

@@ -1,9 +1,31 @@
 import { default as fetchAll } from "./fetchAll";
+import { default as fetchOpportunityTypes } from "./fetchOpportunityTypes";
 import { default as count } from "./count";
 import { default as fetch } from "./[id]/fetch";
 import { default as refresh } from "./[id]/refresh";
-import { default as forecasts } from "./[id]/forecasts";
+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";
+import { default as createNote } from "./[id]/createNote";
+import { default as updateNote } from "./[id]/updateNote";
+import { default as deleteNote } from "./[id]/deleteNote";
 import { default as contacts } from "./[id]/contacts";
 
-export { count, fetch, fetchAll, forecasts, notes, contacts, refresh };
+export {
+  addProduct,
+  count,
+  fetch,
+  fetchAll,
+  fetchOpportunityTypes,
+  products,
+  resequenceProducts,
+  notes,
+  fetchNote,
+  createNote,
+  updateNote,
+  deleteNote,
+  contacts,
+  refresh,
+};

src/api/unifi/site/fetch.ts

@@ -3,6 +3,7 @@ import { unifiSites } from "../../../managers/unifiSites";
 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";
 
 /* GET /v1/unifi/site/:id */
 export default createRoute(
@@ -10,9 +11,16 @@ export default createRoute(
   ["/site/:id"],
   async (c) => {
     const site = await unifiSites.fetch(c.req.param("id"));
+
+    const gatedData = await processObjectValuePerms(
+      site,
+      "obj.unifiSite",
+      c.get("user"),
+    );
+
     const response = apiResponse.successful(
       "UniFi Site Fetched Successfully!",
-      site,
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/unifi/sites/fetchAll.ts

@@ -3,6 +3,7 @@ import { unifiSites } from "../../../managers/unifiSites";
 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";
 
 /* GET /v1/unifi/sites */
 export default createRoute(
@@ -10,9 +11,16 @@ export default createRoute(
   ["/sites"],
   async (c) => {
     const sites = await unifiSites.fetchAll();
+
+    const gatedData = await Promise.all(
+      sites.map((site) =>
+        processObjectValuePerms(site, "obj.unifiSite", c.get("user")),
+      ),
+    );
+
     const response = apiResponse.successful(
       "UniFi Sites Fetched Successfully!",
-      sites,
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/user/@me/fetch.ts

@@ -2,16 +2,20 @@ import { ContentfulStatusCode } from "hono/utils/http-status";
 import { apiResponse } from "../../../modules/api-utils/apiResponse";
 import { createRoute } from "../../../modules/api-utils/createRoute";
 import { authMiddleware } from "../../middleware/authorization";
+import { processObjectValuePerms } from "../../../modules/permission-utils/processObjectPermissions";
 
 // /v1/user/@me
 export default createRoute(
   "get",
   ["/@me"],
-  (c) => {
+  async (c) => {
-    const response = apiResponse.successful(
+    const gatedData = await processObjectValuePerms(
-      "Fetched user.",
       c.get("user")?.toJson(),
+      "obj.user",
+      c.get("user"),
     );
+
+    const response = apiResponse.successful("Fetched user.", gatedData);
     return c.json(response, response.status as ContentfulStatusCode);
   },
   authMiddleware({ scopes: ["user.read"] }),

src/api/user/fetch.ts

@@ -4,6 +4,7 @@ import { createRoute } from "../../modules/api-utils/createRoute";
 import { authMiddleware } from "../middleware/authorization";
 import { users } from "../../managers/users";
 import GenericError from "../../Errors/GenericError";
+import { processObjectValuePerms } from "../../modules/permission-utils/processObjectPermissions";
 
 /* GET /v1/user/users/:identifier */
 export default createRoute(
@@ -21,9 +22,15 @@ export default createRoute(
         status: 404,
       });
 
+    const gatedData = await processObjectValuePerms(
+      user.toJson(),
+      "obj.user",
+      c.get("user"),
+    );
+
     const response = apiResponse.successful(
       "User Fetched Successfully!",
-      user.toJson(),
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/user/fetchAll.ts

@@ -3,6 +3,7 @@ import { apiResponse } from "../../modules/api-utils/apiResponse";
 import { createRoute } from "../../modules/api-utils/createRoute";
 import { authMiddleware } from "../middleware/authorization";
 import { users } from "../../managers/users";
+import { processObjectValuePerms } from "../../modules/permission-utils/processObjectPermissions";
 
 /* GET /v1/user/users */
 export default createRoute(
@@ -11,11 +12,16 @@ export default createRoute(
 
   async (c) => {
     const allUsers = await users.fetchAllUsers();
-    const usersArray = allUsers.map((u) => u.toJson());
+
+    const gatedData = await Promise.all(
+      allUsers.map((u) =>
+        processObjectValuePerms(u.toJson(), "obj.user", c.get("user")),
+      ),
+    );
 
     const response = apiResponse.successful(
       "Users Fetched Successfully!",
-      usersArray,
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/user/fetchRoles.ts

@@ -4,6 +4,7 @@ import { createRoute } from "../../modules/api-utils/createRoute";
 import { authMiddleware } from "../middleware/authorization";
 import { users } from "../../managers/users";
 import GenericError from "../../Errors/GenericError";
+import { processObjectValuePerms } from "../../modules/permission-utils/processObjectPermissions";
 
 /* GET /v1/user/users/:identifier/roles */
 export default createRoute(
@@ -22,11 +23,20 @@ export default createRoute(
       });
 
     const roles = await user.fetchRoles();
-    const rolesArray = roles.map((r) => r.toJson({ viewPermissions: true }));
+
+    const gatedData = await Promise.all(
+      roles.map((r) =>
+        processObjectValuePerms(
+          r.toJson({ viewPermissions: true }),
+          "obj.role",
+          c.get("user"),
+        ),
+      ),
+    );
 
     const response = apiResponse.successful(
       "User Roles Fetched Successfully!",
-      rolesArray,
+      gatedData,
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/constants.ts

@@ -6,6 +6,7 @@ import { Server } from "socket.io";
 import { Server as Engine } from "@socket.io/bun-engine";
 import axios from "axios";
 import { UnifiClient } from "./modules/unifi-api/UnifiClient";
+import Redis from "ioredis";
 
 const connectionString = `${process.env.DATABASE_URL}`;
 const adapter = new PrismaPg({ connectionString });
@@ -22,6 +23,10 @@ export const API_BASE_URL =
 
 export const prisma = new PrismaClient({ adapter });
 
+// Redis Client
+
+export const redis = new Redis(process.env.REDIS_URL!);
+
 export const sessionDuration = 30 * 24 * 60 * 60000;
 export const accessTokenDuration = "10min";
 export const refreshTokenDuration = "30d";

src/controllers/ActivityController.ts

@@ -0,0 +1,252 @@
+import {
+  CWActivity,
+  CWActivityCustomField,
+  CWPatchOperation,
+  CWCreateActivity,
+} from "../modules/cw-utils/activities/activity.types";
+import { activityCw } from "../modules/cw-utils/activities/activities";
+import { fetchActivity } from "../modules/cw-utils/activities/fetchActivity";
+
+/**
+ * Activity Controller
+ *
+ * Domain model class that encapsulates a ConnectWise Activity entity.
+ * Activities are not persisted locally — all data is sourced directly
+ * from the ConnectWise API.
+ */
+export class ActivityController {
+  public readonly cwActivityId: number;
+  public name: string;
+  public notes: string | null;
+
+  public typeName: string | null;
+  public typeCwId: number | null;
+  public statusName: string | null;
+  public statusCwId: number | null;
+
+  public companyCwId: number | null;
+  public companyName: string | null;
+  public companyIdentifier: string | null;
+  public contactCwId: number | null;
+  public contactName: string | null;
+
+  public phoneNumber: string | null;
+  public email: string | null;
+
+  public opportunityCwId: number | null;
+  public opportunityName: string | null;
+  public ticketCwId: number | null;
+  public ticketName: string | null;
+  public agreementCwId: number | null;
+  public agreementName: string | null;
+  public campaignCwId: number | null;
+  public campaignName: string | null;
+
+  public assignToCwId: number | null;
+  public assignToName: string | null;
+  public assignToIdentifier: string | null;
+
+  public scheduleStatusCwId: number | null;
+  public scheduleStatusName: string | null;
+  public reminderCwId: number | null;
+  public reminderName: string | null;
+  public whereCwId: number | null;
+  public whereName: string | null;
+
+  public dateStart: Date | null;
+  public dateEnd: Date | null;
+  public notifyFlag: boolean;
+
+  public currencyCwId: number | null;
+  public currencyName: string | null;
+
+  public mobileGuid: string | null;
+  public customFields: CWActivityCustomField[];
+
+  public cwLastUpdated: Date | null;
+  public cwDateEntered: Date | null;
+  public cwEnteredBy: string | null;
+  public cwUpdatedBy: string | null;
+
+  constructor(data: CWActivity) {
+    this.cwActivityId = data.id;
+    this.name = data.name;
+    this.notes = data.notes ?? null;
+
+    this.typeName = data.type?.name ?? null;
+    this.typeCwId = data.type?.id ?? null;
+    this.statusName = data.status?.name ?? null;
+    this.statusCwId = data.status?.id ?? null;
+
+    this.companyCwId = data.company?.id ?? null;
+    this.companyName = data.company?.name ?? null;
+    this.companyIdentifier = data.company?.identifier ?? null;
+    this.contactCwId = data.contact?.id ?? null;
+    this.contactName = data.contact?.name ?? null;
+
+    this.phoneNumber = data.phoneNumber ?? null;
+    this.email = data.email ?? null;
+
+    this.opportunityCwId = data.opportunity?.id ?? null;
+    this.opportunityName = data.opportunity?.name ?? null;
+    this.ticketCwId = data.ticket?.id ?? null;
+    this.ticketName = data.ticket?.name ?? null;
+    this.agreementCwId = data.agreement?.id ?? null;
+    this.agreementName = data.agreement?.name ?? null;
+    this.campaignCwId = data.campaign?.id ?? null;
+    this.campaignName = data.campaign?.name ?? null;
+
+    this.assignToCwId = data.assignTo?.id ?? null;
+    this.assignToName = data.assignTo?.name ?? null;
+    this.assignToIdentifier = data.assignTo?.identifier ?? null;
+
+    this.scheduleStatusCwId = data.scheduleStatus?.id ?? null;
+    this.scheduleStatusName = data.scheduleStatus?.name ?? null;
+    this.reminderCwId = data.reminder?.id ?? null;
+    this.reminderName = data.reminder?.name ?? null;
+    this.whereCwId = data.where?.id ?? null;
+    this.whereName = data.where?.name ?? null;
+
+    this.dateStart = data.dateStart ? new Date(data.dateStart) : null;
+    this.dateEnd = data.dateEnd ? new Date(data.dateEnd) : null;
+    this.notifyFlag = data.notifyFlag ?? false;
+
+    this.currencyCwId = data.currency?.id ?? null;
+    this.currencyName = data.currency?.name ?? null;
+
+    this.mobileGuid = data.mobileGuid ?? null;
+    this.customFields = data.customFields ?? [];
+
+    this.cwLastUpdated = data._info?.lastUpdated
+      ? new Date(data._info.lastUpdated)
+      : null;
+    this.cwDateEntered = data._info?.dateEntered
+      ? new Date(data._info.dateEntered)
+      : null;
+    this.cwEnteredBy = data._info?.enteredBy ?? null;
+    this.cwUpdatedBy = data._info?.updatedBy ?? null;
+  }
+
+  /**
+   * Refresh from ConnectWise
+   *
+   * Fetches the latest activity data from CW and returns
+   * a new ActivityController instance with updated state.
+   */
+  public async refreshFromCW(): Promise<ActivityController> {
+    const cwData = await fetchActivity(this.cwActivityId);
+    return new ActivityController(cwData);
+  }
+
+  /**
+   * Fetch raw CW data
+   *
+   * Returns the raw ConnectWise activity object.
+   */
+  public async fetchCwData(): Promise<CWActivity> {
+    return fetchActivity(this.cwActivityId);
+  }
+
+  /**
+   * Update in ConnectWise
+   *
+   * Applies JSON Patch operations to this activity in ConnectWise
+   * and returns a new controller with the updated data.
+   */
+  public async update(
+    operations: CWPatchOperation[],
+  ): Promise<ActivityController> {
+    const updated = await activityCw.update(this.cwActivityId, operations);
+    return new ActivityController(updated);
+  }
+
+  /**
+   * Delete from ConnectWise
+   *
+   * Deletes this activity in ConnectWise.
+   */
+  public async delete(): Promise<void> {
+    await activityCw.delete(this.cwActivityId);
+  }
+
+  /**
+   * Create Activity (static factory)
+   *
+   * Creates a new activity in ConnectWise and returns a controller instance.
+   */
+  public static async create(
+    data: CWCreateActivity,
+  ): Promise<ActivityController> {
+    const created = await activityCw.create(data);
+    return new ActivityController(created);
+  }
+
+  /**
+   * To JSON
+   *
+   * Serializes the activity into a safe, API-friendly object.
+   */
+  public toJson(): Record<string, any> {
+    return {
+      cwActivityId: this.cwActivityId,
+      name: this.name,
+      notes: this.notes,
+      type: this.typeCwId ? { id: this.typeCwId, name: this.typeName } : null,
+      status: this.statusCwId
+        ? { id: this.statusCwId, name: this.statusName }
+        : null,
+      company: this.companyCwId
+        ? {
+            id: this.companyCwId,
+            identifier: this.companyIdentifier,
+            name: this.companyName,
+          }
+        : null,
+      contact: this.contactCwId
+        ? { id: this.contactCwId, name: this.contactName }
+        : null,
+      phoneNumber: this.phoneNumber,
+      email: this.email,
+      opportunity: this.opportunityCwId
+        ? { id: this.opportunityCwId, name: this.opportunityName }
+        : null,
+      ticket: this.ticketCwId
+        ? { id: this.ticketCwId, name: this.ticketName }
+        : null,
+      agreement: this.agreementCwId
+        ? { id: this.agreementCwId, name: this.agreementName }
+        : null,
+      campaign: this.campaignCwId
+        ? { id: this.campaignCwId, name: this.campaignName }
+        : null,
+      assignTo: this.assignToCwId
+        ? {
+            id: this.assignToCwId,
+            identifier: this.assignToIdentifier,
+            name: this.assignToName,
+          }
+        : null,
+      scheduleStatus: this.scheduleStatusCwId
+        ? { id: this.scheduleStatusCwId, name: this.scheduleStatusName }
+        : null,
+      reminder: this.reminderCwId
+        ? { id: this.reminderCwId, name: this.reminderName }
+        : null,
+      where: this.whereCwId
+        ? { id: this.whereCwId, name: this.whereName }
+        : null,
+      dateStart: this.dateStart,
+      dateEnd: this.dateEnd,
+      notifyFlag: this.notifyFlag,
+      currency: this.currencyCwId
+        ? { id: this.currencyCwId, name: this.currencyName }
+        : null,
+      mobileGuid: this.mobileGuid,
+      customFields: this.customFields,
+      cwLastUpdated: this.cwLastUpdated,
+      cwDateEntered: this.cwDateEntered,
+      cwEnteredBy: this.cwEnteredBy,
+      cwUpdatedBy: this.cwUpdatedBy,
+    };
+  }
+}

src/controllers/CatalogItemController.ts

@@ -21,6 +21,11 @@ export class CatalogItemController {
   public readonly cwCatalogId: number;
   public readonly identifier: string | null;
 
+  public category: string | null;
+  public categoryCwId: number | null;
+  public subcategory: string | null;
+  public subcategoryCwId: number | null;
+
   public manufacturer: string | null;
   public manufactureCwId: number | null;
   public partNumber: string | null;
@@ -55,6 +60,10 @@ export class CatalogItemController {
     this.internalNotes = itemData.internalNotes;
     this.cwCatalogId = itemData.cwCatalogId;
     this.identifier = itemData.identifier;
+    this.category = itemData.category;
+    this.categoryCwId = itemData.categoryCwId;
+    this.subcategory = itemData.subcategory;
+    this.subcategoryCwId = itemData.subcategoryCwId;
     this.manufacturer = itemData.manufacturer;
     this.manufactureCwId = itemData.manufactureCwId;
     this.partNumber = itemData.partNumber;
@@ -196,6 +205,10 @@ export class CatalogItemController {
       description: this.description,
       customerDescription: this.customerDescription,
       internalNotes: this.internalNotes,
+      category: this.category,
+      categoryCwId: this.categoryCwId,
+      subcategory: this.subcategory,
+      subcategoryCwId: this.subcategoryCwId,
       manufacturer: this.manufacturer,
       manufactureCwId: this.manufactureCwId,
       partNumber: this.partNumber,

src/controllers/CompanyController.ts

@@ -1,7 +1,13 @@
 import { Company } from "../../generated/prisma/client";
+import { connectWiseApi } from "../constants";
 import { fetchCwCompanyById } from "../modules/cw-utils/fetchCompany";
 import { fetchCompanyConfigurations } from "../modules/cw-utils/configurations/fetchCompanyConfigurations";
 import { updateCwInternalCompany } from "../modules/cw-utils/updateCompany";
+import {
+  fetchCompanySites,
+  fetchCompanySite,
+  serializeCwSite,
+} from "../modules/cw-utils/sites/companySites";
 import { Company as CWCompany, Contact } from "../types/ConnectWiseTypes";
 
 /**
@@ -16,7 +22,7 @@ export class CompanyController {
   public name: string;
   public readonly cw_Identifier: string;
   public readonly cw_CompanyId: number;
-  public readonly cw_Data?: {
+  public cw_Data?: {
     company: CWCompany;
     defaultContact: Contact | null;
     allContacts: Contact[];
@@ -30,6 +36,38 @@ export class CompanyController {
     this.cw_Data = cwData;
   }
 
+  /**
+   * Hydrate CW Data
+   *
+   * Fetches and populates the full ConnectWise company data
+   * (company, default contact, all contacts) if not already loaded.
+   *
+   * @returns {ThisType}
+   */
+  public async hydrateCwData() {
+    if (this.cw_Data) return this;
+
+    const cwCompany = await fetchCwCompanyById(this.cw_CompanyId);
+    if (!cwCompany) return this;
+
+    const contactHref = cwCompany.defaultContact?._info?.contact_href;
+    const defaultContactData = contactHref
+      ? await connectWiseApi.get(contactHref)
+      : undefined;
+
+    const allContactsData = await connectWiseApi.get(
+      `${cwCompany._info.contacts_href}&pageSize=1000`,
+    );
+
+    this.cw_Data = {
+      company: cwCompany,
+      defaultContact: defaultContactData?.data ?? null,
+      allContacts: allContactsData.data,
+    };
+
+    return this;
+  }
+
   /**
    * Refresh Internal Company Data from ConnectWise
    *
@@ -71,6 +109,30 @@ export class CompanyController {
     return data;
   }
 
+  /**
+   * Fetch Company Sites
+   *
+   * Retrieves all sites for this company from ConnectWise
+   * and returns them as serialized site objects.
+   */
+  public async fetchSites() {
+    const sites = await fetchCompanySites(this.cw_CompanyId);
+    return sites.map(serializeCwSite);
+  }
+
+  /**
+   * Fetch Company Site by ID
+   *
+   * Retrieves a single site by its ConnectWise site ID
+   * and returns a serialized site object.
+   *
+   * @param cwSiteId - The ConnectWise site ID
+   */
+  public async fetchSite(cwSiteId: number) {
+    const site = await fetchCompanySite(this.cw_CompanyId, cwSiteId);
+    return serializeCwSite(site);
+  }
+
   public toJson(opts?: {
     includeAddress: boolean;
     includePrimaryContact: boolean;

src/controllers/ForecastProductController.ts

@@ -0,0 +1,226 @@
+import { CWForecastItem } from "../modules/cw-utils/opportunities/opportunity.types";
+
+/**
+ * Forecast Product Controller
+ *
+ * Domain model class that encapsulates a ConnectWise Forecast Item (product/
+ * revenue line item on an opportunity). Forecast products are not persisted
+ * locally — all data is sourced directly from the ConnectWise API.
+ */
+export class ForecastProductController {
+  public readonly cwForecastId: number;
+  public forecastDescription: string;
+
+  public opportunityCwId: number | null;
+  public opportunityName: string | null;
+
+  public quantity: number;
+
+  public statusCwId: number | null;
+  public statusName: string | null;
+
+  public catalogItemCwId: number | null;
+  public catalogItemIdentifier: string | null;
+
+  public productDescription: string;
+  public productClass: string;
+  public forecastType: string;
+
+  public revenue: number;
+  public cost: number;
+  public margin: number;
+  public percentage: number;
+
+  public includeFlag: boolean;
+  public linkFlag: boolean;
+  public recurringFlag: boolean;
+  public taxableFlag: boolean;
+
+  public recurringRevenue: number;
+  public recurringCost: number;
+  public cycles: number;
+
+  public sequenceNumber: number;
+  public subNumber: number;
+  public quoteWerksQuantity: number;
+
+  public cwLastUpdated: Date | null;
+  public cwUpdatedBy: string | null;
+
+  // Cancellation data (from procurement products endpoint)
+  public cancelledFlag: boolean;
+  public quantityCancelled: number;
+  public cancelledReason: string | null;
+  public cancelledBy: number | null;
+  public cancelledDate: Date | null;
+
+  // Internal inventory data (from local CatalogItem database)
+  public onHand: number | null;
+  public inStock: boolean | null;
+
+  constructor(data: CWForecastItem) {
+    this.cwForecastId = data.id;
+    this.forecastDescription = data.forecastDescription;
+
+    this.opportunityCwId = data.opportunity?.id ?? null;
+    this.opportunityName = data.opportunity?.name ?? null;
+
+    this.quantity = data.quantity;
+
+    this.statusCwId = data.status?.id ?? null;
+    this.statusName = data.status?.name ?? null;
+
+    this.catalogItemCwId = data.catalogItem?.id ?? null;
+    this.catalogItemIdentifier = data.catalogItem?.identifier ?? null;
+
+    this.productDescription = data.productDescription;
+    this.productClass = data.productClass;
+    this.forecastType = data.forecastType;
+
+    this.revenue = data.revenue;
+    this.cost = data.cost;
+    this.margin = data.margin;
+    this.percentage = data.percentage;
+
+    this.includeFlag = data.includeFlag ?? false;
+    this.linkFlag = data.linkFlag ?? false;
+    this.recurringFlag = data.recurringFlag ?? false;
+    this.taxableFlag = data.taxableFlag ?? false;
+
+    this.recurringRevenue = data.recurringRevenue ?? 0;
+    this.recurringCost = data.recurringCost ?? 0;
+    this.cycles = data.cycles ?? 0;
+
+    this.sequenceNumber = data.sequenceNumber ?? 0;
+    this.subNumber = data.subNumber ?? 0;
+    this.quoteWerksQuantity = data.quoteWerksQuantity ?? 0;
+
+    this.cwLastUpdated = data._info?.lastUpdated
+      ? new Date(data._info.lastUpdated)
+      : null;
+    this.cwUpdatedBy = data._info?.updatedBy ?? null;
+
+    // Cancellation defaults — enriched later via applyCancellationData()
+    this.cancelledFlag = false;
+    this.quantityCancelled = 0;
+    this.cancelledReason = null;
+    this.cancelledBy = null;
+    this.cancelledDate = null;
+
+    // Inventory defaults — enriched later via applyInventoryData()
+    this.onHand = null;
+    this.inStock = null;
+  }
+
+  /**
+   * Apply Cancellation Data
+   *
+   * Enriches this forecast product with cancellation data from the
+   * procurement products endpoint.
+   */
+  public applyCancellationData(data: {
+    cancelledFlag?: boolean;
+    quantityCancelled?: number;
+    cancelledReason?: string;
+    cancelledBy?: number;
+    cancelledDate?: string;
+  }): void {
+    this.cancelledFlag = data.cancelledFlag ?? false;
+    this.quantityCancelled = data.quantityCancelled ?? 0;
+    this.cancelledReason = data.cancelledReason ?? null;
+    this.cancelledBy = data.cancelledBy ?? null;
+    this.cancelledDate = data.cancelledDate
+      ? new Date(data.cancelledDate)
+      : null;
+  }
+
+  /**
+   * Apply Inventory Data
+   *
+   * Enriches this forecast product with internal inventory data from
+   * the local CatalogItem database.
+   */
+  public applyInventoryData(data: { onHand: number }): void {
+    this.onHand = data.onHand;
+    this.inStock = data.onHand > 0;
+  }
+
+  /**
+   * Profit
+   *
+   * Returns the calculated profit (revenue - cost).
+   */
+  public get profit(): number {
+    return this.revenue - this.cost;
+  }
+
+  /**
+   * Cancelled
+   *
+   * Returns true if the forecast item has been cancelled (fully or partially).
+   */
+  public get cancelled(): boolean {
+    return this.cancelledFlag;
+  }
+
+  /**
+   * Cancellation Type
+   *
+   * Returns the type of cancellation:
+   * - `"full"` — all units have been cancelled (`quantityCancelled >= quantity`)
+   * - `"partial"` — some units cancelled but not all
+   * - `null` — not cancelled
+   */
+  public get cancellationType(): "full" | "partial" | null {
+    if (!this.cancelledFlag || this.quantityCancelled <= 0) return null;
+    return this.quantityCancelled >= this.quantity ? "full" : "partial";
+  }
+
+  /**
+   * To JSON
+   *
+   * Serializes the forecast product into a safe, API-friendly object.
+   */
+  public toJson(): Record<string, any> {
+    return {
+      id: this.cwForecastId,
+      forecastDescription: this.forecastDescription,
+      opportunity: this.opportunityCwId
+        ? { id: this.opportunityCwId, name: this.opportunityName }
+        : null,
+      quantity: this.quantity,
+      status: this.statusCwId
+        ? { id: this.statusCwId, name: this.statusName }
+        : null,
+      cancelled: this.cancelled,
+      cancellationType: this.cancellationType,
+      quantityCancelled: this.quantityCancelled,
+      cancelledReason: this.cancelledReason,
+      cancelledDate: this.cancelledDate,
+      catalogItem: this.catalogItemCwId
+        ? { id: this.catalogItemCwId, identifier: this.catalogItemIdentifier }
+        : null,
+      productDescription: this.productDescription,
+      productClass: this.productClass,
+      forecastType: this.forecastType,
+      revenue: this.revenue,
+      cost: this.cost,
+      margin: this.margin,
+      profit: this.profit,
+      percentage: this.percentage,
+      includeFlag: this.includeFlag,
+      linkFlag: this.linkFlag,
+      recurringFlag: this.recurringFlag,
+      taxableFlag: this.taxableFlag,
+      recurringRevenue: this.recurringRevenue,
+      recurringCost: this.recurringCost,
+      cycles: this.cycles,
+      sequenceNumber: this.sequenceNumber,
+      subNumber: this.subNumber,
+      cwLastUpdated: this.cwLastUpdated,
+      cwUpdatedBy: this.cwUpdatedBy,
+      onHand: this.onHand,
+      inStock: this.inStock,
+    };
+  }
+}

src/controllers/OpportunityController.ts

@@ -1,7 +1,23 @@
-import { Opportunity } from "../../generated/prisma/client";
+import { Company, Opportunity } from "../../generated/prisma/client";
 import { prisma } from "../constants";
+import { CompanyController } from "./CompanyController";
+import { ActivityController } from "./ActivityController";
 import { fetchOpportunity } from "../modules/cw-utils/opportunities/fetchOpportunity";
-import { CWOpportunity } from "../modules/cw-utils/opportunities/opportunity.types";
+import { opportunityCw } from "../modules/cw-utils/opportunities/opportunities";
+import { activityCw } from "../modules/cw-utils/activities/activities";
+import {
+  fetchCompanySite,
+  serializeCwSite,
+} from "../modules/cw-utils/sites/companySites";
+import {
+  CWCustomField,
+  CWForecastItemCreate,
+  CWOpportunity,
+  CWOpportunityNote,
+} from "../modules/cw-utils/opportunities/opportunity.types";
+import { resolveMember } from "../modules/cw-utils/members/memberCache";
+import { ForecastProductController } from "./ForecastProductController";
+import GenericError from "../Errors/GenericError";
 
 /**
  * Opportunity Controller
@@ -63,10 +79,26 @@ export class OpportunityController {
   public companyId: string | null;
   public cwLastUpdated: Date | null;
 
+  // Local product display order — array of CW forecast item IDs.
+  // When non-empty, fetchProducts() uses this instead of CW sequenceNumber.
+  public productSequence: number[];
+
   public readonly createdAt: Date;
   public updatedAt: Date;
 
-  constructor(data: Opportunity) {
+  private _company: CompanyController | null = null;
+  private _siteData: ReturnType<typeof serializeCwSite> | null = null;
+  private _customFields: CWCustomField[] | null = null;
+  private _activities: ActivityController[] | null = null;
+
+  constructor(
+    data: Opportunity & { company?: Company | null },
+    opts?: {
+      company?: CompanyController;
+      customFields?: CWCustomField[];
+      activities?: ActivityController[];
+    },
+  ) {
     this.id = data.id;
     this.cwOpportunityId = data.cwOpportunityId;
     this.name = data.name;
@@ -118,9 +150,43 @@ export class OpportunityController {
 
     this.companyId = data.companyId;
     this.cwLastUpdated = data.cwLastUpdated;
+    this.productSequence = data.productSequence;
 
     this.createdAt = data.createdAt;
     this.updatedAt = data.updatedAt;
+
+    this._company =
+      opts?.company ??
+      (data.company ? new CompanyController(data.company) : null);
+
+    this._customFields = opts?.customFields ?? null;
+    this._activities = opts?.activities ?? null;
+  }
+
+  /**
+   * Fetch Company
+   *
+   * Lazily loads the associated CompanyController from the database
+   * if not already loaded via the Prisma include.
+   *
+   * @returns {Promise<CompanyController | null>}
+   */
+  public async fetchCompany(): Promise<CompanyController | null> {
+    if (this._company) {
+      await this._company.hydrateCwData();
+      return this._company;
+    }
+    if (!this.companyId) return null;
+
+    const companyData = await prisma.company.findUnique({
+      where: { id: this.companyId },
+    });
+
+    if (!companyData) return null;
+
+    this._company = new CompanyController(companyData);
+    await this._company.hydrateCwData();
+    return this._company;
   }
 
   /**
@@ -136,6 +202,7 @@ export class OpportunityController {
     const updated = await prisma.opportunity.update({
       where: { id: this.id },
       data: mapped,
+      include: { company: true },
     });
 
     return new OpportunityController(updated);
@@ -216,6 +283,437 @@ export class OpportunityController {
     };
   }
 
+  /**
+   * Fetch Site
+   *
+   * Fetches the full site details (address, phone, flags) from ConnectWise
+   * for the site associated with this opportunity.
+   * Requires both companyCwId and siteCwId to be set.
+   *
+   * @returns Serialized site object or null
+   */
+  public async fetchSite() {
+    if (this._siteData) return this._siteData;
+    if (!this.companyCwId || !this.siteCwId) return null;
+
+    const cwSite = await fetchCompanySite(this.companyCwId, this.siteCwId);
+    this._siteData = serializeCwSite(cwSite);
+    return this._siteData;
+  }
+
+  /**
+   * Fetch Contacts
+   *
+   * Fetches contacts associated with this opportunity from ConnectWise
+   * and returns a serialized array.
+   */
+  public async fetchContacts() {
+    const contacts = await opportunityCw.fetchContacts(this.cwOpportunityId);
+
+    return contacts.map((ct) => ({
+      id: ct.id,
+      contact: ct.contact ? { id: ct.contact.id, name: ct.contact.name } : null,
+      company: ct.company
+        ? {
+            id: ct.company.id,
+            identifier: ct.company.identifier,
+            name: ct.company.name,
+          }
+        : null,
+      role: ct.role ? { id: ct.role.id, name: ct.role.name } : null,
+      notes: ct.notes,
+      referralFlag: ct.referralFlag,
+    }));
+  }
+
+  /**
+   * Fetch Notes
+   *
+   * Fetches notes associated with this opportunity from ConnectWise
+   * and returns a serialized array.
+   */
+  public async fetchNotes() {
+    const notes = await opportunityCw.fetchNotes(this.cwOpportunityId);
+
+    return Promise.all(
+      notes.map(async (n) => ({
+        id: n.id,
+        text: n.text,
+        type: n.type ? { id: n.type.id, name: n.type.name } : null,
+        flagged: n.flagged,
+        dateEntered: n._info?.lastUpdated
+          ? new Date(n._info.lastUpdated)
+          : null,
+        enteredBy: await resolveMember(n.enteredBy),
+      })),
+    );
+  }
+
+  /**
+   * Fetch Single Note
+   *
+   * Fetches a single note by its ID from ConnectWise.
+   *
+   * @param noteId - The CW note ID
+   */
+  public async fetchNote(noteId: number) {
+    const note = await opportunityCw.fetchNote(this.cwOpportunityId, noteId);
+
+    return {
+      id: note.id,
+      text: note.text,
+      type: note.type ? { id: note.type.id, name: note.type.name } : null,
+      flagged: note.flagged,
+      enteredBy: await resolveMember(note.enteredBy),
+    };
+  }
+
+  /**
+   * Fetch Activities
+   *
+   * Fetches activities associated with this opportunity from ConnectWise
+   * and returns an array of ActivityController instances.
+   * Results are cached after the first call.
+   */
+  public async fetchActivities(): Promise<ActivityController[]> {
+    if (this._activities) return this._activities;
+
+    const collection = await activityCw.fetchByOpportunity(
+      this.cwOpportunityId,
+    );
+    this._activities = collection.map((item) => new ActivityController(item));
+    return this._activities;
+  }
+
+  /**
+   * Fetch Products
+   *
+   * Fetches products (forecast/revenue items) for this opportunity from
+   * ConnectWise and returns ForecastProductController instances.
+   */
+  public async fetchProducts(): Promise<ForecastProductController[]> {
+    const [forecast, procProducts] = await Promise.all([
+      opportunityCw.fetchProducts(this.cwOpportunityId),
+      opportunityCw.fetchProcurementProducts(this.cwOpportunityId),
+    ]);
+
+    // Build a map of forecastDetailId → procurement product cancellation data
+    const cancellationMap = new Map<number, Record<string, unknown>>();
+    for (const pp of procProducts) {
+      const forecastDetailId = pp.forecastDetailId as number | undefined;
+      if (forecastDetailId) {
+        cancellationMap.set(forecastDetailId, pp);
+      }
+    }
+
+    // Apply local ordering if productSequence is set, otherwise fall back
+    // to CW sequenceNumber.
+    const forecastItems = forecast.forecastItems ?? [];
+    let ordered: typeof forecastItems;
+
+    if (this.productSequence.length > 0) {
+      const itemById = new Map(forecastItems.map((fi) => [fi.id, fi]));
+      // Items in the specified order first, then any new items not yet sequenced
+      const sequenced = this.productSequence
+        .map((id) => itemById.get(id))
+        .filter((fi): fi is NonNullable<typeof fi> => fi !== undefined);
+      const sequencedIds = new Set(this.productSequence);
+      const unsequenced = forecastItems
+        .filter((fi) => !sequencedIds.has(fi.id))
+        .sort((a, b) => a.sequenceNumber - b.sequenceNumber);
+      ordered = [...sequenced, ...unsequenced];
+    } else {
+      ordered = [...forecastItems].sort(
+        (a, b) => a.sequenceNumber - b.sequenceNumber,
+      );
+    }
+
+    const controllers = ordered.map((item) => {
+      const ctrl = new ForecastProductController(item);
+      const procData = cancellationMap.get(item.id);
+      if (procData) {
+        ctrl.applyCancellationData(procData as any);
+      }
+      return ctrl;
+    });
+
+    // Enrich with internal inventory data from local CatalogItem DB
+    const catalogCwIds = controllers
+      .map((c) => c.catalogItemCwId)
+      .filter((id): id is number => id !== null);
+
+    if (catalogCwIds.length > 0) {
+      const catalogItems = await prisma.catalogItem.findMany({
+        where: { cwCatalogId: { in: catalogCwIds } },
+        select: { cwCatalogId: true, onHand: true },
+      });
+      const inventoryMap = new Map(
+        catalogItems.map((ci) => [ci.cwCatalogId, ci]),
+      );
+      for (const ctrl of controllers) {
+        const inv = ctrl.catalogItemCwId
+          ? inventoryMap.get(ctrl.catalogItemCwId)
+          : undefined;
+        if (inv) ctrl.applyInventoryData(inv);
+      }
+    }
+
+    return controllers;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Opportunity Activity / Workflow Methods
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Set Internal Review
+   *
+   * The quote is ready to be reviewed before it is ready to be sent.
+   */
+  public async setInternalReview(): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Set Internal Approved
+   *
+   * The quote has been approved and is ready to be sent out.
+   */
+  public async setInternalApproved(): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Set Quote Sent
+   *
+   * The quote has been sent to the customer.
+   */
+  public async setQuoteSent(): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Set Quote Confirmed
+   *
+   * The quote has been received by the customer.
+   */
+  public async setQuoteConfirmed(): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Set Revision Needed
+   *
+   * The quote needs to be revised and is set to stage revision.
+   */
+  public async setRevisionNeeded(): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Set Finalized
+   *
+   * Locks any non-admins from modifying the quote, indicating
+   * this is the final iteration of the quote.
+   */
+  public async setFinalized(): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Convert
+   *
+   * Converts the quote to a ticket and updates all necessary fields.
+   */
+  public async convert(): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Add Time
+   *
+   * Adds time to an activity on this opportunity.
+   *
+   * @param activityId - The CW activity ID to add time to
+   * @param user - The user identifier adding time
+   */
+  public async addTime(activityId: number, user: string): Promise<void> {
+    // TODO: implement
+  }
+
+  /**
+   * Update Product
+   *
+   * Updates an existing product/line item on this opportunity via PATCH.
+   *
+   * @param forecastItemId - The CW forecast item ID to update
+   * @param data - Key/value pairs to patch
+   */
+  public async updateProduct(
+    forecastItemId: number,
+    data: Record<string, unknown>,
+  ): Promise<ForecastProductController> {
+    try {
+      const updated = await opportunityCw.updateProduct(
+        this.cwOpportunityId,
+        forecastItemId,
+        data,
+      );
+      return new ForecastProductController(updated);
+    } catch (err: any) {
+      console.error(
+        `[updateProduct] Failed to patch forecast item ${forecastItemId} on opportunity ${this.cwOpportunityId}`,
+        JSON.stringify(
+          {
+            data,
+            status: err?.response?.status,
+            statusText: err?.response?.statusText,
+            responseData: err?.response?.data,
+            message: err?.message,
+          },
+          null,
+          2,
+        ),
+      );
+      throw err;
+    }
+  }
+
+  /**
+   * Resequence Products
+   *
+   * Stores the desired display order of forecast item IDs locally in
+   * the database. No CW API calls are made — CW item IDs are stable
+   * and ordering is applied when `fetchProducts()` is called.
+   *
+   * @param orderedIds - Forecast item IDs in the desired display order
+   */
+  public async resequenceProducts(
+    orderedIds: number[],
+  ): Promise<ForecastProductController[]> {
+    // Validate all IDs exist in CW
+    const forecast = await opportunityCw.fetchProducts(this.cwOpportunityId);
+    const existingIds = new Set(
+      (forecast.forecastItems ?? []).map((fi) => fi.id),
+    );
+    for (const id of orderedIds) {
+      if (!existingIds.has(id)) {
+        throw new GenericError({
+          status: 404,
+          name: "ForecastItemNotFound",
+          message: `Forecast item ${id} not found on opportunity ${this.cwOpportunityId}`,
+        });
+      }
+    }
+
+    // Persist the sequence locally
+    await prisma.opportunity.update({
+      where: { id: this.id },
+      data: { productSequence: orderedIds },
+    });
+    this.productSequence = orderedIds;
+
+    // Return items in the new order
+    return this.fetchProducts();
+  }
+
+  /**
+   * Add Products
+   *
+   * Adds one or more products/line items to this opportunity via the
+   * ConnectWise forecast endpoint. The caller passes only the fields
+   * the user is permitted to set (already filtered by field-level
+   * permission gating in the route handler).
+   *
+   * Accepts a single item or an array of items.
+   */
+  public async addProducts(
+    data: CWForecastItemCreate | CWForecastItemCreate[],
+  ): Promise<ForecastProductController[]> {
+    try {
+      const created = await opportunityCw.createProducts(
+        this.cwOpportunityId,
+        data,
+      );
+      return created.map((item) => new ForecastProductController(item));
+    } catch (err: any) {
+      console.error(
+        `[addProducts] Failed to create forecast item(s) on opportunity ${this.cwOpportunityId}`,
+        JSON.stringify(
+          {
+            data,
+            status: err?.response?.status,
+            statusText: err?.response?.statusText,
+            responseData: err?.response?.data,
+            message: err?.message,
+          },
+          null,
+          2,
+        ),
+      );
+      throw new GenericError({
+        status: err?.response?.status ?? 500,
+        name: "AddProductFailed",
+        message:
+          err?.response?.data?.message ??
+          "Failed to add product(s) to opportunity",
+        cause: err?.message,
+      });
+    }
+  }
+
+  /**
+   * Add Note
+   *
+   * Creates a new note on this opportunity in ConnectWise.
+   *
+   * @param note - The note text to add
+   * @param user - The user identifier adding the note
+   * @param opts - Optional flags
+   */
+  public async addNote(
+    note: string,
+    user: string,
+    opts?: { flagged?: boolean },
+  ): Promise<CWOpportunityNote> {
+    const created = await opportunityCw.createNote(this.cwOpportunityId, {
+      text: note,
+      flagged: opts?.flagged ?? false,
+    });
+    return created;
+  }
+
+  /**
+   * Update Note
+   *
+   * Updates an existing note on this opportunity in ConnectWise.
+   *
+   * @param noteId - The CW note ID to update
+   * @param data - The fields to update
+   */
+  public async updateNote(
+    noteId: number,
+    data: { text?: string; flagged?: boolean },
+  ): Promise<CWOpportunityNote> {
+    const updated = await opportunityCw.updateNote(
+      this.cwOpportunityId,
+      noteId,
+      data,
+    );
+    return updated;
+  }
+
+  /**
+   * Delete Note
+   *
+   * Deletes a note from this opportunity in ConnectWise.
+   *
+   * @param noteId - The CW note ID to delete
+   */
+  public async deleteNote(noteId: number): Promise<void> {
+    await opportunityCw.deleteNote(this.cwOpportunityId, noteId);
+  }
+
   /**
    * To JSON
    *
@@ -258,13 +756,23 @@ export class OpportunityController {
             name: this.secondarySalesRepName,
           }
         : null,
-      company: this.companyCwId
+      company: this._company
-        ? { id: this.companyCwId, name: this.companyName }
+        ? this._company.toJson({
-        : null,
+            includeAllContacts: true,
+            includeAddress: true,
+            includePrimaryContact: false,
+          })
+        : this.companyCwId
+          ? { id: this.companyCwId, name: this.companyName }
+          : null,
       contact: this.contactCwId
         ? { id: this.contactCwId, name: this.contactName }
         : null,
-      site: this.siteCwId ? { id: this.siteCwId, name: this.siteName } : null,
+      site: this._siteData
+        ? this._siteData
+        : this.siteCwId
+          ? { id: this.siteCwId, name: this.siteName }
+          : null,
       customerPO: this.customerPO,
       totalSalesTax: this.totalSalesTax,
       location: this.locationCwId
@@ -283,8 +791,11 @@ export class OpportunityController {
         : null,
       companyId: this.companyId,
       cwLastUpdated: this.cwLastUpdated,
+      productSequence: this.productSequence,
       createdAt: this.createdAt,
       updatedAt: this.updatedAt,
+      customFields: this._customFields ?? [],
+      activities: this._activities?.map((a) => a.toJson()) ?? [],
     };
   }
 }

src/controllers/UserController.ts

@@ -19,6 +19,7 @@ export default class UserController {
   public login: string;
   public email: string;
   public image: string | null;
+  public cwIdentifier: string | null;
 
   private _roles: Collection<string, Role>;
   private _permissions: string | null;
@@ -31,6 +32,7 @@ export default class UserController {
     this.login = userdata.login;
     this.email = userdata.email;
     this.image = userdata.image;
+    this.cwIdentifier = userdata.cwIdentifier ?? null;
     this.updatedAt = userdata.updatedAt;
     this.createdAt = userdata.createdAt;
     this._permissions = userdata.permissions ?? null;
@@ -57,6 +59,7 @@ export default class UserController {
     this.login = userdata.login;
     this.email = userdata.email;
     this.image = userdata.image;
+    this.cwIdentifier = userdata.cwIdentifier ?? null;
     this.updatedAt = userdata.updatedAt;
     this.createdAt = userdata.createdAt;
   }
@@ -314,6 +317,7 @@ export default class UserController {
           })(),
       login: opts?.safeReturn ? undefined : this.login,
       email: opts?.safeReturn ? undefined : this.email,
+      cwIdentifier: opts?.safeReturn ? undefined : this.cwIdentifier,
       image: this.image,
       createdAt: this.createdAt,
       updatedAt: this.updatedAt,

src/index.ts

@@ -13,6 +13,9 @@ import { refreshCompanies } from "./modules/cw-utils/refreshCompanies";
 import { refreshCatalog } from "./modules/cw-utils/procurement/refreshCatalog";
 import { refreshInventory } from "./modules/cw-utils/procurement/refreshInventory";
 import { refreshOpportunities } from "./modules/cw-utils/opportunities/refreshOpportunities";
+import { refreshOpportunityCache } from "./modules/cache/opportunityCache";
+import { refreshCwIdentifiers } from "./modules/cw-utils/members/refreshCwIdentifiers";
+import { userDefinedFieldsCw } from "./modules/cw-utils/userDefinedFields";
 import { events, setupEventDebugger } from "./modules/globalEvents";
 import { signPermissions } from "./modules/permission-utils/signPermissions";
 import { RoleController } from "./controllers/RoleController";
@@ -39,6 +42,7 @@ const safeStartup = async (label: string, fn: () => Promise<void>) => {
 // ---------------------------------------------------------------------------
 Bun.serve({
   port: PORT,
+  idleTimeout: 255,
   websocket: engine.handler().websocket,
   fetch: (req, server) => {
     const url = new URL(req.url);
@@ -118,6 +122,36 @@ setInterval(() => {
   );
 }, 60 * 1000);
 
+// Refresh opportunity CW cache every 30 seconds (activities + company hydration)
+await safeStartup("refreshOpportunityCache", refreshOpportunityCache);
+setInterval(() => {
+  return refreshOpportunityCache().catch((err) =>
+    console.error("[interval] refreshOpportunityCache failed", err),
+  );
+}, 30 * 1000);
+
+// Refresh User Defined Fields every 5 minutes
+await safeStartup("refreshUDFs", () => userDefinedFieldsCw.refresh());
+setInterval(
+  () => {
+    return userDefinedFieldsCw
+      .refresh()
+      .catch((err) => console.error("[interval] refreshUDFs failed", err));
+  },
+  5 * 60 * 1000,
+);
+
+// Refresh CW identifiers for all users every 30 minutes
+await safeStartup("refreshCwIdentifiers", refreshCwIdentifiers);
+setInterval(
+  () => {
+    return refreshCwIdentifiers().catch((err) =>
+      console.error("[interval] refreshCwIdentifiers failed", err),
+    );
+  },
+  30 * 60 * 1000,
+);
+
 await safeStartup("syncSites", () => unifiSites.syncSites());
 setInterval(() => {
   return unifiSites

src/managers/activities.ts

@@ -0,0 +1,211 @@
+import { ActivityController } from "../controllers/ActivityController";
+import { connectWiseApi } from "../constants";
+import GenericError from "../Errors/GenericError";
+import { activityCw } from "../modules/cw-utils/activities/activities";
+import {
+  CWCreateActivity,
+  CWPatchOperation,
+} from "../modules/cw-utils/activities/activity.types";
+
+export const activities = {
+  /**
+   * Fetch Activity
+   *
+   * Fetch a single activity by its ConnectWise activity ID
+   * and return an ActivityController instance.
+   *
+   * @param cwActivityId - The ConnectWise activity ID
+   * @returns {Promise<ActivityController>}
+   */
+  async fetchItem(cwActivityId: number): Promise<ActivityController> {
+    try {
+      const cwData = await activityCw.fetch(cwActivityId);
+      return new ActivityController(cwData);
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "FetchActivityError",
+        message: `Failed to fetch activity ${cwActivityId}`,
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: (error as any).status ?? 502,
+      });
+    }
+  },
+
+  /**
+   * Fetch All Activities (Paginated)
+   *
+   * Fetches activities from ConnectWise with optional conditions and pagination.
+   *
+   * @param page - Page number (1-based)
+   * @param rpp  - Records per page
+   * @param conditions - Optional CW conditions string for filtering
+   * @returns {Promise<ActivityController[]>}
+   */
+  async fetchPages(
+    page: number,
+    rpp: number,
+    conditions?: string,
+  ): Promise<ActivityController[]> {
+    try {
+      const pageNum = Math.max(page, 1);
+      const conditionsParam = conditions
+        ? `&conditions=${encodeURIComponent(conditions)}`
+        : "";
+      const response = await connectWiseApi.get(
+        `/sales/activities?page=${pageNum}&pageSize=${rpp}${conditionsParam}`,
+      );
+      const items = response.data;
+      return items.map((item: any) => new ActivityController(item));
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "FetchActivitiesError",
+        message: "Failed to fetch activities from ConnectWise",
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: 502,
+      });
+    }
+  },
+
+  /**
+   * Fetch Activities by Company
+   *
+   * Fetches all activities for a company by its ConnectWise company ID.
+   *
+   * @param cwCompanyId - The ConnectWise company ID
+   * @returns {Promise<ActivityController[]>}
+   */
+  async fetchByCompany(cwCompanyId: number): Promise<ActivityController[]> {
+    try {
+      const collection = await activityCw.fetchByCompany(cwCompanyId);
+      return collection.map((item) => new ActivityController(item));
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "FetchCompanyActivitiesError",
+        message: `Failed to fetch activities for company ${cwCompanyId}`,
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: 502,
+      });
+    }
+  },
+
+  /**
+   * Fetch Activities by Opportunity
+   *
+   * Fetches all activities for an opportunity by its ConnectWise opportunity ID.
+   *
+   * @param cwOpportunityId - The ConnectWise opportunity ID
+   * @returns {Promise<ActivityController[]>}
+   */
+  async fetchByOpportunity(
+    cwOpportunityId: number,
+  ): Promise<ActivityController[]> {
+    try {
+      const collection = await activityCw.fetchByOpportunity(cwOpportunityId);
+      return collection.map((item) => new ActivityController(item));
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "FetchOpportunityActivitiesError",
+        message: `Failed to fetch activities for opportunity ${cwOpportunityId}`,
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: 502,
+      });
+    }
+  },
+
+  /**
+   * Create Activity
+   *
+   * Creates a new activity in ConnectWise and returns an ActivityController.
+   *
+   * @param data - The activity data to create
+   * @returns {Promise<ActivityController>}
+   */
+  async create(data: CWCreateActivity): Promise<ActivityController> {
+    try {
+      return await ActivityController.create(data);
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "CreateActivityError",
+        message: "Failed to create activity in ConnectWise",
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: 502,
+      });
+    }
+  },
+
+  /**
+   * Update Activity
+   *
+   * Updates an existing activity in ConnectWise using JSON Patch operations
+   * and returns an updated ActivityController.
+   *
+   * @param cwActivityId - The ConnectWise activity ID to update
+   * @param operations - Array of JSON Patch operations to apply
+   * @returns {Promise<ActivityController>}
+   */
+  async update(
+    cwActivityId: number,
+    operations: CWPatchOperation[],
+  ): Promise<ActivityController> {
+    try {
+      const updated = await activityCw.update(cwActivityId, operations);
+      return new ActivityController(updated);
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "UpdateActivityError",
+        message: `Failed to update activity ${cwActivityId}`,
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: 502,
+      });
+    }
+  },
+
+  /**
+   * Delete Activity
+   *
+   * Deletes an activity from ConnectWise.
+   *
+   * @param cwActivityId - The ConnectWise activity ID to delete
+   */
+  async delete(cwActivityId: number): Promise<void> {
+    try {
+      await activityCw.delete(cwActivityId);
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "DeleteActivityError",
+        message: `Failed to delete activity ${cwActivityId}`,
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: 502,
+      });
+    }
+  },
+
+  /**
+   * Count Activities
+   *
+   * Returns the total number of activities, optionally filtered.
+   *
+   * @param conditions - Optional CW conditions string for filtering
+   * @returns {Promise<number>}
+   */
+  async count(conditions?: string): Promise<number> {
+    try {
+      return await activityCw.countItems(conditions);
+    } catch (error) {
+      const errBody = (error as any).response?.data || error;
+      throw new GenericError({
+        name: "CountActivitiesError",
+        message: "Failed to count activities in ConnectWise",
+        cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+        status: 502,
+      });
+    }
+  },
+};

src/managers/opportunities.ts

@@ -1,6 +1,127 @@
+import { Company } from "../../generated/prisma/client";
 import { prisma } from "../constants";
+import { ActivityController } from "../controllers/ActivityController";
+import { CompanyController } from "../controllers/CompanyController";
 import { OpportunityController } from "../controllers/OpportunityController";
 import GenericError from "../Errors/GenericError";
+import { activityCw } from "../modules/cw-utils/activities/activities";
+import { opportunityCw } from "../modules/cw-utils/opportunities/opportunities";
+import { computeCacheTTL } from "../modules/algorithms/computeCacheTTL";
+import {
+  getCachedActivities,
+  getCachedCompanyCwData,
+  fetchAndCacheActivities,
+  fetchAndCacheCompanyCwData,
+} from "../modules/cache/opportunityCache";
+
+// ---------------------------------------------------------------------------
+// Data-source hierarchy helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a CompanyController with hydrated CW data from a Prisma Company record.
+ *
+ * Data-source hierarchy (controlled by `strategy`):
+ *
+ * - `"cache-only"` — Redis cache → bare DB record (no CW call).
+ *   Ideal for list views where latency matters and the background
+ *   refresh job is responsible for keeping the cache warm.
+ *
+ * - `"cache-then-cw"` (default) — Redis cache → CW API → cache result.
+ *   On a cold cache, calls CW to ensure the caller gets full data.
+ *
+ * - `"cw-first"` — CW API (always) → cache result.
+ *   Forces a fresh fetch regardless of cache state.
+ */
+async function buildCompanyController(
+  company: Company,
+  opts?: {
+    strategy?: "cache-only" | "cache-then-cw" | "cw-first";
+    ttlMs?: number;
+  },
+): Promise<CompanyController> {
+  const strategy = opts?.strategy ?? "cache-then-cw";
+  const ctrl = new CompanyController(company);
+
+  // ── cw-first: always fetch from CW ──────────────────────────────────
+  if (strategy === "cw-first") {
+    await ctrl.hydrateCwData();
+    if (ctrl.cw_Data && opts?.ttlMs) {
+      await fetchAndCacheCompanyCwData(company.cw_CompanyId, opts.ttlMs).catch(
+        () => {},
+      );
+    }
+    return ctrl;
+  }
+
+  // ── cache-only / cache-then-cw: try Redis first ─────────────────────
+  const cached = await getCachedCompanyCwData(company.cw_CompanyId);
+  if (cached) {
+    ctrl.cw_Data = cached;
+    return ctrl;
+  }
+
+  // cache-only stops here — return the bare DB-backed controller
+  if (strategy === "cache-only") return ctrl;
+
+  // cache-then-cw: cache miss — fall through to CW
+  await ctrl.hydrateCwData();
+  if (ctrl.cw_Data && opts?.ttlMs) {
+    await fetchAndCacheCompanyCwData(company.cw_CompanyId, opts.ttlMs).catch(
+      () => {},
+    );
+  }
+
+  return ctrl;
+}
+
+/**
+ * Fetch ActivityController[] for an opportunity.
+ *
+ * Same three strategies as {@link buildCompanyController}:
+ *
+ * - `"cache-only"` — Redis → empty array (no CW call).
+ * - `"cache-then-cw"` (default) — Redis → CW API → cache result.
+ * - `"cw-first"` — CW API (always) → cache result.
+ */
+async function buildActivities(
+  cwOpportunityId: number,
+  opts?: {
+    strategy?: "cache-only" | "cache-then-cw" | "cw-first";
+    ttlMs?: number;
+  },
+): Promise<ActivityController[]> {
+  const strategy = opts?.strategy ?? "cache-then-cw";
+
+  // ── cw-first: always fetch from CW ──────────────────────────────────
+  if (strategy === "cw-first") {
+    const collection = await activityCw.fetchByOpportunity(cwOpportunityId);
+    const arr = collection.map((item) => item);
+    if (opts?.ttlMs) {
+      await fetchAndCacheActivities(cwOpportunityId, opts.ttlMs).catch(
+        () => {},
+      );
+    }
+    return arr.map((item) => new ActivityController(item));
+  }
+
+  // ── cache-only / cache-then-cw: try Redis first ─────────────────────
+  const cached = await getCachedActivities(cwOpportunityId);
+  if (cached) {
+    return cached.map((item) => new ActivityController(item));
+  }
+
+  // cache-only stops here — return empty (background job will fill it)
+  if (strategy === "cache-only") return [];
+
+  // cache-then-cw: cache miss — fall through to CW
+  const collection = await activityCw.fetchByOpportunity(cwOpportunityId);
+  const arr = collection.map((item) => item);
+  if (opts?.ttlMs) {
+    await fetchAndCacheActivities(cwOpportunityId, opts.ttlMs).catch(() => {});
+  }
+  return arr.map((item) => new ActivityController(item));
+}
 
 export const opportunities = {
   /**
@@ -9,20 +130,38 @@ export const opportunities = {
    * Fetch an opportunity by its internal ID or ConnectWise opportunity ID
    * and return an OpportunityController instance.
    *
+   * **Data-source strategy:**
+   * - `fresh: true` → `"cw-first"` — always fetches from CW, updates DB, caches result.
+   * - `fresh: false` (default) → `"cache-then-cw"` — tries Redis first, falls back to CW on miss.
+   *
+   * Individual fetches always contact CW to update the DB record with
+   * the latest data from ConnectWise, regardless of the cache strategy
+   * for activities/company hydration.
+   *
    * @param identifier - The internal ID (string) or CW opportunity ID (number)
+   * @param opts - Optional flags
+   * @param opts.fresh - When `true`, bypass the cache and pull directly from CW.
    * @returns {Promise<OpportunityController>}
    */
-  async fetchItem(identifier: string | number): Promise<OpportunityController> {
+  async fetchItem(
+    identifier: string | number,
+    opts?: { fresh?: boolean },
+  ): Promise<OpportunityController> {
+    const strategy: "cache-only" | "cache-then-cw" | "cw-first" = opts?.fresh
+      ? "cw-first"
+      : "cache-then-cw";
     const isNumeric =
       typeof identifier === "number" || /^\d+$/.test(String(identifier));
 
-    const item = await prisma.opportunity.findFirst({
+    // Look up the existing DB record to get the cwOpportunityId
+    const existing = await prisma.opportunity.findFirst({
       where: isNumeric
         ? { cwOpportunityId: Number(identifier) }
         : { id: identifier as string },
+      select: { id: true, cwOpportunityId: true },
     });
 
-    if (!item) {
+    if (!existing) {
       throw new GenericError({
         message: "Opportunity not found",
         name: "OpportunityNotFound",
@@ -31,12 +170,58 @@ export const opportunities = {
       });
     }
 
-    return new OpportunityController(item);
+    // Fetch fresh data from ConnectWise
+    const cwData = await opportunityCw.fetch(existing.cwOpportunityId);
+
+    // Map and update the DB record
+    const mapped = OpportunityController.mapCwToDb(cwData);
+
+    // Resolve internal company link
+    const companyId = cwData.company?.id
+      ? ((
+          await prisma.company.findFirst({
+            where: { cw_CompanyId: cwData.company.id },
+            select: { id: true },
+          })
+        )?.id ?? null)
+      : null;
+
+    const updated = await prisma.opportunity.update({
+      where: { id: existing.id },
+      data: { ...mapped, companyId },
+      include: { company: true },
+    });
+
+    const ttlMs =
+      computeCacheTTL({
+        closedFlag: updated.closedFlag,
+        closedDate: updated.closedDate,
+        expectedCloseDate: updated.expectedCloseDate,
+        lastUpdated: updated.cwLastUpdated,
+      }) ?? undefined;
+
+    const activities = await buildActivities(updated.cwOpportunityId, {
+      strategy,
+      ttlMs,
+    });
+
+    return new OpportunityController(updated, {
+      company: updated.company
+        ? await buildCompanyController(updated.company, { strategy, ttlMs })
+        : undefined,
+      customFields: cwData.customFields ?? [],
+      activities,
+    });
   },
 
   /**
    * Fetch All Opportunities (Paginated)
    *
+   * Uses the **cache-only** strategy: Redis → bare DB data.
+   * Activities and company hydration come from the Redis cache if
+   * available; otherwise the controller is returned with DB-only data.
+   * The background refresh job is responsible for keeping Redis warm.
+   *
    * @param page - Page number (1-based)
    * @param rpp  - Records per page
    * @param opts - Optional filters
@@ -51,12 +236,26 @@ export const opportunities = {
 
     const items = await prisma.opportunity.findMany({
       where: opts?.includeClosed ? undefined : { closedFlag: false },
+      include: { company: true },
       skip,
       take: rpp,
-      orderBy: { expectedCloseDate: "asc" },
+      orderBy: { createdAt: "desc" },
     });
 
-    return items.map((item) => new OpportunityController(item));
+    return Promise.all(
+      items.map(async (item) => {
+        return new OpportunityController(item, {
+          company: item.company
+            ? await buildCompanyController(item.company, {
+                strategy: "cache-only",
+              })
+            : undefined,
+          activities: await buildActivities(item.cwOpportunityId, {
+            strategy: "cache-only",
+          }),
+        });
+      }),
+    );
   },
 
   /**
@@ -65,6 +264,8 @@ export const opportunities = {
    * Search opportunities by name, company name, contact name, notes,
    * sales rep, or status with pagination support.
    *
+   * Uses the **cache-only** strategy (same as `fetchPages`).
+   *
    * @param query - Search query string
    * @param page  - Page number (1-based)
    * @param rpp   - Records per page
@@ -78,6 +279,9 @@ export const opportunities = {
     opts?: { includeClosed?: boolean },
   ): Promise<OpportunityController[]> {
     const skip = (Math.max(page, 1) - 1) * rpp;
+    const numericQuery = /^\d+$/.test(query.trim())
+      ? Number(query.trim())
+      : null;
 
     const items = await prisma.opportunity.findMany({
       where: {
@@ -90,14 +294,31 @@ export const opportunities = {
           { primarySalesRepName: { contains: query, mode: "insensitive" } },
           { statusName: { contains: query, mode: "insensitive" } },
           { stageName: { contains: query, mode: "insensitive" } },
+          ...(numericQuery !== null
+            ? [{ cwOpportunityId: { equals: numericQuery } }]
+            : []),
         ],
       },
+      include: { company: true },
       skip,
       take: rpp,
       orderBy: { expectedCloseDate: "asc" },
     });
 
-    return items.map((item) => new OpportunityController(item));
+    return Promise.all(
+      items.map(async (item) => {
+        return new OpportunityController(item, {
+          company: item.company
+            ? await buildCompanyController(item.company, {
+                strategy: "cache-only",
+              })
+            : undefined,
+          activities: await buildActivities(item.cwOpportunityId, {
+            strategy: "cache-only",
+          }),
+        });
+      }),
+    );
   },
 
   /**
@@ -112,11 +333,50 @@ export const opportunities = {
     });
   },
 
+  /**
+   * Count Search Results
+   *
+   * Returns the total number of opportunities matching a search query,
+   * using the same filter logic as `search()`.
+   *
+   * @param query - Search query string
+   * @param opts  - Optional filters
+   * @returns {Promise<number>}
+   */
+  async searchCount(
+    query: string,
+    opts?: { includeClosed?: boolean },
+  ): Promise<number> {
+    const numericQuery = /^\d+$/.test(query.trim())
+      ? Number(query.trim())
+      : null;
+
+    return prisma.opportunity.count({
+      where: {
+        ...(opts?.includeClosed ? {} : { closedFlag: false }),
+        OR: [
+          { name: { contains: query, mode: "insensitive" } },
+          { companyName: { contains: query, mode: "insensitive" } },
+          { contactName: { contains: query, mode: "insensitive" } },
+          { notes: { contains: query, mode: "insensitive" } },
+          { primarySalesRepName: { contains: query, mode: "insensitive" } },
+          { statusName: { contains: query, mode: "insensitive" } },
+          { stageName: { contains: query, mode: "insensitive" } },
+          ...(numericQuery !== null
+            ? [{ cwOpportunityId: { equals: numericQuery } }]
+            : []),
+        ],
+      },
+    });
+  },
+
   /**
    * Fetch Opportunities by Company
    *
    * Fetch all opportunities for a company by its internal company ID.
    *
+   * Uses the **cache-only** strategy (same as `fetchPages`).
+   *
    * @param companyId - The internal company ID
    * @param opts - Optional filters
    * @returns {Promise<OpportunityController[]>}
@@ -130,9 +390,23 @@ export const opportunities = {
         companyId,
         ...(opts?.includeClosed ? {} : { closedFlag: false }),
       },
+      include: { company: true },
       orderBy: { expectedCloseDate: "asc" },
     });
 
-    return items.map((item) => new OpportunityController(item));
+    return Promise.all(
+      items.map(async (item) => {
+        return new OpportunityController(item, {
+          company: item.company
+            ? await buildCompanyController(item.company, {
+                strategy: "cache-only",
+              })
+            : undefined,
+          activities: await buildActivities(item.cwOpportunityId, {
+            strategy: "cache-only",
+          }),
+        });
+      }),
+    );
   },
 };

src/managers/procurement.ts

@@ -1,6 +1,11 @@
 import { prisma } from "../constants";
 import { CatalogItemController } from "../controllers/CatalogItemController";
 import GenericError from "../Errors/GenericError";
+import {
+  getSubcategoriesForCategory,
+  getSubcategoriesForGroup,
+  ECOSYSTEM_TREE,
+} from "../modules/catalog-categories/catalogCategories";
 
 /**
  * Standard include clause used by catalog item queries.
@@ -10,6 +15,95 @@ const catalogItemInclude = {
   linkedItems: true,
 } as const;
 
+/**
+ * Filter options for catalog item queries.
+ */
+export interface CatalogFilterOpts {
+  includeInactive?: boolean;
+  category?: string;
+  subcategory?: string;
+  group?: string;
+  manufacturer?: string;
+  ecosystem?: string;
+  inStock?: boolean;
+  minPrice?: number;
+  maxPrice?: number;
+}
+
+/**
+ * Builds a Prisma `where` clause from filter options.
+ */
+function buildFilterWhere(opts: CatalogFilterOpts = {}) {
+  const conditions: Record<string, unknown>[] = [];
+
+  if (!opts.includeInactive) {
+    conditions.push({ inactive: false });
+  }
+
+  if (opts.category) {
+    conditions.push({ category: opts.category });
+  }
+
+  if (opts.subcategory) {
+    conditions.push({ subcategory: opts.subcategory });
+  }
+
+  if (opts.group && opts.category) {
+    const subcats = getSubcategoriesForGroup(opts.category, opts.group);
+    if (subcats.length > 0) {
+      conditions.push({ subcategory: { in: subcats } });
+    }
+  } else if (opts.group && !opts.category) {
+    // Try to find the group in any category
+    const {
+      CATEGORY_TREE,
+      isCategoryGroup,
+    } = require("../modules/catalog-categories/catalogCategories");
+    for (const cat of CATEGORY_TREE) {
+      const subcats = getSubcategoriesForGroup(cat.name, opts.group);
+      if (subcats.length > 0) {
+        conditions.push({ category: cat.name, subcategory: { in: subcats } });
+        break;
+      }
+    }
+  }
+
+  if (opts.manufacturer) {
+    conditions.push({
+      manufacturer: { contains: opts.manufacturer, mode: "insensitive" },
+    });
+  }
+
+  if (opts.ecosystem) {
+    const eco = ECOSYSTEM_TREE.find(
+      (e) => e.name.toLowerCase() === opts.ecosystem!.toLowerCase(),
+    );
+    if (eco && eco.manufacturers.length > 0) {
+      conditions.push({
+        OR: eco.manufacturers.map((m) => ({
+          manufacturer: { contains: m.name, mode: "insensitive" as const },
+          subcategory: { startsWith: m.subcategoryPrefix },
+          category: m.category,
+        })),
+      });
+    }
+  }
+
+  if (opts.inStock) {
+    conditions.push({ onHand: { gt: 0 } });
+  }
+
+  if (opts.minPrice !== undefined) {
+    conditions.push({ price: { gte: opts.minPrice } });
+  }
+
+  if (opts.maxPrice !== undefined) {
+    conditions.push({ price: { lte: opts.maxPrice } });
+  }
+
+  return conditions.length > 0 ? { AND: conditions } : undefined;
+}
+
 export const procurement = {
   /**
    * Fetch Catalog Item
@@ -51,22 +145,23 @@ export const procurement = {
   /**
    * Fetch All Catalog Items (Paginated)
    *
-   * Fetch pages of catalog items for pagination.
+   * Fetch pages of catalog items for pagination with optional filtering.
    *
    * @param page - Page number (1-based)
    * @param rpp  - Records per page
+   * @param opts - Filter options
    * @returns {Promise<CatalogItemController[]>} - Array of catalog item controllers
    */
   async fetchPages(
     page: number,
     rpp: number,
-    opts?: { includeInactive?: boolean },
+    opts?: CatalogFilterOpts,
   ): Promise<CatalogItemController[]> {
     const skip = (Math.max(page, 1) - 1) * rpp;
     const take = rpp;
 
     const items = await prisma.catalogItem.findMany({
-      where: opts?.includeInactive ? undefined : { inactive: false },
+      where: buildFilterWhere(opts),
       skip,
       take,
       include: catalogItemInclude,
@@ -80,25 +175,28 @@ export const procurement = {
    * Search Catalog Items
    *
    * Search catalog items by name, description, part number, or vendor SKU
-   * with pagination support.
+   * with pagination support and optional category/subcategory/ecosystem filters.
    *
    * @param query - Search query string
    * @param page  - Page number (1-based)
    * @param rpp   - Records per page
+   * @param opts  - Filter options
    * @returns {Promise<CatalogItemController[]>} - Array of matching catalog item controllers
    */
   async search(
     query: string,
     page: number,
     rpp: number,
-    opts?: { includeInactive?: boolean },
+    opts?: CatalogFilterOpts,
   ): Promise<CatalogItemController[]> {
     const skip = (Math.max(page, 1) - 1) * rpp;
     const take = rpp;
 
+    const filterWhere = buildFilterWhere(opts) ?? {};
+
     const items = await prisma.catalogItem.findMany({
       where: {
-        ...(opts?.includeInactive ? {} : { inactive: false }),
+        ...filterWhere,
         OR: [
           { identifier: { contains: query, mode: "insensitive" } },
           { name: { contains: query, mode: "insensitive" } },
@@ -120,17 +218,80 @@ export const procurement = {
   /**
    * Count Catalog Items
    *
-   * Returns the total number of catalog items in the database.
+   * Returns the total number of catalog items matching the given filters.
    *
-   * @param opts - Optional filters
+   * @param opts - Filter options
    * @returns {Promise<number>} - Total count
    */
-  async count(opts?: { activeOnly?: boolean }): Promise<number> {
+  async count(
+    opts?: CatalogFilterOpts & { activeOnly?: boolean },
+  ): Promise<number> {
+    // Support legacy `activeOnly` flag by mapping it to `includeInactive`
+    const filterOpts: CatalogFilterOpts = {
+      ...opts,
+      includeInactive:
+        opts?.includeInactive ?? (opts?.activeOnly ? false : true),
+    };
+    if (opts?.activeOnly) filterOpts.includeInactive = false;
+
     return prisma.catalogItem.count({
-      where: opts?.activeOnly ? { inactive: false } : undefined,
+      where: buildFilterWhere(filterOpts),
     });
   },
 
+  /**
+   * Count Catalog Items (with search query)
+   *
+   * Returns the total number of catalog items matching a search query and filters.
+   *
+   * @param query - Search query string
+   * @param opts  - Filter options
+   * @returns {Promise<number>} - Total count
+   */
+  async countSearch(query: string, opts?: CatalogFilterOpts): Promise<number> {
+    const filterWhere = buildFilterWhere(opts) ?? {};
+
+    return prisma.catalogItem.count({
+      where: {
+        ...filterWhere,
+        OR: [
+          { identifier: { contains: query, mode: "insensitive" } },
+          { name: { contains: query, mode: "insensitive" } },
+          { description: { contains: query, mode: "insensitive" } },
+          { partNumber: { contains: query, mode: "insensitive" } },
+          { vendorSku: { contains: query, mode: "insensitive" } },
+          { manufacturer: { contains: query, mode: "insensitive" } },
+        ],
+      },
+    });
+  },
+
+  /**
+   * Fetch Distinct Values
+   *
+   * Returns the distinct values for a given field across all catalog items.
+   * Useful for populating filter dropdowns in the UI.
+   *
+   * @param field - The field to get distinct values for
+   * @param opts  - Filter options to scope the distinct query
+   * @returns {Promise<string[]>} - Sorted array of distinct non-null values
+   */
+  async fetchDistinctValues(
+    field: "category" | "subcategory" | "manufacturer",
+    opts?: CatalogFilterOpts,
+  ): Promise<string[]> {
+    const items = await prisma.catalogItem.findMany({
+      where: buildFilterWhere(opts),
+      select: { [field]: true },
+      distinct: [field],
+      orderBy: { [field]: "asc" },
+    });
+
+    return items
+      .map((item: Record<string, unknown>) => item[field] as string | null)
+      .filter((v): v is string => v !== null);
+  },
+
   /**
    * Link Catalog Items
    *

src/managers/users.ts

@@ -4,6 +4,7 @@ import { prisma } from "../constants";
 import { SessionTokensObject } from "../controllers/SessionController";
 import UserController from "../controllers/UserController";
 import { fetchMicrosoftUser } from "../modules/fetchMicrosoftUser";
+import { findCwIdentifierByEmail } from "../modules/cw-utils/members/fetchAllMembers";
 import { events } from "../modules/globalEvents";
 import { sessions } from "./sessions";
 import * as msal from "@azure/msal-node";
@@ -90,12 +91,18 @@ export const users = {
   async createUser(token: string): Promise<UserController> {
     const msData = await fetchMicrosoftUser(token);
 
+    // Attempt to resolve the user's ConnectWise identifier by email
+    const cwIdentifier = await findCwIdentifierByEmail(msData.mail).catch(
+      () => null,
+    );
+
     const newUser = await prisma.user.create({
       data: {
         userId: msData.id,
         email: msData.mail,
         name: `${msData.givenName} ${msData.surname}`,
         login: msData.userPrincipalName,
+        cwIdentifier,
         token,
       },
       include: { roles: true },

src/modules/algorithms/computeCacheTTL.ts

@@ -0,0 +1,166 @@
+/**
+ * @module computeCacheTTL
+ *
+ * Adaptive Cache TTL Algorithm
+ * ============================
+ *
+ * Determines how long a cached record should live before it must be
+ * re-fetched from the upstream source (e.g. ConnectWise API).
+ *
+ * The algorithm prioritises freshness for records that are actively
+ * being worked on, while avoiding unnecessary API calls for stale or
+ * inactive data.
+ *
+ * ## Spec
+ *
+ * | # | Condition                                                        | TTL (ms) | TTL (human) | Rationale                                                          |
+ * |---|------------------------------------------------------------------|----------|-------------|--------------------------------------------------------------------|
+ * | 1 | `closedFlag` is `true`                                           | `null`   | Do not cache| Closed records are rarely accessed; caching wastes memory.         |
+ * | 2 | `expectedCloseDate` OR `lastUpdated` is within the last **5 days**| 30 000   | 30 seconds  | High-activity window — data changes frequently and must stay fresh.|
+ * | 3 | `expectedCloseDate` OR `lastUpdated` is within the last **14 days**| 60 000  | 60 seconds  | Moderate activity — still relevant, but changes less often.        |
+ * | 4 | Everything else (older than 14 days)                             | 900 000  | 15 minutes  | Low activity — safe to serve from cache for longer.                |
+ *
+ * ## Evaluation order
+ *
+ * Rules are evaluated **top-to-bottom**; the first matching rule wins.
+ * Rule 2 (5-day window) is a subset of Rule 3 (14-day window), so it
+ * must be checked first.
+ *
+ * ## Inputs
+ *
+ * | Field              | Type             | Description                                                        |
+ * |--------------------|------------------|--------------------------------------------------------------------|
+ * | `closedFlag`       | `boolean`        | Whether the record is closed / inactive.                           |
+ * | `expectedCloseDate`| `Date \| null`   | The projected close date (future-looking relevance signal).        |
+ * | `lastUpdated`      | `Date \| null`   | The last time the upstream record was modified (backward-looking). |
+ * | `now`              | `Date` (optional)| Override for the current timestamp; defaults to `new Date()`.      |
+ *
+ * ## Output
+ *
+ * Returns `number | null`:
+ * - A positive integer representing the TTL in **milliseconds**, or
+ * - `null` when the record should **not** be cached at all.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { computeCacheTTL } from "../modules/algorithms/computeCacheTTL";
+ *
+ * const ttl = computeCacheTTL({
+ *   closedFlag: opportunity.closedFlag,
+ *   expectedCloseDate: opportunity.expectedCloseDate,
+ *   lastUpdated: opportunity.cwLastUpdated,
+ * });
+ *
+ * if (ttl !== null) {
+ *   await redis.set(key, serialised, "PX", ttl);
+ * }
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** 30 seconds – TTL for high-activity records (within 5 days). */
+export const TTL_HIGH_ACTIVITY = 30_000;
+
+/** 60 seconds – TTL for moderate-activity records (within 14 days). */
+export const TTL_MODERATE_ACTIVITY = 60_000;
+
+/** 15 minutes – TTL for low-activity / stale records. */
+export const TTL_LOW_ACTIVITY = 900_000;
+
+/** 30 days in milliseconds. */
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** 5 days in milliseconds. */
+const FIVE_DAYS_MS = 5 * 24 * 60 * 60 * 1000;
+
+/** 14 days in milliseconds. */
+const FOURTEEN_DAYS_MS = 14 * 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Input type
+// ---------------------------------------------------------------------------
+
+export interface CacheTTLInput {
+  /** Whether the record is closed / inactive. */
+  closedFlag: boolean;
+  /** When the record was closed — used for recently-closed caching (within 30 days). */
+  closedDate: Date | null;
+  /** The projected close date — serves as a forward-looking relevance signal. */
+  expectedCloseDate: Date | null;
+  /** The date the upstream record was last modified — backward-looking signal. */
+  lastUpdated: Date | null;
+  /**
+   * Override for the current timestamp.
+   * Useful for deterministic testing. Defaults to `new Date()`.
+   */
+  now?: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Algorithm
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the cache TTL for a record based on its activity signals.
+ *
+ * @param input - The record's activity signals. See {@link CacheTTLInput}.
+ * @returns The TTL in milliseconds, or `null` if the record should not be cached.
+ *
+ * @see Module-level JSDoc for the full spec table and evaluation rules.
+ */
+export function computeCacheTTL(input: CacheTTLInput): number | null {
+  const {
+    closedFlag,
+    closedDate,
+    expectedCloseDate,
+    lastUpdated,
+    now = new Date(),
+  } = input;
+
+  const nowMs = now.getTime();
+
+  /**
+   * Check whether a date falls within a window around `now`.
+   *
+   * "Within" means the date is between `now - windowMs` and `now + windowMs`,
+   * allowing both past updates and future-scheduled dates to qualify.
+   */
+  const isWithinWindow = (date: Date | null, windowMs: number): boolean => {
+    if (!date) return false;
+    const diff = Math.abs(nowMs - date.getTime());
+    return diff <= windowMs;
+  };
+
+  // Rule 1 — Closed records
+  if (closedFlag) {
+    // Rule 1b — Recently closed (within 30 days) → cache at low-activity TTL
+    if (isWithinWindow(closedDate, THIRTY_DAYS_MS)) {
+      return TTL_LOW_ACTIVITY;
+    }
+    // Rule 1a — Closed longer than 30 days → do not cache
+    return null;
+  }
+
+  // Rule 2 — High activity (5 days)
+  if (
+    isWithinWindow(expectedCloseDate, FIVE_DAYS_MS) ||
+    isWithinWindow(lastUpdated, FIVE_DAYS_MS)
+  ) {
+    return TTL_HIGH_ACTIVITY;
+  }
+
+  // Rule 3 — Moderate activity (14 days)
+  if (
+    isWithinWindow(expectedCloseDate, FOURTEEN_DAYS_MS) ||
+    isWithinWindow(lastUpdated, FOURTEEN_DAYS_MS)
+  ) {
+    return TTL_MODERATE_ACTIVITY;
+  }
+
+  // Rule 4 — Low activity / stale
+  return TTL_LOW_ACTIVITY;
+}

src/modules/cache/opportunityCache.ts

@@ -0,0 +1,257 @@
+/**
+ * @module opportunityCache
+ *
+ * Redis-backed cache for expensive ConnectWise API data associated
+ * with opportunities.
+ *
+ * ## What is cached
+ *
+ * Each non-closed opportunity may have two cached payloads keyed by
+ * its `cwOpportunityId`:
+ *
+ * - **Activities** (`opp:activities:{cwOpportunityId}`) — the raw
+ *   `CWActivity[]` array fetched from `activityCw.fetchByOpportunity()`.
+ * - **Company CW data** (`opp:company-cw:{cw_CompanyId}`) — the hydrated
+ *   company / contacts blob set by `CompanyController.hydrateCwData()`.
+ *
+ * TTLs are computed dynamically via {@link computeCacheTTL} so hot
+ * opportunities refresh every 30 s while stale ones live for 15 min.
+ *
+ * ## Background refresh
+ *
+ * {@link refreshOpportunityCache} is designed to be called on a
+ * 30-second interval from `src/index.ts`. It scans all non-closed
+ * DB opportunities, checks which cache keys have expired, and
+ * re-fetches only those from ConnectWise.
+ */
+
+import { prisma, redis } from "../../constants";
+import { activityCw } from "../cw-utils/activities/activities";
+import { computeCacheTTL } from "../algorithms/computeCacheTTL";
+import { connectWiseApi } from "../../constants";
+import { fetchCwCompanyById } from "../cw-utils/fetchCompany";
+import { events } from "../globalEvents";
+
+// ---------------------------------------------------------------------------
+// Key helpers
+// ---------------------------------------------------------------------------
+
+const ACTIVITY_PREFIX = "opp:activities:";
+const COMPANY_CW_PREFIX = "opp:company-cw:";
+
+/** Redis key for cached activities by CW opportunity ID. */
+export const activityCacheKey = (cwOppId: number) =>
+  `${ACTIVITY_PREFIX}${cwOppId}`;
+
+/** Redis key for cached company CW hydration data by CW company ID. */
+export const companyCwCacheKey = (cwCompanyId: number) =>
+  `${COMPANY_CW_PREFIX}${cwCompanyId}`;
+
+// ---------------------------------------------------------------------------
+// Read helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieve cached CW activities for an opportunity.
+ *
+ * @returns The parsed `CWActivity[]` or `null` on cache miss.
+ */
+export async function getCachedActivities(
+  cwOpportunityId: number,
+): Promise<any[] | null> {
+  const raw = await redis.get(activityCacheKey(cwOpportunityId));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Retrieve cached company CW hydration data.
+ *
+ * @returns `{ company, defaultContact, allContacts }` or `null` on cache miss.
+ */
+export async function getCachedCompanyCwData(
+  cwCompanyId: number,
+): Promise<{ company: any; defaultContact: any; allContacts: any[] } | null> {
+  const raw = await redis.get(companyCwCacheKey(cwCompanyId));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch activities from CW and cache them with the appropriate TTL.
+ *
+ * @returns The raw `CWActivity[]` collection (as plain array).
+ */
+export async function fetchAndCacheActivities(
+  cwOpportunityId: number,
+  ttlMs: number,
+): Promise<any[]> {
+  const collection = await activityCw.fetchByOpportunity(cwOpportunityId);
+  const arr = collection.map((item) => item);
+  await redis.set(
+    activityCacheKey(cwOpportunityId),
+    JSON.stringify(arr),
+    "PX",
+    ttlMs,
+  );
+  return arr;
+}
+
+/**
+ * Fetch company CW data (company, contacts) and cache with the given TTL.
+ *
+ * @returns The hydration blob or `null` if the company doesn't exist in CW.
+ */
+export async function fetchAndCacheCompanyCwData(
+  cwCompanyId: number,
+  ttlMs: number,
+): Promise<{ company: any; defaultContact: any; allContacts: any[] } | null> {
+  const cwCompany = await fetchCwCompanyById(cwCompanyId);
+  if (!cwCompany) return null;
+
+  const contactHref = cwCompany.defaultContact?._info?.contact_href;
+  const defaultContactData = contactHref
+    ? await connectWiseApi.get(contactHref)
+    : undefined;
+
+  const allContactsData = await connectWiseApi.get(
+    `${cwCompany._info.contacts_href}&pageSize=1000`,
+  );
+
+  const blob = {
+    company: cwCompany,
+    defaultContact: defaultContactData?.data ?? null,
+    allContacts: allContactsData.data,
+  };
+
+  await redis.set(
+    companyCwCacheKey(cwCompanyId),
+    JSON.stringify(blob),
+    "PX",
+    ttlMs,
+  );
+
+  return blob;
+}
+
+// ---------------------------------------------------------------------------
+// Background refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Refresh the opportunity cache.
+ *
+ * Scans all non-closed opportunities in the database, computes a TTL for each,
+ * checks whether the cache key still exists, and re-fetches from ConnectWise
+ * only for entries that have expired.
+ *
+ * Designed to be called every **30 seconds** from the process entry point.
+ */
+export async function refreshOpportunityCache(): Promise<void> {
+  // Include non-closed AND recently-closed (within 30 days) opportunities
+  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+
+  const opportunities = await prisma.opportunity.findMany({
+    where: {
+      OR: [
+        { closedFlag: false },
+        { closedFlag: true, closedDate: { gte: thirtyDaysAgo } },
+      ],
+    },
+    select: {
+      cwOpportunityId: true,
+      closedFlag: true,
+      closedDate: true,
+      expectedCloseDate: true,
+      cwLastUpdated: true,
+      company: { select: { cw_CompanyId: true } },
+    },
+  });
+
+  events.emit("cache:opportunities:refresh:started", {
+    totalOpportunities: opportunities.length,
+  });
+
+  let activitiesRefreshed = 0;
+  let companiesRefreshed = 0;
+  let skipped = 0;
+
+  // Batch-check which activity keys already exist via a pipeline
+  const pipeline = redis.pipeline();
+  for (const opp of opportunities) {
+    pipeline.exists(activityCacheKey(opp.cwOpportunityId));
+  }
+  const existsResults = await pipeline.exec();
+
+  const refreshTasks: Promise<void>[] = [];
+
+  for (let i = 0; i < opportunities.length; i++) {
+    const opp = opportunities[i]!;
+
+    const ttl = computeCacheTTL({
+      closedFlag: opp.closedFlag,
+      closedDate: opp.closedDate,
+      expectedCloseDate: opp.expectedCloseDate,
+      lastUpdated: opp.cwLastUpdated,
+    });
+
+    // Skip closed (ttl === null) — should not happen because of the query filter,
+    // but guard anyway.
+    if (ttl === null) {
+      skipped++;
+      continue;
+    }
+
+    // existsResults entries are [error, result] tuples
+    const activityExists = existsResults?.[i]?.[1] === 1;
+
+    if (!activityExists) {
+      refreshTasks.push(
+        fetchAndCacheActivities(opp.cwOpportunityId, ttl).then(() => {
+          activitiesRefreshed++;
+        }),
+      );
+    }
+
+    // Also refresh company CW data if the key is missing
+    if (opp.company?.cw_CompanyId) {
+      const cwCompanyId = opp.company.cw_CompanyId;
+      refreshTasks.push(
+        (async () => {
+          const companyExists = await redis.exists(
+            companyCwCacheKey(cwCompanyId),
+          );
+          if (!companyExists) {
+            await fetchAndCacheCompanyCwData(cwCompanyId, ttl);
+            companiesRefreshed++;
+          }
+        })(),
+      );
+    }
+  }
+
+  // Run all refresh tasks concurrently with bounded concurrency
+  const CONCURRENCY = 10;
+  for (let i = 0; i < refreshTasks.length; i += CONCURRENCY) {
+    await Promise.allSettled(refreshTasks.slice(i, i + CONCURRENCY));
+  }
+
+  events.emit("cache:opportunities:refresh:completed", {
+    totalOpportunities: opportunities.length,
+    activitiesRefreshed,
+    companiesRefreshed,
+    skipped,
+  });
+}

src/modules/catalog-categories/catalogCategories.ts

@@ -0,0 +1,498 @@
+/**
+ * Catalog Categories & Ecosystems
+ *
+ * This module defines the complete category/subcategory hierarchy and
+ * ecosystem decision trees used for product filtering in the UI.
+ *
+ * --- Terminology ---
+ *
+ * Category:     Top-level CW category (e.g. "Technology", "Field", "General").
+ *               A category is NEVER a subcategory.
+ *
+ * Subcategory:  The CW subcategory name stored on each catalog item.
+ *               At the second level of the tree, if there are no children
+ *               beneath it then the node name IS the subcategory.
+ *               If children exist, the second-level node is an *umbrella*
+ *               that groups related subcategories — the children are the
+ *               actual subcategory names.
+ *
+ * Ecosystem:    A cross-cutting product grouping defined by manufacturer +
+ *               category + subcategory-prefix rules. Ecosystems let the UI
+ *               present a "Networking" or "Video Surveillance" view that
+ *               spans manufacturers regardless of where CW filed them.
+ *
+ * --- Data shapes ---
+ *
+ * SubcategoryNode  – a leaf: `{ name, cwId? }`
+ * CategoryGroup    – an umbrella with children: `{ name, children[] }`
+ * CategoryEntry    – either a leaf OR a group at the 2nd level
+ * TopLevelCategory – `{ name, cwId?, entries[] }`
+ *
+ * The `CATEGORY_TREE` export is the single source of truth; helpers derive
+ * flat lists, lookup maps, and search predicates from it.
+ */
+
+// ─── Data types ──────────────────────────────────────────────────────────────
+
+export interface SubcategoryNode {
+  /** The exact CW subcategory name */
+  name: string;
+  /** CW subcategory id (optional, for reference) */
+  cwId?: number;
+}
+
+export interface CategoryGroup {
+  /** Display name of the umbrella (e.g. "Network", "Cables", "AlarmBurg") */
+  name: string;
+  /** The subcategories that belong to this umbrella */
+  children: SubcategoryNode[];
+}
+
+/** A second-level entry is either a direct subcategory or an umbrella group */
+export type CategoryEntry = SubcategoryNode | CategoryGroup;
+
+export interface TopLevelCategory {
+  /** The CW category name */
+  name: string;
+  /** CW category id (optional, for reference) */
+  cwId?: number;
+  /** Second-level entries under this category */
+  entries: CategoryEntry[];
+}
+
+/** Helper type guard */
+export function isCategoryGroup(entry: CategoryEntry): entry is CategoryGroup {
+  return "children" in entry;
+}
+
+// ─── Ecosystem types ─────────────────────────────────────────────────────────
+
+export interface EcosystemManufacturer {
+  /** Manufacturer name as stored in CW */
+  name: string;
+  /** CW manufacturer id */
+  cwId?: number;
+  /** Which CW category these products fall under */
+  category: string;
+  /** Subcategory prefix — matches any subcategory starting with this string */
+  subcategoryPrefix: string;
+}
+
+export interface Ecosystem {
+  /** Display name (e.g. "Networking", "Video Surveillance") */
+  name: string;
+  /** Manufacturers that belong to this ecosystem */
+  manufacturers: EcosystemManufacturer[];
+}
+
+// ─── Category Tree ───────────────────────────────────────────────────────────
+
+export const CATEGORY_TREE: TopLevelCategory[] = [
+  {
+    name: "Technology",
+    cwId: 18,
+    entries: [
+      { name: "GeneralEquip", cwId: 57 },
+      { name: "Home Entertainment", cwId: 114 },
+      { name: "Monitor", cwId: 115 },
+      { name: "Printers", cwId: 120 },
+      { name: "Storage", cwId: 108 },
+      {
+        name: "Network",
+        children: [
+          { name: "Network-Other", cwId: 174 },
+          { name: "Network-Router", cwId: 119 },
+          { name: "Network-Switch", cwId: 112 },
+          { name: "Network-Wireless", cwId: 111 },
+        ],
+      },
+      {
+        name: "Computer",
+        children: [
+          { name: "Computer-Components", cwId: 109 },
+          { name: "Computer-Desktop", cwId: 106 },
+          { name: "Computer-Laptop", cwId: 107 },
+        ],
+      },
+      {
+        name: "Recurring",
+        children: [
+          { name: "Recurring - Online", cwId: 83 },
+          { name: "Recurring - Other", cwId: 84 },
+          { name: "Recurring - Protection", cwId: 81 },
+          { name: "Recurring - Telephone", cwId: 133 },
+        ],
+      },
+      {
+        name: "Telephone",
+        children: [
+          { name: "Tele-HSet-Digital", cwId: 116 },
+          { name: "Tele-HSet-IP", cwId: 206 },
+          { name: "Tele-HSet-SLT" },
+          { name: "Tele-Misc", cwId: 75 },
+          { name: "Tele-Paging", cwId: 76 },
+          { name: "Tele-SystemCards", cwId: 135 },
+          { name: "Tele-Systems", cwId: 78 },
+        ],
+      },
+    ],
+  },
+  {
+    name: "General",
+    cwId: 25,
+    entries: [
+      { name: "Batteries", cwId: 80 },
+      { name: "Battery Backups", cwId: 144 },
+      { name: "BulkWire", cwId: 200 },
+      {
+        name: "Cables",
+        children: [
+          { name: "Cables-Adapters", cwId: 182 },
+          { name: "Cables-HDMI", cwId: 176 },
+          { name: "Cables-Network", cwId: 87 },
+          { name: "Cables-Other", cwId: 177 },
+          { name: "Cables-USB", cwId: 178 },
+          { name: "Cables-VGA", cwId: 179 },
+        ],
+      },
+      { name: "Elec Cords & Adapters", cwId: 142 },
+      { name: "Enclosures", cwId: 141 },
+      { name: "PowerSupply", cwId: 167 },
+      {
+        name: "RackEquip",
+        children: [
+          { name: "RackEquip-Rack", cwId: 143 },
+          { name: "RackEquip-Shelves", cwId: 190 },
+        ],
+      },
+    ],
+  },
+  {
+    name: "Field",
+    cwId: 28,
+    entries: [
+      { name: "Conduit" },
+      { name: "Electric", cwId: 199 },
+      { name: "GateControl", cwId: 45 },
+      { name: "Locksets" },
+      { name: "Other", cwId: 46 },
+      { name: "Relays", cwId: 168 },
+      {
+        name: "AccessControl",
+        children: [
+          { name: "AccessControl-Controllers", cwId: 137 },
+          { name: "AccessControl-Credential", cwId: 183 },
+          { name: "AccessControl-LockDevices", cwId: 138 },
+          { name: "AccessControl-Other", cwId: 44 },
+          { name: "AccessControl-Readers", cwId: 136 },
+          { name: "AccessControl-VideoEntry", cwId: 139 },
+        ],
+      },
+      {
+        name: "AlarmBurg",
+        children: [
+          { name: "AlarmBurg-Communicators", cwId: 96 },
+          { name: "AlarmBurg-Keypads", cwId: 93 },
+          { name: "AlarmBurg-Modules", cwId: 140 },
+          { name: "AlarmBurg-Other", cwId: 92 },
+          { name: "AlarmBurg-Panels", cwId: 42 },
+          { name: "AlarmBurg-Sensors-Wireless", cwId: 147 },
+          { name: "AlarmBurg-Sensors-Wired", cwId: 146 },
+          { name: "AlarmBurg-Siren", cwId: 145 },
+        ],
+      },
+      {
+        name: "AlarmFire",
+        children: [
+          { name: "AlarmFire-Communicators", cwId: 97 },
+          { name: "AlarmFire-Devices", cwId: 169 },
+          { name: "AlarmFire-Modules", cwId: 170 },
+          { name: "AlarmFire-Other", cwId: 98 },
+          { name: "AlarmFire-Panels", cwId: 95 },
+          { name: "AlarmFire-Sensors", cwId: 94 },
+        ],
+      },
+      {
+        name: "Automation",
+        children: [
+          { name: "Automation-General", cwId: 99 },
+          { name: "Automation-HVAC", cwId: 181 },
+          { name: "Automation-Lights", cwId: 180 },
+          { name: "Automation-Locks", cwId: 192 },
+          { name: "Automation-Thermostat" },
+        ],
+      },
+      {
+        name: "AV",
+        children: [
+          { name: "AV-Adapters&Cables", cwId: 171 },
+          { name: "AV-Components", cwId: 172 },
+          { name: "AV-Mounts", cwId: 191 },
+          { name: "AV-Other", cwId: 184 },
+          { name: "AV-Speakers", cwId: 173 },
+          { name: "AV-Television", cwId: 175 },
+        ],
+      },
+      {
+        name: "StrCbl",
+        children: [
+          { name: "StrCbl-Jacks", cwId: 186 },
+          { name: "StrCbl-PatchPanel", cwId: 187 },
+          { name: "StrCbl-Plates", cwId: 185 },
+        ],
+      },
+      {
+        name: "Surveillance",
+        children: [
+          { name: "Surveillance-Accs", cwId: 90 },
+          { name: "Surveillance-CamerasAnalog", cwId: 89 },
+          { name: "Surveillance-CamerasIP", cwId: 88 },
+          { name: "Surveillance-NVR", cwId: 43 },
+        ],
+      },
+    ],
+  },
+];
+
+// ─── Ecosystem Tree ──────────────────────────────────────────────────────────
+
+export const ECOSYSTEM_TREE: Ecosystem[] = [
+  {
+    name: "Networking",
+    manufacturers: [
+      {
+        name: "Ubiquiti",
+        cwId: 248,
+        category: "Technology",
+        subcategoryPrefix: "Network-",
+      },
+      {
+        name: "TP-Link",
+        cwId: 259,
+        category: "Technology",
+        subcategoryPrefix: "Network-",
+      },
+    ],
+  },
+  {
+    name: "Video Surveillance",
+    manufacturers: [
+      {
+        name: "Uniview",
+        cwId: 239,
+        category: "Field",
+        subcategoryPrefix: "Surveillance-",
+      },
+      {
+        name: "Hikvision",
+        cwId: 299,
+        category: "Field",
+        subcategoryPrefix: "Surveillance-",
+      },
+      {
+        name: "Alarm.com",
+        cwId: 294,
+        category: "Field",
+        subcategoryPrefix: "Surveillance-",
+      },
+    ],
+  },
+  {
+    name: "Burg/Alarm",
+    manufacturers: [
+      {
+        name: "Qolsys",
+        cwId: 376,
+        category: "Field",
+        subcategoryPrefix: "AlarmBurg-",
+      },
+      {
+        name: "DSC",
+        cwId: 287,
+        category: "Field",
+        subcategoryPrefix: "AlarmBurg-",
+      },
+    ],
+  },
+];
+
+// ─── Derived helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Returns a flat list of all subcategory names under a given category.
+ */
+export function getSubcategoriesForCategory(categoryName: string): string[] {
+  const category = CATEGORY_TREE.find((c) => c.name === categoryName);
+  if (!category) return [];
+
+  const subcats: string[] = [];
+  for (const entry of category.entries) {
+    if (isCategoryGroup(entry)) {
+      for (const child of entry.children) {
+        subcats.push(child.name);
+      }
+    } else {
+      subcats.push(entry.name);
+    }
+  }
+  return subcats;
+}
+
+/**
+ * Returns all subcategory names under a given umbrella group within a category.
+ * e.g. getSubcategoriesForGroup("Field", "AlarmBurg") → ["AlarmBurg-Communicators", ...]
+ */
+export function getSubcategoriesForGroup(
+  categoryName: string,
+  groupName: string,
+): string[] {
+  const category = CATEGORY_TREE.find((c) => c.name === categoryName);
+  if (!category) return [];
+
+  const group = category.entries.find(
+    (e) => isCategoryGroup(e) && e.name === groupName,
+  );
+  if (!group || !isCategoryGroup(group)) return [];
+
+  return group.children.map((c) => c.name);
+}
+
+/**
+ * Returns all top-level category names.
+ */
+export function getCategoryNames(): string[] {
+  return CATEGORY_TREE.map((c) => c.name);
+}
+
+/**
+ * Returns the umbrella group name for a given subcategory, or null if it's a
+ * direct entry (not under an umbrella).
+ */
+export function getGroupForSubcategory(
+  subcategoryName: string,
+): { category: string; group: string } | null {
+  for (const cat of CATEGORY_TREE) {
+    for (const entry of cat.entries) {
+      if (isCategoryGroup(entry)) {
+        if (entry.children.some((c) => c.name === subcategoryName)) {
+          return { category: cat.name, group: entry.name };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns the full tree serialized for the API / UI consumption.
+ * Each top-level category includes its entries, with umbrella groups
+ * expanded to show children.
+ */
+export function serializeCategoryTree() {
+  return CATEGORY_TREE.map((cat) => ({
+    name: cat.name,
+    cwId: cat.cwId ?? null,
+    entries: cat.entries.map((entry) => {
+      if (isCategoryGroup(entry)) {
+        return {
+          type: "group" as const,
+          name: entry.name,
+          subcategories: entry.children.map((c) => ({
+            name: c.name,
+            cwId: c.cwId ?? null,
+          })),
+        };
+      }
+      return {
+        type: "subcategory" as const,
+        name: entry.name,
+        cwId: (entry as SubcategoryNode).cwId ?? null,
+      };
+    }),
+  }));
+}
+
+/**
+ * Returns the ecosystem tree serialized for the API / UI consumption.
+ */
+export function serializeEcosystemTree() {
+  return ECOSYSTEM_TREE.map((eco) => ({
+    name: eco.name,
+    manufacturers: eco.manufacturers.map((m) => ({
+      name: m.name,
+      cwId: m.cwId ?? null,
+      category: m.category,
+      subcategoryPrefix: m.subcategoryPrefix,
+    })),
+  }));
+}
+
+/**
+ * Returns a flat list of every known subcategory name across all categories.
+ */
+export function getAllSubcategoryNames(): string[] {
+  const names: string[] = [];
+  for (const cat of CATEGORY_TREE) {
+    for (const entry of cat.entries) {
+      if (isCategoryGroup(entry)) {
+        for (const child of entry.children) {
+          names.push(child.name);
+        }
+      } else {
+        names.push(entry.name);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Given a CW subcategory name, resolves which top-level category it belongs to.
+ */
+export function getCategoryForSubcategory(
+  subcategoryName: string,
+): string | null {
+  for (const cat of CATEGORY_TREE) {
+    for (const entry of cat.entries) {
+      if (isCategoryGroup(entry)) {
+        if (entry.children.some((c) => c.name === subcategoryName)) {
+          return cat.name;
+        }
+      } else if (entry.name === subcategoryName) {
+        return cat.name;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Given a CW manufacturer name, returns which ecosystems it belongs to.
+ */
+export function getEcosystemsForManufacturer(
+  manufacturerName: string,
+): string[] {
+  return ECOSYSTEM_TREE.filter((eco) =>
+    eco.manufacturers.some(
+      (m) => m.name.toLowerCase() === manufacturerName.toLowerCase(),
+    ),
+  ).map((eco) => eco.name);
+}
+
+/**
+ * Checks if a catalog item (by manufacturer + subcategory) matches a given ecosystem.
+ */
+export function matchesEcosystem(
+  ecosystemName: string,
+  manufacturer: string | null,
+  subcategory: string | null,
+): boolean {
+  const eco = ECOSYSTEM_TREE.find((e) => e.name === ecosystemName);
+  if (!eco) return false;
+
+  return eco.manufacturers.some(
+    (m) =>
+      m.name.toLowerCase() === (manufacturer ?? "").toLowerCase() &&
+      (subcategory ?? "").startsWith(m.subcategoryPrefix),
+  );
+}

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

@@ -0,0 +1,168 @@
+import { Collection } from "@discordjs/collection";
+import { connectWiseApi } from "../../../constants";
+import {
+  CWActivity,
+  CWActivitySummary,
+  CWCreateActivity,
+  CWPatchOperation,
+} from "./activity.types";
+
+export const activityCw = {
+  /**
+   * Count Activities
+   *
+   * Returns the total number of activities in ConnectWise.
+   * Optionally accepts CW conditions string for filtered counts.
+   */
+  countItems: async (conditions?: string): Promise<number> => {
+    const query = conditions
+      ? `/sales/activities/count?conditions=${encodeURIComponent(conditions)}`
+      : "/sales/activities/count";
+    const response = await connectWiseApi.get(query);
+    return response.data.count;
+  },
+
+  /**
+   * Fetch All Activity Summaries
+   *
+   * Lightweight fetch returning only id and _info (for lastUpdated comparison).
+   * Paginates through all activities.
+   */
+  fetchAllSummaries: async (): Promise<
+    Collection<number, CWActivitySummary>
+  > => {
+    const allItems = new Collection<number, CWActivitySummary>();
+    const pageSize = 1000;
+
+    const count = await activityCw.countItems();
+    const totalPages = Math.ceil(count / pageSize);
+
+    for (let page = 0; page < totalPages; page++) {
+      const response = await connectWiseApi.get(
+        `/sales/activities?page=${page + 1}&pageSize=${pageSize}&fields=id,_info`,
+      );
+      const items: CWActivitySummary[] = response.data;
+
+      for (const item of items) {
+        allItems.set(item.id, item);
+      }
+    }
+
+    return allItems;
+  },
+
+  /**
+   * Fetch All Activities (Full)
+   *
+   * Fetches all activities with complete data. Paginates through
+   * the full list. Optionally accepts CW conditions string for filtering.
+   */
+  fetchAll: async (
+    conditions?: string,
+  ): Promise<Collection<number, CWActivity>> => {
+    const allItems = new Collection<number, CWActivity>();
+    const pageSize = 1000;
+
+    const count = await activityCw.countItems(conditions);
+    const totalPages = Math.ceil(count / pageSize);
+
+    for (let page = 0; page < totalPages; page++) {
+      const conditionsParam = conditions
+        ? `&conditions=${encodeURIComponent(conditions)}`
+        : "";
+      const response = await connectWiseApi.get(
+        `/sales/activities?page=${page + 1}&pageSize=${pageSize}${conditionsParam}`,
+      );
+      const items: CWActivity[] = response.data;
+
+      for (const item of items) {
+        allItems.set(item.id, item);
+      }
+    }
+
+    return allItems;
+  },
+
+  /**
+   * Fetch Single Activity
+   *
+   * Fetches a single activity by its ConnectWise ID.
+   */
+  fetch: async (id: number): Promise<CWActivity> => {
+    const response = await connectWiseApi.get(`/sales/activities/${id}`);
+    return response.data;
+  },
+
+  /**
+   * Fetch Activities by Company
+   *
+   * Fetches all activities associated with a specific ConnectWise company ID.
+   */
+  fetchByCompany: async (
+    cwCompanyId: number,
+  ): Promise<Collection<number, CWActivity>> => {
+    return activityCw.fetchAll(`company/id=${cwCompanyId}`);
+  },
+
+  /**
+   * Fetch Activities by Opportunity
+   *
+   * Fetches all activities associated with a specific opportunity ID.
+   */
+  fetchByOpportunity: async (
+    opportunityId: number,
+  ): Promise<Collection<number, CWActivity>> => {
+    return activityCw.fetchAll(`opportunity/id=${opportunityId}`);
+  },
+
+  /**
+   * Create Activity
+   *
+   * Creates a new activity in ConnectWise.
+   */
+  create: async (activity: CWCreateActivity): Promise<CWActivity> => {
+    const response = await connectWiseApi.post("/sales/activities", activity);
+    return response.data;
+  },
+
+  /**
+   * Update Activity (PATCH)
+   *
+   * Updates an existing activity using JSON Patch operations.
+   */
+  update: async (
+    id: number,
+    operations: CWPatchOperation[],
+  ): Promise<CWActivity> => {
+    const response = await connectWiseApi.patch(
+      `/sales/activities/${id}`,
+      operations,
+    );
+    return response.data;
+  },
+
+  /**
+   * Replace Activity (PUT)
+   *
+   * Replaces an entire activity record in ConnectWise.
+   */
+  replace: async (
+    id: number,
+    activity: CWCreateActivity,
+  ): Promise<CWActivity> => {
+    const response = await connectWiseApi.put(
+      `/sales/activities/${id}`,
+      activity,
+    );
+    return response.data;
+  },
+
+  /**
+   * Delete Activity
+   *
+   * Deletes an activity by its ConnectWise ID.
+   */
+  delete: async (id: number): Promise<void> => {
+    await connectWiseApi.delete(`/sales/activities/${id}`);
+  },
+};

src/modules/cw-utils/activities/activity.types.ts

@@ -0,0 +1,123 @@
+interface CWReference {
+  id: number;
+  name: string;
+  _info?: Record<string, string>;
+}
+
+interface CWMemberReference {
+  id: number;
+  identifier: string;
+  name: string;
+  _info?: Record<string, string>;
+}
+
+interface CWCompanyReference {
+  id: number;
+  identifier: string;
+  name: string;
+  _info?: Record<string, string>;
+}
+
+interface CWContactReference {
+  id: number;
+  name: string;
+  _info?: Record<string, string>;
+}
+
+export interface CWActivity {
+  id: number;
+  name: string;
+  type: CWReference;
+  company: CWCompanyReference;
+  contact: CWContactReference;
+  phoneNumber: string;
+  email: string;
+  status: CWReference;
+  opportunity: CWReference;
+  ticket: CWReference;
+  agreement: CWReference;
+  campaign: CWReference;
+  notes: string;
+  dateStart: string;
+  dateEnd: string;
+  assignTo: CWMemberReference;
+  scheduleStatus: CWReference;
+  reminder: CWReference;
+  where: CWReference;
+  notifyFlag: boolean;
+  mobileGuid: string;
+  currency: CWReference;
+  customFields: CWActivityCustomField[];
+  _info: CWActivityInfo;
+}
+
+export interface CWActivityCustomField {
+  id: number;
+  caption: string;
+  type: string;
+  entryMethod: string;
+  numberOfDecimals: number;
+  value: unknown;
+}
+
+export interface CWActivityInfo {
+  lastUpdated: string;
+  updatedBy: string;
+  dateEntered: string;
+  enteredBy: string;
+}
+
+export interface CWActivitySummary {
+  id: number;
+  _info?: Record<string, string>;
+}
+
+export interface CWCreateActivity {
+  name: string;
+  type?: { id: number };
+  company?: { id: number };
+  contact?: { id: number };
+  phoneNumber?: string;
+  email?: string;
+  status?: { id: number };
+  opportunity?: { id: number };
+  ticket?: { id: number };
+  agreement?: { id: number };
+  campaign?: { id: number };
+  notes?: string;
+  dateStart?: string;
+  dateEnd?: string;
+  assignTo?: { id: number };
+  scheduleStatus?: { id: number };
+  reminder?: { id: number };
+  where?: { id: number };
+  notifyFlag?: boolean;
+}
+
+export interface CWUpdateActivity {
+  name?: string;
+  type?: { id: number };
+  company?: { id: number };
+  contact?: { id: number };
+  phoneNumber?: string;
+  email?: string;
+  status?: { id: number };
+  opportunity?: { id: number };
+  ticket?: { id: number };
+  agreement?: { id: number };
+  campaign?: { id: number };
+  notes?: string;
+  dateStart?: string;
+  dateEnd?: string;
+  assignTo?: { id: number };
+  scheduleStatus?: { id: number };
+  reminder?: { id: number };
+  where?: { id: number };
+  notifyFlag?: boolean;
+}
+
+export interface CWPatchOperation {
+  op: "replace" | "add" | "remove";
+  path: string;
+  value: unknown;
+}

src/modules/cw-utils/activities/createActivity.ts

@@ -0,0 +1,27 @@
+import GenericError from "../../../Errors/GenericError";
+import { activityCw } from "./activities";
+import { CWActivity, CWCreateActivity } from "./activity.types";
+
+/**
+ * Create a new activity in ConnectWise.
+ *
+ * @param activity - The activity data to create
+ * @returns The newly created CW activity object
+ * @throws GenericError if the creation fails
+ */
+export const createActivity = async (
+  activity: CWCreateActivity,
+): Promise<CWActivity> => {
+  try {
+    return await activityCw.create(activity);
+  } catch (error) {
+    const errBody = (error as any).response?.data || error;
+    console.error("Error creating activity:", errBody);
+    throw new GenericError({
+      name: "CreateActivityError",
+      message: "Failed to create activity in ConnectWise",
+      cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+      status: 502,
+    });
+  }
+};

src/modules/cw-utils/activities/fetchActivity.ts

@@ -0,0 +1,27 @@
+import GenericError from "../../../Errors/GenericError";
+import { activityCw } from "./activities";
+import { CWActivity } from "./activity.types";
+
+/**
+ * Fetch a single activity by its ConnectWise ID.
+ *
+ * @param cwActivityId - The ConnectWise activity ID
+ * @returns The full CW activity object
+ * @throws GenericError if the fetch fails
+ */
+export const fetchActivity = async (
+  cwActivityId: number,
+): Promise<CWActivity> => {
+  try {
+    return await activityCw.fetch(cwActivityId);
+  } catch (error) {
+    const errBody = (error as any).response?.data || error;
+    console.error(`Error fetching activity with ID ${cwActivityId}:`, errBody);
+    throw new GenericError({
+      name: "FetchActivityError",
+      message: `Failed to fetch activity ${cwActivityId}`,
+      cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+      status: 502,
+    });
+  }
+};

src/modules/cw-utils/activities/fetchAllActivities.ts

@@ -0,0 +1,28 @@
+import { Collection } from "@discordjs/collection";
+import GenericError from "../../../Errors/GenericError";
+import { activityCw } from "./activities";
+import { CWActivity } from "./activity.types";
+
+/**
+ * Fetch all activities from ConnectWise with optional conditions.
+ *
+ * @param conditions - Optional CW conditions string for filtering
+ * @returns A Collection of CW activities keyed by their ID
+ * @throws GenericError if the fetch fails
+ */
+export const fetchAllActivities = async (
+  conditions?: string,
+): Promise<Collection<number, CWActivity>> => {
+  try {
+    return await activityCw.fetchAll(conditions);
+  } catch (error) {
+    const errBody = (error as any).response?.data || error;
+    console.error("Error fetching all activities:", errBody);
+    throw new GenericError({
+      name: "FetchAllActivitiesError",
+      message: "Failed to fetch activities from ConnectWise",
+      cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+      status: 502,
+    });
+  }
+};

src/modules/cw-utils/activities/index.ts

@@ -0,0 +1,15 @@
+export { activityCw } from "./activities";
+export { fetchActivity } from "./fetchActivity";
+export { fetchAllActivities } from "./fetchAllActivities";
+export { createActivity } from "./createActivity";
+export { updateActivity } from "./updateActivity";
+
+export type {
+  CWActivity,
+  CWActivitySummary,
+  CWActivityCustomField,
+  CWActivityInfo,
+  CWCreateActivity,
+  CWUpdateActivity,
+  CWPatchOperation,
+} from "./activity.types";

src/modules/cw-utils/activities/updateActivity.ts

@@ -0,0 +1,29 @@
+import GenericError from "../../../Errors/GenericError";
+import { activityCw } from "./activities";
+import { CWActivity, CWPatchOperation } from "./activity.types";
+
+/**
+ * Update an existing activity in ConnectWise using JSON Patch operations.
+ *
+ * @param cwActivityId - The ConnectWise activity ID to update
+ * @param operations - Array of JSON Patch operations to apply
+ * @returns The updated CW activity object
+ * @throws GenericError if the update fails
+ */
+export const updateActivity = async (
+  cwActivityId: number,
+  operations: CWPatchOperation[],
+): Promise<CWActivity> => {
+  try {
+    return await activityCw.update(cwActivityId, operations);
+  } catch (error) {
+    const errBody = (error as any).response?.data || error;
+    console.error(`Error updating activity with ID ${cwActivityId}:`, errBody);
+    throw new GenericError({
+      name: "UpdateActivityError",
+      message: `Failed to update activity ${cwActivityId}`,
+      cause: typeof errBody === "string" ? errBody : JSON.stringify(errBody),
+      status: 502,
+    });
+  }
+};

src/modules/cw-utils/members/fetchAllMembers.ts

@@ -0,0 +1,67 @@
+import { Collection } from "@discordjs/collection";
+import { connectWiseApi } from "../../../constants";
+
+export interface CWMember {
+  id: number;
+  identifier: string;
+  firstName: string;
+  lastName: string;
+  officeEmail: string;
+  inactiveFlag: boolean;
+  _info: Record<string, string>;
+}
+
+/**
+ * Fetch All CW Members
+ *
+ * Fetches every member from ConnectWise using pagination and returns them
+ * in a Collection keyed by their identifier (e.g. "jroberts").
+ *
+ * @returns {Promise<Collection<string, CWMember>>} Collection of CW members keyed by identifier
+ */
+export const fetchAllCwMembers = async (): Promise<
+  Collection<string, CWMember>
+> => {
+  const members = new Collection<string, CWMember>();
+  const pageSize = 1000;
+
+  const { data: countData } = await connectWiseApi.get("/system/members/count");
+  const totalPages = Math.ceil(countData.count / pageSize);
+
+  for (let page = 0; page < totalPages; page++) {
+    const { data } = await connectWiseApi.get<CWMember[]>(
+      `/system/members?page=${page + 1}&pageSize=${pageSize}`,
+    );
+
+    for (const member of data) {
+      members.set(member.identifier, member);
+    }
+  }
+
+  return members;
+};
+
+/**
+ * Find CW Member Identifier by Email
+ *
+ * Looks up a ConnectWise member whose `officeEmail` matches the provided
+ * email address (case-insensitive) and returns their `identifier` string
+ * (e.g. "jroberts"). Returns `null` if no match is found.
+ *
+ * @param email - The email address to search for
+ * @param members - Optional pre-fetched member collection to search against (avoids extra API call)
+ * @returns {Promise<string | null>} The CW identifier or null
+ */
+export const findCwIdentifierByEmail = async (
+  email: string,
+  members?: Collection<string, CWMember>,
+): Promise<string | null> => {
+  const allMembers = members ?? (await fetchAllCwMembers());
+  const normalised = email.toLowerCase();
+
+  const match = allMembers.find(
+    (m) => m.officeEmail?.toLowerCase() === normalised,
+  );
+
+  return match?.identifier ?? null;
+};

src/modules/cw-utils/members/memberCache.ts

@@ -0,0 +1,104 @@
+import { Collection } from "@discordjs/collection";
+import { prisma } from "../../../constants";
+import { redis } from "../../../constants";
+import { CWMember } from "./fetchAllMembers";
+
+const REDIS_KEY = "cw:members";
+
+export interface ResolvedMember {
+  /** Local database user ID (null if no matching local user) */
+  id: string | null;
+  /** CW member identifier (e.g. "jroberts") */
+  identifier: string;
+  /** Full name resolved from CW member cache, or raw identifier as fallback */
+  name: string;
+  /** ConnectWise member ID */
+  cwMemberId: number | null;
+}
+
+/**
+ * CW Member Cache
+ *
+ * Dual-layer cache (in-memory + Redis) of ConnectWise members keyed by
+ * their identifier (e.g. "jroberts"). Populated by `refreshCwIdentifiers`
+ * on startup and every 30 minutes thereafter.
+ */
+let memberCache = new Collection<string, CWMember>();
+
+/**
+ * Set the member cache contents.
+ *
+ * Replaces both the in-memory Collection and the Redis snapshot.
+ *
+ * @param members - Collection of CW members keyed by identifier
+ */
+export const setMemberCache = async (members: Collection<string, CWMember>) => {
+  memberCache = members;
+  await redis.set(REDIS_KEY, JSON.stringify([...members.values()]));
+};
+
+/**
+ * Get the current member cache.
+ *
+ * Returns the in-memory Collection. If empty, attempts to hydrate from Redis
+ * first. Returns whatever is available (may be empty if Redis is also cold).
+ */
+export const getMemberCache = async (): Promise<
+  Collection<string, CWMember>
+> => {
+  if (memberCache.size > 0) return memberCache;
+
+  const stored = await redis.get(REDIS_KEY);
+  if (stored) {
+    const parsed: CWMember[] = JSON.parse(stored);
+    memberCache = new Collection(parsed.map((m) => [m.identifier, m]));
+  }
+
+  return memberCache;
+};
+
+/**
+ * Resolve CW Identifier to Full Name
+ *
+ * Looks up a ConnectWise member by their identifier in the in-memory cache
+ * and returns their full name. Falls back to the raw identifier if not found.
+ *
+ * @param identifier - The CW member identifier (e.g. "jroberts")
+ * @returns The member's full name (e.g. "John Roberts") or the raw identifier
+ */
+export const resolveMemberName = (identifier: string): string => {
+  const member = memberCache.get(identifier);
+  if (!member) return identifier;
+  return `${member.firstName} ${member.lastName}`.trim() || identifier;
+};
+
+/**
+ * Resolve CW Identifier to Full Member Info
+ *
+ * Looks up a ConnectWise member by their identifier in the in-memory cache
+ * and cross-references with the local database to return a complete member
+ * reference including local user ID, CW identifier, full name, and CW member ID.
+ *
+ * @param identifier - The CW member identifier (e.g. "jroberts")
+ * @returns {Promise<ResolvedMember>} Resolved member info
+ */
+export const resolveMember = async (
+  identifier: string,
+): Promise<ResolvedMember> => {
+  const cwMember = memberCache.get(identifier);
+  const name = cwMember
+    ? `${cwMember.firstName} ${cwMember.lastName}`.trim() || identifier
+    : identifier;
+
+  const localUser = await prisma.user.findFirst({
+    where: { cwIdentifier: identifier },
+    select: { id: true },
+  });
+
+  return {
+    id: localUser?.id ?? null,
+    identifier,
+    name,
+    cwMemberId: cwMember?.id ?? null,
+  };
+};

src/modules/cw-utils/members/refreshCwIdentifiers.ts

@@ -0,0 +1,46 @@
+import { connectWiseApi, prisma } from "../../../constants";
+import { events } from "../../globalEvents";
+import { fetchAllCwMembers, findCwIdentifierByEmail } from "./fetchAllMembers";
+import { setMemberCache } from "./memberCache";
+
+/**
+ * Refresh CW Identifiers
+ *
+ * Fetches all CW members and all users from the database, then updates
+ * each user's `cwIdentifier` field by matching their email to a CW member's
+ * `officeEmail`. Only users whose identifier has changed (or was previously
+ * null) are updated to avoid unnecessary writes.
+ *
+ * Also refreshes the in-memory member cache used for name resolution.
+ */
+export const refreshCwIdentifiers = async () => {
+  events.emit("cw:members:refresh:started");
+
+  const allMembers = await fetchAllCwMembers();
+  await setMemberCache(allMembers);
+  const allUsers = await prisma.user.findMany({
+    select: { id: true, email: true, cwIdentifier: true },
+  });
+
+  let updatedCount = 0;
+
+  await Promise.all(
+    allUsers.map(async (user) => {
+      const identifier = await findCwIdentifierByEmail(user.email, allMembers);
+
+      if (identifier !== user.cwIdentifier) {
+        await prisma.user.update({
+          where: { id: user.id },
+          data: { cwIdentifier: identifier },
+        });
+        updatedCount++;
+      }
+    }),
+  );
+
+  events.emit("cw:members:refresh:completed", {
+    totalMembers: allMembers.size,
+    totalUsers: allUsers.length,
+    usersUpdated: updatedCount,
+  });
+};

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

@@ -3,8 +3,12 @@ import { connectWiseApi } from "../../../constants";
 import {
   CWOpportunity,
   CWOpportunitySummary,
+  CWForecast,
   CWForecastItem,
+  CWForecastItemCreate,
   CWOpportunityNote,
+  CWOpportunityNoteCreate,
+  CWOpportunityNoteUpdate,
   CWOpportunityContact,
 } from "./opportunity.types";
 
@@ -106,17 +110,148 @@ export const opportunityCw = {
   },
 
   /**
-   * Fetch Opportunity Forecasts
+   * Fetch Opportunity Products
    *
-   * Fetches forecast/revenue items for a given opportunity.
+   * Fetches the full forecast object (products, revenue summaries, totals)
+   * for a given opportunity.
    */
-  fetchForecasts: async (opportunityId: number): Promise<CWForecastItem[]> => {
+  fetchProducts: async (opportunityId: number): Promise<CWForecast> => {
     const response = await connectWiseApi.get(
       `/sales/opportunities/${opportunityId}/forecast`,
     );
     return response.data;
   },
 
+  /**
+   * Create Forecast Items
+   *
+   * Adds one or more forecast items (products) to an opportunity using
+   * POST. The CW forecast endpoint expects a Forecast object with a
+   * `forecastItems` array — we wrap just the new items inside that
+   * structure so existing items are never sent or touched.
+   */
+  createProducts: async (
+    opportunityId: number,
+    data: CWForecastItemCreate | CWForecastItemCreate[],
+  ): Promise<CWForecastItem[]> => {
+    const items_to_add = Array.isArray(data) ? data : [data];
+    const url = `/sales/opportunities/${opportunityId}/forecast`;
+
+    // 1. Fetch existing forecast to derive defaults & diff IDs later
+    const existing = await opportunityCw.fetchProducts(opportunityId);
+    const existingIds = new Set(
+      (existing.forecastItems ?? []).map((fi) => fi.id),
+    );
+
+    // Derive sensible defaults from an existing item when available
+    const templateItem = (existing.forecastItems ?? [])[0];
+    const defaultStatus = templateItem?.status
+      ? { id: templateItem.status.id }
+      : { id: 1 };
+    const defaultForecastType = templateItem?.forecastType ?? "Product";
+
+    // 2. Build forecast items with required CW fields filled in
+    const forecastItems = items_to_add.map((newItem) => ({
+      opportunity: { id: opportunityId },
+      status: defaultStatus,
+      forecastType: defaultForecastType,
+      ...(newItem as Record<string, unknown>),
+    }));
+
+    // 3. POST a Forecast wrapper containing only the new items
+    const response = await connectWiseApi.post(url, { forecastItems });
+    const updatedForecast: CWForecast = response.data;
+
+    // 4. Find newly-created item(s) by diffing IDs
+    const newItems = (updatedForecast.forecastItems ?? []).filter(
+      (fi) => !existingIds.has(fi.id),
+    );
+
+    // Fall back to the last N items if ID diffing finds nothing
+    return newItems.length > 0
+      ? newItems
+      : (updatedForecast.forecastItems ?? []).slice(-items_to_add.length);
+  },
+
+  /**
+   * Update Forecast Item
+   *
+   * PATCHes a single forecast item on the parent `/forecast` endpoint.
+   * CW supports JSON Patch with paths like `/forecastItems/{index}/field`.
+   * This preserves item IDs (unlike PUT which always regenerates them)
+   * and does NOT recalculate revenue/cost from linked catalog items.
+   *
+   * NOTE: Not all fields are patchable — `sequenceNumber` and `quantity`
+   * are read-only on forecast items. Product ordering is managed locally
+   * via `OpportunityController.resequenceProducts()` and stored in the
+   * database `productSequence` field.
+   */
+  updateProduct: async (
+    opportunityId: number,
+    forecastItemId: number,
+    data: Record<string, unknown>,
+  ): Promise<CWForecastItem> => {
+    const forecast = await opportunityCw.fetchProducts(opportunityId);
+    const items = forecast.forecastItems ?? [];
+    const idx = items.findIndex((fi) => fi.id === forecastItemId);
+    if (idx === -1) {
+      throw new Error(
+        `Forecast item ${forecastItemId} not found on opportunity ${opportunityId}`,
+      );
+    }
+
+    const operations = Object.entries(data).map(([key, value]) => ({
+      op: "replace" as const,
+      path: `/forecastItems/${idx}/${key}`,
+      value,
+    }));
+
+    const url = `/sales/opportunities/${opportunityId}/forecast`;
+    const response = await connectWiseApi.patch(url, operations);
+    const updated: CWForecast = response.data;
+    return (updated.forecastItems ?? [])[idx]!;
+  },
+
+  /**
+   * Bulk-update Forecast Items
+   *
+   * PATCHes multiple forecast items in a single request via the parent
+   * `/forecast` endpoint. All patch operations are sent in one array.
+   */
+  bulkUpdateProducts: async (
+    opportunityId: number,
+    updates: Map<number, Record<string, unknown>>,
+  ): Promise<CWForecastItem[]> => {
+    const forecast = await opportunityCw.fetchProducts(opportunityId);
+    const items = forecast.forecastItems ?? [];
+
+    const operations: { op: "replace"; path: string; value: unknown }[] = [];
+    const touchedIndices: number[] = [];
+
+    for (const [itemId, changes] of updates) {
+      const idx = items.findIndex((fi) => fi.id === itemId);
+      if (idx === -1) {
+        throw new Error(
+          `Forecast item ${itemId} not found on opportunity ${opportunityId}`,
+        );
+      }
+      touchedIndices.push(idx);
+      for (const [key, value] of Object.entries(changes)) {
+        operations.push({
+          op: "replace",
+          path: `/forecastItems/${idx}/${key}`,
+          value,
+        });
+      }
+    }
+
+    const url = `/sales/opportunities/${opportunityId}/forecast`;
+    const response = await connectWiseApi.patch(url, operations);
+    const updated: CWForecast = response.data;
+
+    return touchedIndices.map((i) => (updated.forecastItems ?? [])[i]!);
+  },
+
   /**
    * Fetch Opportunity Notes
    *
@@ -129,6 +264,69 @@ export const opportunityCw = {
     return response.data;
   },
 
+  /**
+   * Fetch Single Note
+   *
+   * Fetches a single note by its ID on the given opportunity.
+   */
+  fetchNote: async (
+    opportunityId: number,
+    noteId: number,
+  ): Promise<CWOpportunityNote> => {
+    const response = await connectWiseApi.get(
+      `/sales/opportunities/${opportunityId}/notes/${noteId}`,
+    );
+    return response.data;
+  },
+
+  /**
+   * Create Note
+   *
+   * Creates a new note on the given opportunity.
+   */
+  createNote: async (
+    opportunityId: number,
+    data: CWOpportunityNoteCreate,
+  ): Promise<CWOpportunityNote> => {
+    const response = await connectWiseApi.post(
+      `/sales/opportunities/${opportunityId}/notes`,
+      data,
+    );
+    return response.data;
+  },
+
+  /**
+   * Update Note
+   *
+   * Updates an existing note on the given opportunity.
+   */
+  updateNote: async (
+    opportunityId: number,
+    noteId: number,
+    data: CWOpportunityNoteUpdate,
+  ): Promise<CWOpportunityNote> => {
+    const response = await connectWiseApi.patch(
+      `/sales/opportunities/${opportunityId}/notes/${noteId}`,
+      Object.entries(data).map(([key, value]) => ({
+        op: "replace",
+        path: key,
+        value,
+      })),
+    );
+    return response.data;
+  },
+
+  /**
+   * Delete Note
+   *
+   * Deletes a note from the given opportunity.
+   */
+  deleteNote: async (opportunityId: number, noteId: number): Promise<void> => {
+    await connectWiseApi.delete(
+      `/sales/opportunities/${opportunityId}/notes/${noteId}`,
+    );
+  },
+
   /**
    * Fetch Opportunity Contacts
    *
@@ -142,4 +340,20 @@ export const opportunityCw = {
     );
     return response.data;
   },
+
+  /**
+   * Fetch Procurement Products
+   *
+   * Fetches procurement product records linked to an opportunity.
+   * These contain cancellation data (cancelledFlag, cancelledReason, etc.)
+   * that the forecast endpoint does not provide.
+   */
+  fetchProcurementProducts: async (
+    opportunityId: number,
+  ): Promise<Record<string, unknown>[]> => {
+    const response = await connectWiseApi.get(
+      `/procurement/products?conditions=${encodeURIComponent(`opportunity/id=${opportunityId}`)}&fields=id,forecastDetailId,cancelledFlag,quantityCancelled,cancelledReason,cancelledBy,cancelledDate`,
+    );
+    return response.data;
+  },
 };

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

@@ -30,7 +30,7 @@ interface CWSiteReference {
   _info?: Record<string, string>;
 }
 
-interface CWCustomField {
+export interface CWCustomField {
   id: number;
   caption: string;
   type: string;
@@ -103,16 +103,72 @@ export interface CWOpportunityInfo {
 
 export interface CWForecastItem {
   id: number;
+  forecastDescription: string;
   opportunity: CWReference;
-  forecastType: string;
+  quantity: number;
-  forecastMonth: string;
+  status: CWReference;
+  catalogItem?: {
+    id: number;
+    identifier: string;
+    _info?: Record<string, string>;
+  };
+  productDescription: string;
+  productClass: string;
   revenue: number;
   cost: number;
-  forecastPercentage: number;
+  margin: number;
-  status: CWReference;
+  percentage: number;
-  includedFlag: boolean;
+  includeFlag: boolean;
-  linkedFlag: boolean;
+  quoteWerksQuantity: number;
+  forecastType: string;
+  linkFlag: boolean;
+  recurringRevenue: number;
+  recurringCost: number;
+  cycles: number;
   recurringFlag: boolean;
+  sequenceNumber: number;
+  subNumber: number;
+  taxableFlag: boolean;
+  _info?: Record<string, string>;
+}
+
+export interface CWForecastRevenueSummary {
+  id: number;
+  revenue: number;
+  cost: number;
+  margin: number;
+  percentage: number;
+  _info?: Record<string, string>;
+}
+
+export interface CWForecast {
+  id: number;
+  forecastItems: CWForecastItem[];
+  productRevenue: CWForecastRevenueSummary;
+  serviceRevenue: CWForecastRevenueSummary;
+  agreementRevenue: CWForecastRevenueSummary;
+  timeRevenue: CWForecastRevenueSummary;
+  expenseRevenue: CWForecastRevenueSummary;
+  forecastRevenueTotals: CWForecastRevenueSummary;
+  inclusiveRevenueTotals: CWForecastRevenueSummary;
+  recurringTotal: number;
+  wonRevenue: CWForecastRevenueSummary;
+  lostRevenue: CWForecastRevenueSummary;
+  openRevenue: CWForecastRevenueSummary;
+  otherRevenue1: CWForecastRevenueSummary;
+  otherRevenue2: CWForecastRevenueSummary;
+  salesTaxRevenue: number;
+  forecastTotalWithTaxes: number;
+  expectedProbability: number;
+  taxCode: CWReference;
+  billingTerms: CWReference;
+  currency: {
+    id: number;
+    symbol: string;
+    currencyCode: string;
+    name: string;
+    _info?: Record<string, string>;
+  };
   _info?: Record<string, string>;
 }
 
@@ -127,6 +183,18 @@ export interface CWOpportunityNote {
   _info?: Record<string, string>;
 }
 
+export interface CWOpportunityNoteCreate {
+  text: string;
+  type?: { id: number };
+  flagged?: boolean;
+}
+
+export interface CWOpportunityNoteUpdate {
+  text?: string;
+  type?: { id: number };
+  flagged?: boolean;
+}
+
 export interface CWOpportunityContact {
   id: number;
   opportunity: CWReference;
@@ -138,6 +206,26 @@ export interface CWOpportunityContact {
   _info?: Record<string, string>;
 }
 
+export interface CWForecastItemCreate {
+  catalogItem?: { id: number };
+  forecastDescription?: string;
+  productDescription?: string;
+  quantity?: number;
+  status?: { id: number };
+  productClass?: string;
+  forecastType?: string;
+  revenue?: number;
+  cost?: number;
+  includeFlag?: boolean;
+  linkFlag?: boolean;
+  recurringFlag?: boolean;
+  taxableFlag?: boolean;
+  recurringRevenue?: number;
+  recurringCost?: number;
+  cycles?: number;
+  sequenceNumber?: number;
+}
+
 export interface CWOpportunitySummary {
   id: number;
   _info?: Record<string, string>;

src/modules/cw-utils/procurement/refreshCatalog.ts

@@ -96,6 +96,10 @@ export const refreshCatalog = async () => {
             description: item.description,
             customerDescription: item.customerDescription,
             internalNotes: item.notes,
+            category: item.category?.name,
+            categoryCwId: item.category?.id,
+            subcategory: item.subcategory?.name,
+            subcategoryCwId: item.subcategory?.id,
             manufacturer: item.manufacturer?.name,
             manufactureCwId: item.manufacturer?.id,
             partNumber: item.manufacturerPartNumber,
@@ -115,6 +119,10 @@ export const refreshCatalog = async () => {
             description: item.description,
             customerDescription: item.customerDescription,
             internalNotes: item.notes,
+            category: item.category?.name,
+            categoryCwId: item.category?.id,
+            subcategory: item.subcategory?.name,
+            subcategoryCwId: item.subcategory?.id,
             manufacturer: item.manufacturer?.name,
             manufactureCwId: item.manufacturer?.id,
             partNumber: item.manufacturerPartNumber,

src/modules/cw-utils/sites/companySites.ts

@@ -0,0 +1,79 @@
+import { connectWiseApi } from "../../../constants";
+
+export interface CWCompanySite {
+  id: number;
+  name: string;
+  addressLine1: string;
+  addressLine2?: string;
+  city: string;
+  stateReference: { id: number; identifier: string; name: string } | null;
+  zip: string;
+  country: { id: number; name: string } | null;
+  phoneNumber: string;
+  faxNumber: string;
+  taxCodeId: number | null;
+  expenseReimbursement: number;
+  primaryAddressFlag: boolean;
+  defaultShippingFlag: boolean;
+  defaultBillingFlag: boolean;
+  defaultMailingFlag: boolean;
+  mobileGuid: string;
+  calendar: { id: number; name: string } | null;
+  timeZone: { id: number; name: string } | null;
+  company: { id: number; identifier: string; name: string };
+  _info: Record<string, string>;
+}
+
+/**
+ * Fetch all sites for a ConnectWise company.
+ *
+ * @param cwCompanyId - The ConnectWise company ID
+ * @returns Array of CW company sites
+ */
+export const fetchCompanySites = async (
+  cwCompanyId: number,
+): Promise<CWCompanySite[]> => {
+  const response = await connectWiseApi.get(
+    `/company/companies/${cwCompanyId}/sites?pageSize=1000`,
+  );
+  return response.data;
+};
+
+/**
+ * Fetch a single site by CW site ID for a given company.
+ *
+ * @param cwCompanyId - The ConnectWise company ID
+ * @param cwSiteId    - The ConnectWise site ID
+ * @returns The CW company site
+ */
+export const fetchCompanySite = async (
+  cwCompanyId: number,
+  cwSiteId: number,
+): Promise<CWCompanySite> => {
+  const response = await connectWiseApi.get(
+    `/company/companies/${cwCompanyId}/sites/${cwSiteId}`,
+  );
+  return response.data;
+};
+
+/**
+ * Serialize a CW site into a clean API-friendly object.
+ */
+export const serializeCwSite = (site: CWCompanySite) => ({
+  id: site.id,
+  name: site.name,
+  address: {
+    line1: site.addressLine1,
+    line2: site.addressLine2 ?? null,
+    city: site.city,
+    state: site.stateReference?.name ?? null,
+    zip: site.zip,
+    country: site.country?.name ?? "United States",
+  },
+  phoneNumber: site.phoneNumber || null,
+  faxNumber: site.faxNumber || null,
+  primaryAddressFlag: site.primaryAddressFlag,
+  defaultShippingFlag: site.defaultShippingFlag,
+  defaultBillingFlag: site.defaultBillingFlag,
+  defaultMailingFlag: site.defaultMailingFlag,
+});

src/modules/cw-utils/userDefinedFields/index.ts

@@ -0,0 +1,6 @@
+export { userDefinedFieldsCw } from "./userDefinedFields";
+export type {
+  CWUserDefinedField,
+  CWUserDefinedFieldOption,
+  CWUserDefinedFieldInfo,
+} from "./udf.types";

src/modules/cw-utils/userDefinedFields/udf.types.ts

@@ -0,0 +1,34 @@
+export interface CWUserDefinedFieldOption {
+  id: number;
+  optionValue: string;
+  defaultFlag: boolean;
+  inactiveFlag: boolean;
+  sortOrder: number;
+}
+
+export interface CWUserDefinedFieldInfo {
+  lastUpdated: string;
+  updatedBy: string;
+}
+
+export interface CWUserDefinedField {
+  id: number;
+  podId: number;
+  caption: string;
+  sequenceNumber: number;
+  screenId: string;
+  helpText?: string;
+  fieldTypeIdentifier: string;
+  numberDecimals: number;
+  entryTypeIdentifier: string;
+  requiredFlag: boolean;
+  displayOnScreenFlag: boolean;
+  readOnlyFlag: boolean;
+  listViewFlag: boolean;
+  options?: CWUserDefinedFieldOption[];
+  businessUnitIds: number[];
+  locationIds: number[];
+  connectWiseID: string;
+  dateCreated: string;
+  _info: CWUserDefinedFieldInfo;
+}

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

@@ -0,0 +1,119 @@
+import { Collection } from "@discordjs/collection";
+import { connectWiseApi, redis } from "../../../constants";
+import { events } from "../../globalEvents";
+import { CWUserDefinedField } from "./udf.types";
+
+const REDIS_KEY = "cw:userDefinedFields";
+
+/** In-memory cache of all CW User Defined Fields, keyed by UDF id */
+let cache: Collection<number, CWUserDefinedField> = new Collection();
+
+export const userDefinedFieldsCw = {
+  /**
+   * Get Cache
+   *
+   * Returns the current in-memory Collection of all User Defined Fields.
+   * If the cache is empty, it will attempt to hydrate from Redis first,
+   * then fall back to a live API fetch.
+   */
+  get: async (): Promise<Collection<number, CWUserDefinedField>> => {
+    if (cache.size > 0) return cache;
+
+    // Try hydrating from Redis
+    const stored = await redis.get(REDIS_KEY);
+    if (stored) {
+      const parsed: CWUserDefinedField[] = JSON.parse(stored);
+      cache = new Collection(parsed.map((udf) => [udf.id, udf]));
+      return cache;
+    }
+
+    // Nothing cached anywhere — do a live fetch
+    return userDefinedFieldsCw.refresh();
+  },
+
+  /**
+   * Fetch All User Defined Fields
+   *
+   * Fetches all UDFs from the ConnectWise API.
+   * Does NOT update the cache — use `refresh()` for that.
+   */
+  fetchAll: async (): Promise<Collection<number, CWUserDefinedField>> => {
+    const allItems = new Collection<number, CWUserDefinedField>();
+    const pageSize = 1000;
+
+    const response = await connectWiseApi.get(
+      `/system/userDefinedFields?pageSize=${pageSize}`,
+    );
+    const items: CWUserDefinedField[] = response.data;
+
+    for (const item of items) {
+      allItems.set(item.id, item);
+    }
+
+    return allItems;
+  },
+
+  /**
+   * Refresh
+   *
+   * Fetches all UDFs from ConnectWise, replaces the in-memory cache
+   * and persists the snapshot to Redis.
+   */
+  refresh: async (): Promise<Collection<number, CWUserDefinedField>> => {
+    events.emit("cw:udf:refresh:started");
+
+    const allItems = await userDefinedFieldsCw.fetchAll();
+    cache = allItems;
+
+    // Persist to Redis
+    await redis.set(REDIS_KEY, JSON.stringify([...allItems.values()]));
+
+    events.emit("cw:udf:refresh:completed", { count: allItems.size });
+    return cache;
+  },
+
+  /**
+   * Find by ID
+   *
+   * Returns a single UDF by its ConnectWise ID from the cache.
+   */
+  findById: async (id: number): Promise<CWUserDefinedField | undefined> => {
+    const items = await userDefinedFieldsCw.get();
+    return items.get(id);
+  },
+
+  /**
+   * Find by Caption
+   *
+   * Returns the first UDF matching the given caption (case-insensitive).
+   */
+  findByCaption: async (
+    caption: string,
+  ): Promise<CWUserDefinedField | undefined> => {
+    const items = await userDefinedFieldsCw.get();
+    const lowerCaption = caption.toLowerCase();
+    return items.find((udf) => udf.caption.toLowerCase() === lowerCaption);
+  },
+
+  /**
+   * Find by Screen ID
+   *
+   * Returns all UDFs associated with a given screenId.
+   */
+  findByScreenId: async (
+    screenId: string,
+  ): Promise<Collection<number, CWUserDefinedField>> => {
+    const items = await userDefinedFieldsCw.get();
+    return items.filter((udf) => udf.screenId === screenId);
+  },
+
+  /**
+   * Invalidate
+   *
+   * Clears the in-memory cache and removes the Redis key.
+   */
+  invalidate: async (): Promise<void> => {
+    cache = new Collection();
+    await redis.del(REDIS_KEY);
+  },
+};

src/modules/globalEvents.ts

@@ -177,6 +177,30 @@ interface EventTypes {
     totalDb: number;
     staleCount: number;
   }) => void;
+
+  // Cache Events
+  "cache:opportunities:refresh:started": (data: {
+    totalOpportunities: number;
+  }) => void;
+  "cache:opportunities:refresh:completed": (data: {
+    totalOpportunities: number;
+    activitiesRefreshed: number;
+    companiesRefreshed: number;
+    skipped: number;
+  }) => void;
+  "cache:opportunities:refresh:error": (data: { error: unknown }) => void;
+
+  // ConnectWise User Defined Fields Events
+  "cw:udf:refresh:started": () => void;
+  "cw:udf:refresh:completed": (data: { count: number }) => void;
+
+  // ConnectWise Members Events
+  "cw:members:refresh:started": () => void;
+  "cw:members:refresh:completed": (data: {
+    totalMembers: number;
+    totalUsers: number;
+    usersUpdated: number;
+  }) => void;
 }
 
 export const events = new Eventra<EventTypes>();

src/types/PermissionNodes.ts

@@ -31,6 +31,8 @@ export interface PermissionCategory {
   description: string;
   /** Permission nodes in this category */
   permissions: PermissionNode[];
+  /** Optional nested sub-categories for hierarchical grouping */
+  subCategories?: Record<string, PermissionCategory>;
 }
 
 export const PERMISSION_NODES = {
@@ -353,10 +355,13 @@ export const PERMISSION_NODES = {
       },
       {
         node: "procurement.catalog.fetch.many",
-        description: "Fetch multiple catalog items or count",
+        description:
+          "Fetch multiple catalog items, count, categories/ecosystems, or filter values",
         usedIn: [
           "src/api/procurement/fetchAll.ts",
           "src/api/procurement/count.ts",
+          "src/api/procurement/categories.ts",
+          "src/api/procurement/filters.ts",
         ],
       },
       {
@@ -385,18 +390,24 @@ export const PERMISSION_NODES = {
       {
         node: "sales.opportunity.fetch",
         description:
-          "Fetch a single opportunity and its sub-resources (forecasts, notes, contacts)",
+          "Fetch a single opportunity and its sub-resources (products, notes, contacts)",
         usedIn: [
           "src/api/sales/[id]/fetch.ts",
-          "src/api/sales/[id]/forecasts.ts",
+          "src/api/sales/[id]/products.ts",
           "src/api/sales/[id]/notes.ts",
+          "src/api/sales/[id]/fetchNote.ts",
           "src/api/sales/[id]/contacts.ts",
         ],
       },
       {
         node: "sales.opportunity.fetch.many",
-        description: "Fetch multiple opportunities or count",
+        description:
-        usedIn: ["src/api/sales/fetchAll.ts", "src/api/sales/count.ts"],
+          "Fetch multiple opportunities, count, or opportunity types",
+        usedIn: [
+          "src/api/sales/fetchAll.ts",
+          "src/api/sales/count.ts",
+          "src/api/sales/fetchOpportunityTypes.ts",
+        ],
       },
       {
         node: "sales.opportunity.refresh",
@@ -404,6 +415,57 @@ export const PERMISSION_NODES = {
         usedIn: ["src/api/sales/[id]/refresh.ts"],
         dependencies: ["sales.opportunity.fetch"],
       },
+      {
+        node: "sales.opportunity.note.create",
+        description: "Create a new note on an opportunity",
+        usedIn: ["src/api/sales/[id]/createNote.ts"],
+        dependencies: ["sales.opportunity.fetch"],
+      },
+      {
+        node: "sales.opportunity.note.update",
+        description: "Update an existing note on an opportunity",
+        usedIn: ["src/api/sales/[id]/updateNote.ts"],
+        dependencies: ["sales.opportunity.fetch"],
+      },
+      {
+        node: "sales.opportunity.note.delete",
+        description: "Delete a note from an opportunity",
+        usedIn: ["src/api/sales/[id]/deleteNote.ts"],
+        dependencies: ["sales.opportunity.fetch"],
+      },
+      {
+        node: "sales.opportunity.product.update",
+        description:
+          "Update products (forecast items) on an opportunity, including resequencing",
+        usedIn: ["src/api/sales/[id]/resequenceProducts.ts"],
+        dependencies: ["sales.opportunity.fetch"],
+      },
+      {
+        node: "sales.opportunity.product.add",
+        description:
+          "Add a new product (forecast item) to an opportunity. Individual fields are gated by sales.opportunity.product.field.<field> permissions.",
+        usedIn: ["src/api/sales/[id]/addProduct.ts"],
+        dependencies: ["sales.opportunity.fetch"],
+        fieldLevelPermissions: [
+          "sales.opportunity.product.field.catalogItem",
+          "sales.opportunity.product.field.forecastDescription",
+          "sales.opportunity.product.field.productDescription",
+          "sales.opportunity.product.field.quantity",
+          "sales.opportunity.product.field.status",
+          "sales.opportunity.product.field.productClass",
+          "sales.opportunity.product.field.forecastType",
+          "sales.opportunity.product.field.revenue",
+          "sales.opportunity.product.field.cost",
+          "sales.opportunity.product.field.includeFlag",
+          "sales.opportunity.product.field.linkFlag",
+          "sales.opportunity.product.field.recurringFlag",
+          "sales.opportunity.product.field.taxableFlag",
+          "sales.opportunity.product.field.recurringRevenue",
+          "sales.opportunity.product.field.recurringCost",
+          "sales.opportunity.product.field.cycles",
+          "sales.opportunity.product.field.sequenceNumber",
+        ],
+      },
     ],
   },
 
@@ -642,14 +704,307 @@ export const PERMISSION_NODES = {
       },
     ],
   },
+  objectTypes: {
+    name: "Object Types",
+    description:
+      "Field-level read permissions that control which keys are visible on API response objects. Each sub-category corresponds to a domain object type. Use <scope>.* to grant access to all fields.",
+    permissions: [],
+    subCategories: {
+      company: {
+        name: "Company",
+        description:
+          "Field-level read permissions for Company response objects",
+        permissions: [
+          {
+            node: "obj.company",
+            description:
+              "Field-level gate for Company objects. Each key on the response is checked as obj.company.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/companies/[id]/fetch.ts",
+              "src/api/companies/fetchAll.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.company.id",
+              "obj.company.name",
+              "obj.company.cw_Identifier",
+              "obj.company.cw_CompanyId",
+              "obj.company.cw_Data",
+              "obj.company.createdAt",
+              "obj.company.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      credential: {
+        name: "Credential",
+        description:
+          "Field-level read permissions for Credential response objects",
+        permissions: [
+          {
+            node: "obj.credential",
+            description:
+              "Field-level gate for Credential objects. Each key on the response is checked as obj.credential.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/credentials/fetch.ts",
+              "src/api/credentials/fetchByCompany.ts",
+              "src/api/credentials/fetchSubCredentials.ts",
+              "src/api/credential-types/fetchCredentials.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.credential.id",
+              "obj.credential.name",
+              "obj.credential.notes",
+              "obj.credential.typeId",
+              "obj.credential.companyId",
+              "obj.credential.subCredentialOfId",
+              "obj.credential.fields",
+              "obj.credential.type",
+              "obj.credential.company",
+              "obj.credential.subCredentials",
+              "obj.credential.secureFieldIds",
+              "obj.credential.createdAt",
+              "obj.credential.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      credentialType: {
+        name: "Credential Type",
+        description:
+          "Field-level read permissions for Credential Type response objects",
+        permissions: [
+          {
+            node: "obj.credentialType",
+            description:
+              "Field-level gate for Credential Type objects. Each key on the response is checked as obj.credentialType.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/credential-types/fetch.ts",
+              "src/api/credential-types/fetchAll.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.credentialType.id",
+              "obj.credentialType.name",
+              "obj.credentialType.permissionScope",
+              "obj.credentialType.icon",
+              "obj.credentialType.fields",
+              "obj.credentialType.credentialCount",
+              "obj.credentialType.createdAt",
+              "obj.credentialType.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      user: {
+        name: "User",
+        description: "Field-level read permissions for User response objects",
+        permissions: [
+          {
+            node: "obj.user",
+            description:
+              "Field-level gate for User objects. Each key on the response is checked as obj.user.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/user/@me/fetch.ts",
+              "src/api/user/fetch.ts",
+              "src/api/user/fetchAll.ts",
+              "src/api/roles/getUsers.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.user.id",
+              "obj.user.name",
+              "obj.user.roles",
+              "obj.user.permissions",
+              "obj.user.login",
+              "obj.user.email",
+              "obj.user.image",
+              "obj.user.createdAt",
+              "obj.user.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      role: {
+        name: "Role",
+        description: "Field-level read permissions for Role response objects",
+        permissions: [
+          {
+            node: "obj.role",
+            description:
+              "Field-level gate for Role objects. Each key on the response is checked as obj.role.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/roles/fetch.ts",
+              "src/api/roles/fetchAll.ts",
+              "src/api/user/fetchRoles.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.role.id",
+              "obj.role.title",
+              "obj.role.moniker",
+              "obj.role.permissions",
+              "obj.role.users",
+              "obj.role.createdAt",
+              "obj.role.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      catalogItem: {
+        name: "Catalog Item",
+        description:
+          "Field-level read permissions for Catalog Item (procurement) response objects",
+        permissions: [
+          {
+            node: "obj.catalogItem",
+            description:
+              "Field-level gate for Catalog Item objects. Each key on the response is checked as obj.catalogItem.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/procurement/fetchAll.ts",
+              "src/api/procurement/[id]/fetch.ts",
+              "src/api/procurement/[id]/fetchLinked.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.catalogItem.id",
+              "obj.catalogItem.cwCatalogId",
+              "obj.catalogItem.identifier",
+              "obj.catalogItem.name",
+              "obj.catalogItem.description",
+              "obj.catalogItem.customerDescription",
+              "obj.catalogItem.internalNotes",
+              "obj.catalogItem.manufacturer",
+              "obj.catalogItem.manufactureCwId",
+              "obj.catalogItem.partNumber",
+              "obj.catalogItem.vendorName",
+              "obj.catalogItem.vendorSku",
+              "obj.catalogItem.vendorCwId",
+              "obj.catalogItem.price",
+              "obj.catalogItem.cost",
+              "obj.catalogItem.inactive",
+              "obj.catalogItem.salesTaxable",
+              "obj.catalogItem.onHand",
+              "obj.catalogItem.cwLastUpdated",
+              "obj.catalogItem.linkedItems",
+              "obj.catalogItem.createdAt",
+              "obj.catalogItem.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      opportunity: {
+        name: "Opportunity",
+        description:
+          "Field-level read permissions for Opportunity (sales) response objects",
+        permissions: [
+          {
+            node: "obj.opportunity",
+            description:
+              "Field-level gate for Opportunity objects. Each key on the response is checked as obj.opportunity.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/sales/fetchAll.ts",
+              "src/api/sales/[id]/fetch.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.opportunity.id",
+              "obj.opportunity.cwOpportunityId",
+              "obj.opportunity.name",
+              "obj.opportunity.notes",
+              "obj.opportunity.type",
+              "obj.opportunity.stage",
+              "obj.opportunity.status",
+              "obj.opportunity.priority",
+              "obj.opportunity.rating",
+              "obj.opportunity.source",
+              "obj.opportunity.campaign",
+              "obj.opportunity.primarySalesRep",
+              "obj.opportunity.secondarySalesRep",
+              "obj.opportunity.company",
+              "obj.opportunity.contact",
+              "obj.opportunity.site",
+              "obj.opportunity.customerPO",
+              "obj.opportunity.totalSalesTax",
+              "obj.opportunity.location",
+              "obj.opportunity.department",
+              "obj.opportunity.expectedCloseDate",
+              "obj.opportunity.pipelineChangeDate",
+              "obj.opportunity.dateBecameLead",
+              "obj.opportunity.closedDate",
+              "obj.opportunity.closedFlag",
+              "obj.opportunity.closedBy",
+              "obj.opportunity.companyId",
+              "obj.opportunity.cwLastUpdated",
+              "obj.opportunity.createdAt",
+              "obj.opportunity.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      unifiSite: {
+        name: "UniFi Site",
+        description:
+          "Field-level read permissions for UniFi Site response objects",
+        permissions: [
+          {
+            node: "obj.unifiSite",
+            description:
+              "Field-level gate for UniFi Site objects. Each key on the response is checked as obj.unifiSite.<field>. Only fields the user has permission for are included.",
+            usedIn: [
+              "src/api/unifi/sites/fetchAll.ts",
+              "src/api/unifi/site/fetch.ts",
+              "src/api/companies/[id]/unifiSites.ts",
+            ],
+            fieldLevelPermissions: [
+              "obj.unifiSite.id",
+              "obj.unifiSite.name",
+              "obj.unifiSite.siteId",
+              "obj.unifiSite.companyId",
+              "obj.unifiSite.company",
+              "obj.unifiSite.createdAt",
+              "obj.unifiSite.updatedAt",
+            ],
+          },
+        ],
+      },
+
+      wifiNetwork: {
+        name: "WiFi Network",
+        description:
+          "Field-level read permissions for UniFi WiFi Network (WLAN) response objects. See the unifi category for the full field-level permission list under unifi.site.wifi.read.",
+        permissions: [
+          {
+            node: "unifi.site.wifi.read",
+            description:
+              "Field-level gate for WiFi network response data (defined in the unifi category). Each key on the WlanConf object is checked as unifi.site.wifi.read.<field>.",
+            usedIn: ["src/api/unifi/site/wifi/fetchAll.ts"],
+            dependencies: ["unifi.access", "unifi.site.wifi"],
+          },
+        ],
+      },
+    },
+  },
 } as const satisfies Record<string, PermissionCategory>;
 
+/**
+ * Recursively collects permission nodes from a category and its sub-categories.
+ */
+function collectPermissions(category: PermissionCategory): PermissionNode[] {
+  const direct = category.permissions as PermissionNode[];
+  const nested = category.subCategories
+    ? Object.values(category.subCategories).flatMap(collectPermissions)
+    : [];
+  return [...direct, ...nested];
+}
+
 /**
  * Utility function to get all permission nodes flattened into a single array
  */
 export function getAllPermissionNodes(): PermissionNode[] {
-  return Object.values(PERMISSION_NODES).flatMap(
+  return Object.values(PERMISSION_NODES).flatMap((category) =>
-    (category) => category.permissions as PermissionNode[],
+    collectPermissions(category),
   );
 }
 

src/types/QuoteStatuses.ts

@@ -0,0 +1,199 @@
+export interface QuoteStatus {
+  id: number;
+  name: string;
+  wonFlag: boolean;
+  lostFlag: boolean;
+  closedFlag: boolean;
+  inactiveFlag: boolean;
+  defaultFlag: boolean;
+  enteredBy: string;
+  dateEntered: string;
+  _info: {
+    lastUpdated: string;
+    updatedBy: string;
+  };
+  connectWiseId: string;
+  optimaEquivalency: number[];
+}
+
+export const QUOTE_STATUSES: QuoteStatus[] = [
+  //
+  // FUTURE
+  //
+  {
+    id: 51,
+    name: "FutureLead",
+    wonFlag: false,
+    lostFlag: false,
+    closedFlag: false,
+    inactiveFlag: false,
+    defaultFlag: false,
+    enteredBy: "crobinso",
+    dateEntered: "2023-07-11T23:13:19Z",
+    _info: {
+      lastUpdated: "2024-04-28T15:03:57Z",
+      updatedBy: "crobinso",
+    },
+    connectWiseId: "070f72a3-70d0-ef11-b2e0-000c29c55070",
+    optimaEquivalency: [
+      35, // Z9. Later
+      36, // Z0.  TT Identified Need
+    ],
+  },
+
+  //
+  // NEW
+  //
+  {
+    id: 24,
+    name: "New",
+    wonFlag: false,
+    lostFlag: false,
+    closedFlag: false,
+    inactiveFlag: false,
+    defaultFlag: true,
+    enteredBy: "CRobinso",
+    dateEntered: "2021-01-03T15:06:59Z",
+    _info: {
+      lastUpdated: "2024-04-28T15:04:43Z",
+      updatedBy: "crobinso",
+    },
+    connectWiseId: "ec0e72a3-70d0-ef11-b2e0-000c29c55070",
+    optimaEquivalency: [
+      1, // Pre2021-1) New
+      13, // Pre2021-Initial Contact Made
+      37, // 00. Pending New
+    ],
+  },
+
+  //
+  // INTERNAL REVIEW
+  //
+  {
+    id: 56,
+    name: "Internal Review",
+    wonFlag: false,
+    lostFlag: false,
+    closedFlag: false,
+    inactiveFlag: false,
+    defaultFlag: false,
+    enteredBy: "crobinso",
+    dateEntered: "2024-04-28T15:05:09Z",
+    _info: {
+      lastUpdated: "2024-04-28T15:05:09Z",
+      updatedBy: "crobinso",
+    },
+    connectWiseId: "0c0f72a3-70d0-ef11-b2e0-000c29c55070",
+    optimaEquivalency: [
+      10, // Pre2021-Order Approved
+      26, // Z3.  ConfirmedQuote
+      27, // Z4.  Waiting-VendorInfo
+      28, // Z5.  Waiting-OtherTTStaff
+      41, // PRE2405. Review Ready
+      54, // PRE24_90.  Customer Approved
+    ],
+  },
+
+  //
+  // ACTIVE
+  //
+  {
+    id: 58,
+    name: "Active",
+    wonFlag: false,
+    lostFlag: false,
+    closedFlag: false,
+    inactiveFlag: false,
+    defaultFlag: false,
+    enteredBy: "crobinso",
+    dateEntered: "2024-04-28T15:07:17Z",
+    _info: {
+      lastUpdated: "2024-04-28T15:07:17Z",
+      updatedBy: "crobinso",
+    },
+    connectWiseId: "0e0f72a3-70d0-ef11-b2e0-000c29c55070",
+    optimaEquivalency: [
+      9, // Pre2021-Recommendation
+      15, // Pre2021-3) Onsite Assess Sch'd
+      16, // Pre2021-4) Quote Info Gathered
+      17, // Pre2021-5) Quote Sent
+      18, // Pre2021-6) Follow-up #1 Made
+      19, // Pre2021-7) Follow-up #2 Made
+      20, // Pre2021-8) Follow-up #3 Made
+
+      25, // ZOLD---Quote Sent
+      43, // 03. Quote Sent
+
+      38, // PRE2402. On-Site Ready
+      39, // PRE2403. On-Site Scheduled
+      40, // PRE2404. On-Site Complete
+      42, // PRE2407. Reviewed
+      44, // PRE2409.  Follow-Up 1
+      45, // PRE2410. Changes Needed
+      46, // PRE2411. Follow-Up 2
+      47, // PRE2412. Follow-Up3
+      48, // PRE2413. Follow-Up Extended
+      52, // PRE2489.  Overdue
+      55, // PRE24_70. Quote Sent - Sell
+      57, // 04. Confirmed Quote
+    ],
+  },
+
+  //
+  // WON
+  //
+  {
+    id: 29,
+    name: "Won",
+    wonFlag: true,
+    lostFlag: false,
+    closedFlag: true,
+    inactiveFlag: false,
+    defaultFlag: false,
+    enteredBy: "CRobinso",
+    dateEntered: "2021-01-03T15:07:44Z",
+    _info: {
+      lastUpdated: "2024-01-21T20:39:41Z",
+      updatedBy: "crobinso",
+    },
+    connectWiseId: "f10e72a3-70d0-ef11-b2e0-000c29c55070",
+    optimaEquivalency: [
+      2, // Pre2021-8) Won
+      54, // PRE24_90.  Customer Approved (if you treat as effectively Won)
+      49, // 91. Pending Won
+    ],
+  },
+
+  //
+  // LOST
+  //
+  {
+    id: 53,
+    name: "Lost",
+    wonFlag: false,
+    lostFlag: true,
+    closedFlag: true,
+    inactiveFlag: false,
+    defaultFlag: false,
+    enteredBy: "crobinso",
+    dateEntered: "2024-01-20T20:51:35Z",
+    _info: {
+      lastUpdated: "2024-01-20T20:51:41Z",
+      updatedBy: "crobinso",
+    },
+    connectWiseId: "090f72a3-70d0-ef11-b2e0-000c29c55070",
+    optimaEquivalency: [
+      3, // Pre2021-9) Lost
+      4, // Pre2021-No Decision
+      12, // Pre2021-OLD
+
+      30, // Pre2024_99.  Lost-Competitor
+      31, // Pre2024_99.  Lost-DIY
+      32, // Pre2024_99.  Lost-NoDecision
+      33, // Pre2024_99.  Lost-Pricing
+      34, // Pre2024_99.  Lost-OtherTTQuote
+
+      50, // 98. Pending Lost
+    ],
+  },
+];

test-forecast-resequence.ts

@@ -0,0 +1,442 @@
+/**
+ * Test Script: Forecast Item Resequencing & Procurement Linkage
+ *
+ * Validates the CW forecast API behaviour discovered via probing:
+ *   - `sequenceNumber` is read-only — display order = array position
+ *   - PUT always regenerates all forecast item IDs
+ *   - Revenue & cost are preserved through PUT
+ *   - PATCH on /forecast with `/forecastItems/{idx}/field` paths works
+ *     for some fields (e.g. forecastDescription) and preserves IDs
+ *
+ * Test flow:
+ *   1. Create opportunity under XYZ Test Company
+ *   2. Add 4 products via POST
+ *   3. Create procurement products (linked by forecastDetailId)
+ *   4. Cancel one procurement product
+ *   5. Reorder forecast items via PUT (reverse order)
+ *   6. Remap procurement forecastDetailId to new IDs
+ *   7. Verify: order correct, prices preserved, cancellation data intact
+ *   8. Clean up
+ *
+ * Usage:  bun run test-forecast-resequence.ts
+ */
+import axios from "axios";
+
+const cw = axios.create({
+  baseURL: "https://ttscw.totaltech.net/v4_6_release/apis/3.0/",
+  headers: {
+    Authorization: `Basic ${process.env.CW_BASIC_TOKEN}`,
+    clientId: `${process.env.CW_CLIENT_ID}`,
+    "Content-Type": "application/json",
+  },
+});
+
+const log = (label: string, ...args: unknown[]) =>
+  console.log(`\n[${label}]`, ...args);
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+  // ── 1. Find company ─────────────────────────────────────────────────────
+  log("SETUP", "Finding XYZ Test Company...");
+  const compRes = await cw.get(
+    `/company/companies?conditions=${encodeURIComponent("name like 'XYZ Test%'")}&fields=id,identifier,name`,
+  );
+  if (compRes.data.length === 0) {
+    console.error("ERROR: 'XYZ Test Company' not found.");
+    process.exit(1);
+  }
+  const company = compRes.data[0];
+  log("SETUP", `Company: ${company.name} (id=${company.id})`);
+
+  // ── 2. Create opportunity ───────────────────────────────────────────────
+  log("SETUP", "Creating test opportunity...");
+  const oppRes = await cw.post("/sales/opportunities", {
+    name: `[TEST] Resequence – ${new Date().toISOString().slice(0, 16)}`,
+    company: { id: company.id },
+    contact: { id: 1 },
+    primarySalesRep: { id: 153 },
+    expectedCloseDate: new Date(Date.now() + 30 * 86_400_000)
+      .toISOString()
+      .replace(/\.\d{3}Z$/, "Z"),
+  });
+  const oppId = oppRes.data.id;
+  log("SETUP", `Created opportunity id=${oppId}`);
+
+  const forecastUrl = `/sales/opportunities/${oppId}/forecast`;
+
+  // Track IDs for cleanup
+  const procIdsToClean: number[] = [];
+
+  try {
+    // ── 3. Add 4 products ───────────────────────────────────────────────────
+    log("PRODUCTS", "Adding 4 products...");
+    const postRes = await cw.post(forecastUrl, {
+      forecastItems: [
+        {
+          opportunity: { id: oppId },
+          status: { id: 1 },
+          forecastDescription: "Alpha",
+          revenue: 100,
+          cost: 50,
+          forecastType: "Product",
+        },
+        {
+          opportunity: { id: oppId },
+          status: { id: 1 },
+          forecastDescription: "Bravo",
+          revenue: 250,
+          cost: 125,
+          forecastType: "Product",
+        },
+        {
+          opportunity: { id: oppId },
+          status: { id: 1 },
+          forecastDescription: "Charlie",
+          revenue: 30,
+          cost: 10,
+          forecastType: "Product",
+        },
+        {
+          opportunity: { id: oppId },
+          status: { id: 1 },
+          forecastDescription: "Delta",
+          revenue: 75,
+          cost: 40,
+          forecastType: "Product",
+        },
+      ],
+    });
+    const items: any[] = postRes.data.forecastItems ?? [];
+    log("PRODUCTS", `Created ${items.length} items:`);
+    for (const it of items) {
+      console.log(
+        `  id=${it.id} desc="${it.forecastDescription}" rev=${it.revenue} cost=${it.cost}`,
+      );
+    }
+
+    // Snapshot prices
+    const priceSnap = new Map<string, { rev: number; cost: number }>(
+      items.map((i) => [
+        i.forecastDescription,
+        { rev: i.revenue, cost: i.cost },
+      ]),
+    );
+
+    // ── 4. Create procurement products ──────────────────────────────────────
+    log("PROCUREMENT", "Creating procurement products...");
+    const procProducts: any[] = [];
+    for (const item of items) {
+      try {
+        const pr = await cw.post("/procurement/products", {
+          catalogItem: { id: 87 },
+          description: item.forecastDescription,
+          quantity: 1,
+          price: item.revenue,
+          cost: item.cost,
+          billableOption: "Billable",
+          opportunity: { id: oppId },
+          forecastDetailId: item.id,
+        });
+        procProducts.push(pr.data);
+        procIdsToClean.push(pr.data.id);
+        console.log(
+          `  ✓ Proc ${pr.data.id} → forecastDetailId=${pr.data.forecastDetailId} "${item.forecastDescription}"`,
+        );
+      } catch (e: any) {
+        console.log(
+          `  ✗ Failed: ${e.response?.status} ${JSON.stringify(e.response?.data)}`,
+        );
+      }
+    }
+
+    if (procProducts.length === 0) {
+      log(
+        "PROCUREMENT",
+        "Could not create procurement products (permission issue?).",
+      );
+      log(
+        "PROCUREMENT",
+        "Will run reorder test without cancellation verification.",
+      );
+    }
+
+    // ── 5. Cancel "Bravo" procurement product ───────────────────────────────
+    const bravoProc = procProducts.find((p: any) => p.description === "Bravo");
+    if (bravoProc) {
+      log("CANCEL", `Cancelling Bravo (proc id=${bravoProc.id})...`);
+      try {
+        await cw.patch(`/procurement/products/${bravoProc.id}`, [
+          { op: "replace", path: "cancelledFlag", value: true },
+          { op: "replace", path: "quantityCancelled", value: 1 },
+          {
+            op: "replace",
+            path: "cancelledReason",
+            value: "Test cancellation",
+          },
+        ]);
+        log("CANCEL", "✓ Cancelled.");
+      } catch (e: any) {
+        log(
+          "CANCEL",
+          `✗ ${e.response?.status} ${JSON.stringify(e.response?.data)}`,
+        );
+      }
+    }
+
+    // ── 5b. Check for auto-created forecast items ─────────────────────────
+    await sleep(300);
+    const midForecast = await cw.get(forecastUrl);
+    const midItems = midForecast.data.forecastItems ?? [];
+    log(
+      "OBSERVE",
+      `Forecast items after procurement creation: ${midItems.length} (was ${items.length})`,
+    );
+    if (midItems.length !== items.length) {
+      log(
+        "OBSERVE",
+        "⚠ Creating procurement products auto-created additional forecast items!",
+      );
+      for (const mi of midItems) {
+        const isOriginal = items.some((i: any) => i.id === mi.id);
+        console.log(
+          `  id=${mi.id} desc="${mi.forecastDescription}" ${isOriginal ? "(original)" : "(AUTO-CREATED by procurement)"}`,
+        );
+      }
+    }
+
+    // Snapshot procurement state before reorder
+    const beforeProc = await cw.get(
+      `/procurement/products?conditions=${encodeURIComponent(`opportunity/id=${oppId}`)}&fields=id,forecastDetailId,cancelledFlag,quantityCancelled,cancelledReason,description`,
+    );
+    // Build map by description for cross-PUT comparison (IDs will change)
+    const beforeByDesc = new Map<string, any>();
+    log(
+      "SNAPSHOT",
+      `${beforeProc.data.length} procurement products before reorder:`,
+    );
+    for (const p of beforeProc.data) {
+      beforeByDesc.set(p.description, p);
+      console.log(
+        `  Proc ${p.id}: forecastDetailId=${p.forecastDetailId} cancelled=${p.cancelledFlag} qty=${p.quantityCancelled} reason="${p.cancelledReason ?? ""}" "${p.description}"`,
+      );
+    }
+
+    // Record old procurement IDs for later comparison
+    const oldProcIds = new Set(beforeProc.data.map((p: any) => p.id));
+
+    // ── 6. Reorder: reverse ONLY the original 4 forecast items ──────────────
+    log("REORDER", "Reversing forecast item order via PUT...");
+
+    // Only reorder the original items; keep any auto-created ones in place
+    const originalDescs = new Set(items.map((i: any) => i.forecastDescription));
+    const originals = midItems.filter(
+      (i: any) =>
+        originalDescs.has(i.forecastDescription) &&
+        items.some((o: any) => o.id === i.id),
+    );
+    const extras = midItems.filter(
+      (i: any) => !originals.some((o: any) => o.id === i.id),
+    );
+
+    const reversedOriginals = [...originals].reverse();
+    const reorderedAll = [...reversedOriginals, ...extras];
+
+    const clone = JSON.parse(JSON.stringify(midForecast.data));
+    clone.forecastItems = JSON.parse(JSON.stringify(reorderedAll));
+
+    const putRes = await cw.put(forecastUrl, clone);
+    const newItems: any[] = putRes.data.forecastItems ?? [];
+
+    log("REORDER", `After PUT (${newItems.length} items):`);
+    for (const it of newItems) {
+      console.log(
+        `  id=${it.id} desc="${it.forecastDescription}" rev=${it.revenue} cost=${it.cost}`,
+      );
+    }
+
+    // Build old→new ID map by position (for original items only)
+    const idMap = new Map<number, number>();
+    for (let i = 0; i < reversedOriginals.length && i < newItems.length; i++) {
+      idMap.set(reversedOriginals[i].id, newItems[i].id);
+    }
+    log("ID MAP", "Forecast item Old → New:");
+    for (const [oldId, newId] of idMap) {
+      console.log(`  ${oldId} → ${newId}`);
+    }
+
+    // ── 7. Check if procurement products survived PUT ───────────────────────
+    await sleep(300);
+    const afterProc = await cw.get(
+      `/procurement/products?conditions=${encodeURIComponent(`opportunity/id=${oppId}`)}&fields=id,forecastDetailId,cancelledFlag,quantityCancelled,cancelledReason,description`,
+    );
+    const newProcIds = new Set(afterProc.data.map((p: any) => p.id));
+
+    log(
+      "PROCUREMENT SURVIVAL",
+      "Checking if procurement product IDs survived PUT...",
+    );
+    const procSurvived = [...oldProcIds].every((id) => newProcIds.has(id));
+    if (procSurvived) {
+      console.log("  ✓ All original procurement product IDs survived PUT.");
+    } else {
+      console.log("  ✗ PUT REGENERATED procurement product IDs!");
+      console.log(`    Before: [${[...oldProcIds].join(", ")}]`);
+      console.log(`    After:  [${[...newProcIds].join(", ")}]`);
+    }
+
+    // Try remap if old IDs still exist
+    let remapOk = true;
+    if (procSurvived) {
+      log("REMAP", "Updating procurement products forecastDetailId...");
+      for (const pp of beforeProc.data) {
+        const oldFdId = pp.forecastDetailId as number;
+        const newFdId = idMap.get(oldFdId);
+        if (!newFdId || newFdId === oldFdId) continue;
+        try {
+          await cw.patch(`/procurement/products/${pp.id}`, [
+            { op: "replace", path: "forecastDetailId", value: newFdId },
+          ]);
+          console.log(
+            `  ✓ Proc ${pp.id}: forecastDetailId ${oldFdId} → ${newFdId}`,
+          );
+        } catch (e: any) {
+          remapOk = false;
+          console.log(
+            `  ✗ Proc ${pp.id} remap failed: ${e.response?.status} ${JSON.stringify(e.response?.data)}`,
+          );
+        }
+      }
+    } else {
+      remapOk = false;
+      log(
+        "REMAP",
+        "⚠ SKIPPED — procurement products were regenerated by PUT; old IDs no longer exist.",
+      );
+    }
+
+    // ── 8. Verify ───────────────────────────────────────────────────────────
+    await sleep(300);
+
+    // 8a. Verify order (first 4 items)
+    log("VERIFY ORDER", "Expected reverse: Delta, Charlie, Bravo, Alpha");
+    const expectedOrder = ["Delta", "Charlie", "Bravo", "Alpha"];
+    let orderOk = true;
+    for (let i = 0; i < expectedOrder.length; i++) {
+      const actual = newItems[i]?.forecastDescription;
+      const ok = actual === expectedOrder[i];
+      if (!ok) orderOk = false;
+      console.log(
+        `  Position ${i}: ${ok ? "✓" : "✗"} expected "${expectedOrder[i]}", got "${actual}"`,
+      );
+    }
+
+    // 8b. Verify prices (by description)
+    log("VERIFY PRICES", "");
+    let pricesOk = true;
+    for (const item of newItems) {
+      const orig = priceSnap.get(item.forecastDescription);
+      if (!orig) continue;
+      if (item.revenue !== orig.rev || item.cost !== orig.cost) {
+        pricesOk = false;
+        console.log(
+          `  ✗ "${item.forecastDescription}": rev ${orig.rev}→${item.revenue}, cost ${orig.cost}→${item.cost}`,
+        );
+      }
+    }
+    if (pricesOk) console.log("  ✓ All prices preserved.");
+
+    // 8c. Verify cancellation data — match by description since IDs may have changed
+    let cancelOk = true;
+    if (procProducts.length > 0) {
+      log(
+        "VERIFY CANCELLATION",
+        "Checking cancellation data on procurement products after PUT...",
+      );
+      const finalProc = await cw.get(
+        `/procurement/products?conditions=${encodeURIComponent(`opportunity/id=${oppId}`)}&fields=id,forecastDetailId,cancelledFlag,quantityCancelled,cancelledReason,description`,
+      );
+
+      // Track by procIdsToClean for cleanup
+      for (const p of finalProc.data) {
+        if (!procIdsToClean.includes(p.id)) procIdsToClean.push(p.id);
+      }
+
+      for (const pp of finalProc.data) {
+        const orig = beforeByDesc.get(pp.description);
+        if (!orig) {
+          console.log(
+            `  ? Proc ${pp.id} "${pp.description}" — no matching pre-PUT record`,
+          );
+          continue;
+        }
+
+        const cancelledMatch =
+          pp.cancelledFlag === orig.cancelledFlag &&
+          pp.quantityCancelled === orig.quantityCancelled &&
+          (pp.cancelledReason ?? "") === (orig.cancelledReason ?? "");
+
+        if (!cancelledMatch) {
+          cancelOk = false;
+          console.log(
+            `  ✗ Proc ${pp.id} "${pp.description}": CANCELLATION DATA CHANGED\n` +
+              `    Before: cancelled=${orig.cancelledFlag} qty=${orig.quantityCancelled} reason="${orig.cancelledReason ?? ""}"\n` +
+              `    After:  cancelled=${pp.cancelledFlag} qty=${pp.quantityCancelled} reason="${pp.cancelledReason ?? ""}"`,
+          );
+        } else {
+          console.log(
+            `  ✓ Proc ${pp.id} "${pp.description}": cancelled=${pp.cancelledFlag} qty=${pp.quantityCancelled} reason="${pp.cancelledReason ?? ""}"`,
+          );
+        }
+      }
+    }
+
+    // ── Summary ─────────────────────────────────────────────────────────────
+    log("SUMMARY", "");
+    console.log(
+      "  Order correct:              ",
+      orderOk ? "✓ PASS" : "✗ FAIL",
+    );
+    console.log(
+      "  Prices preserved:           ",
+      pricesOk ? "✓ PASS" : "✗ FAIL",
+    );
+    console.log(
+      "  Proc IDs survived PUT:      ",
+      procSurvived ? "✓ PASS" : "✗ FAIL",
+    );
+    console.log(
+      "  Procurement remap:          ",
+      remapOk ? "✓ PASS" : "✗ FAIL (skipped or failed)",
+    );
+    console.log(
+      "  Cancellation data preserved:",
+      cancelOk ? "✓ PASS" : "✗ FAIL",
+    );
+
+    const allPass = orderOk && pricesOk && procSurvived && remapOk && cancelOk;
+    log("RESULT", allPass ? "✓ ALL TESTS PASSED" : "✗ SOME TESTS FAILED");
+  } finally {
+    // ── Cleanup ─────────────────────────────────────────────────────────────
+    log("CLEANUP", "Deleting procurement products...");
+    for (const id of procIdsToClean) {
+      try {
+        await cw.delete(`/procurement/products/${id}`);
+      } catch {}
+    }
+    log("CLEANUP", `Deleted ${procIdsToClean.length} procurement products.`);
+
+    log("CLEANUP", `Deleting opportunity ${oppId}...`);
+    try {
+      await cw.delete(`/sales/opportunities/${oppId}`);
+      log("CLEANUP", "✓ Done.");
+    } catch (e: any) {
+      log("CLEANUP", `✗ ${e.response?.status ?? e.message}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error("\n[FATAL]", err.response?.data ?? err.message);
+  process.exit(1);
+});

tests/setup.ts

@@ -38,6 +38,14 @@ mock.module("../src/constants", () => ({
   connectWiseApi: {
     get: mock(() => Promise.resolve({ data: {} })),
     post: mock(() => Promise.resolve({ data: {} })),
+    put: mock(() => Promise.resolve({ data: {} })),
+    patch: mock(() => Promise.resolve({ data: {} })),
+    delete: mock(() => Promise.resolve({ data: {} })),
+  },
+  redis: {
+    get: mock(() => Promise.resolve(null)),
+    set: mock(() => Promise.resolve("OK")),
+    del: mock(() => Promise.resolve(1)),
   },
   unifi: createMockUnifi(),
   unifiControllerBaseUrl: "https://unifi.test.local",
@@ -235,3 +243,160 @@ export function buildMockUnifiSite(overrides: Record<string, any> = {}) {
     ...overrides,
   };
 }
+
+/** Build a minimal Prisma-shaped Opportunity row. */
+export function buildMockOpportunity(overrides: Record<string, any> = {}) {
+  return {
+    id: "opp-1",
+    cwOpportunityId: 1001,
+    name: "Test Opportunity",
+    notes: "Some notes",
+    typeName: "New Business",
+    typeCwId: 1,
+    stageName: "Proposal",
+    stageCwId: 2,
+    statusName: "Active",
+    statusCwId: 3,
+    priorityName: "High",
+    priorityCwId: 4,
+    ratingName: "Hot",
+    ratingCwId: 5,
+    source: "Referral",
+    campaignName: null,
+    campaignCwId: null,
+    primarySalesRepName: "John",
+    primarySalesRepIdentifier: "jroberts",
+    primarySalesRepCwId: 10,
+    secondarySalesRepName: null,
+    secondarySalesRepIdentifier: null,
+    secondarySalesRepCwId: null,
+    companyCwId: 123,
+    companyName: "Test Company",
+    contactCwId: 200,
+    contactName: "Jane Doe",
+    siteCwId: 300,
+    siteName: "Main Office",
+    customerPO: "PO-12345",
+    totalSalesTax: 50.0,
+    locationName: "HQ",
+    locationCwId: 400,
+    departmentName: "Sales",
+    departmentCwId: 500,
+    expectedCloseDate: new Date("2026-04-01"),
+    pipelineChangeDate: new Date("2026-02-15"),
+    dateBecameLead: new Date("2026-01-01"),
+    closedDate: null,
+    closedFlag: false,
+    closedByName: null,
+    closedByCwId: null,
+    companyId: "company-1",
+    cwLastUpdated: new Date("2026-02-28"),
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-02-28"),
+    company: null,
+    ...overrides,
+  };
+}
+
+/** Build a minimal CW Activity object for ActivityController tests. */
+export function buildMockCWActivity(overrides: Record<string, any> = {}) {
+  return {
+    id: 5001,
+    name: "Test Activity",
+    notes: "Activity notes",
+    type: { id: 1, name: "Call" },
+    status: { id: 2, name: "Open" },
+    company: { id: 123, identifier: "TestCo", name: "Test Company" },
+    contact: { id: 200, name: "Jane Doe" },
+    phoneNumber: "555-1234",
+    email: "jane@test.com",
+    opportunity: { id: 1001, name: "Test Opportunity" },
+    ticket: { id: 0, name: "" },
+    agreement: { id: 0, name: "" },
+    campaign: { id: 0, name: "" },
+    assignTo: { id: 10, identifier: "jroberts", name: "John Roberts" },
+    scheduleStatus: { id: 1, name: "Firm" },
+    reminder: { id: 1, name: "15 Minutes" },
+    where: { id: 1, name: "Office" },
+    dateStart: "2026-03-01T09:00:00Z",
+    dateEnd: "2026-03-01T10:00:00Z",
+    notifyFlag: false,
+    mobileGuid: "guid-abc123",
+    currency: { id: 1, name: "USD" },
+    customFields: [],
+    _info: {
+      lastUpdated: "2026-02-28T12:00:00Z",
+      updatedBy: "jroberts",
+      dateEntered: "2026-01-15T08:00:00Z",
+      enteredBy: "jroberts",
+    },
+    ...overrides,
+  };
+}
+
+/** Build a minimal CW Forecast Item for ForecastProductController tests. */
+export function buildMockCWForecastItem(overrides: Record<string, any> = {}) {
+  return {
+    id: 7001,
+    forecastDescription: "Network Switch",
+    opportunity: { id: 1001, name: "Test Opportunity" },
+    quantity: 5,
+    status: { id: 1, name: "Won" },
+    catalogItem: { id: 500, identifier: "USW-Pro-24" },
+    productDescription: "UniFi Switch Pro 24",
+    productClass: "Product",
+    forecastType: "Product",
+    revenue: 2500.0,
+    cost: 1800.0,
+    margin: 700.0,
+    percentage: 100,
+    includeFlag: true,
+    linkFlag: false,
+    recurringFlag: false,
+    taxableFlag: true,
+    recurringRevenue: 0,
+    recurringCost: 0,
+    cycles: 0,
+    sequenceNumber: 1,
+    subNumber: 0,
+    quoteWerksQuantity: 0,
+    _info: {
+      lastUpdated: "2026-02-28T12:00:00Z",
+      updatedBy: "jroberts",
+    },
+    ...overrides,
+  };
+}
+
+/** Build a minimal Prisma-shaped CatalogItem row. */
+export function buildMockCatalogItem(overrides: Record<string, any> = {}) {
+  return {
+    id: "cat-1",
+    cwCatalogId: 500,
+    identifier: "USW-Pro-24",
+    name: "UniFi Switch Pro 24",
+    description: "24-port managed switch",
+    customerDescription: "Enterprise switch",
+    internalNotes: null,
+    category: "Technology",
+    categoryCwId: 18,
+    subcategory: "Network-Switch",
+    subcategoryCwId: 112,
+    manufacturer: "Ubiquiti",
+    manufactureCwId: 248,
+    partNumber: "USW-Pro-24",
+    vendorName: "Ubiquiti Inc",
+    vendorSku: "USW-Pro-24",
+    vendorCwId: 100,
+    price: 500.0,
+    cost: 360.0,
+    inactive: false,
+    salesTaxable: true,
+    onHand: 10,
+    cwLastUpdated: new Date("2026-02-28"),
+    linkedItems: [],
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-02-28"),
+    ...overrides,
+  };
+}

tests/unit/activityTypes.test.ts

@@ -0,0 +1,89 @@
+import { describe, test, expect } from "bun:test";
+import type {
+  CWActivity,
+  CWActivitySummary,
+  CWActivityCustomField,
+  CWActivityInfo,
+  CWCreateActivity,
+  CWUpdateActivity,
+  CWPatchOperation,
+} from "../../src/modules/cw-utils/activities/activity.types";
+
+describe("activity.types", () => {
+  test("CWActivity type has all required fields", () => {
+    const activity: CWActivity = {
+      id: 1,
+      name: "Test Call",
+      type: { id: 1, name: "Call" },
+      company: { id: 100, identifier: "TestCo", name: "Test Company" },
+      contact: { id: 200, name: "John" },
+      phoneNumber: "555-1234",
+      email: "test@test.com",
+      status: { id: 1, name: "Open" },
+      opportunity: { id: 300, name: "Opp" },
+      ticket: { id: 0, name: "" },
+      agreement: { id: 0, name: "" },
+      campaign: { id: 0, name: "" },
+      notes: "Some notes",
+      dateStart: "2026-01-01T09:00:00Z",
+      dateEnd: "2026-01-01T10:00:00Z",
+      assignTo: { id: 10, identifier: "jroberts", name: "John Roberts" },
+      scheduleStatus: { id: 1, name: "Firm" },
+      reminder: { id: 1, name: "15 min" },
+      where: { id: 1, name: "Office" },
+      notifyFlag: false,
+      mobileGuid: "guid-123",
+      currency: { id: 1, name: "USD" },
+      customFields: [],
+      _info: {
+        lastUpdated: "2026-01-01T12:00:00Z",
+        updatedBy: "admin",
+        dateEntered: "2026-01-01T08:00:00Z",
+        enteredBy: "admin",
+      },
+    };
+
+    expect(activity.id).toBe(1);
+    expect(activity.name).toBe("Test Call");
+    expect(activity.assignTo.identifier).toBe("jroberts");
+  });
+
+  test("CWCreateActivity allows partial fields", () => {
+    const create: CWCreateActivity = {
+      name: "New Activity",
+      opportunity: { id: 300 },
+    };
+    expect(create.name).toBe("New Activity");
+    expect(create.company).toBeUndefined();
+  });
+
+  test("CWPatchOperation has op, path, value", () => {
+    const op: CWPatchOperation = {
+      op: "replace",
+      path: "name",
+      value: "Updated Name",
+    };
+    expect(op.op).toBe("replace");
+    expect(op.path).toBe("name");
+  });
+
+  test("CWActivitySummary is lightweight", () => {
+    const summary: CWActivitySummary = {
+      id: 42,
+      _info: { lastUpdated: "2026-01-01T00:00:00Z" },
+    };
+    expect(summary.id).toBe(42);
+  });
+
+  test("CWActivityCustomField has expected shape", () => {
+    const field: CWActivityCustomField = {
+      id: 1,
+      caption: "Project Code",
+      type: "Text",
+      entryMethod: "EntryField",
+      numberOfDecimals: 0,
+      value: "PRJ-001",
+    };
+    expect(field.caption).toBe("Project Code");
+  });
+});

tests/unit/catalogCategories.test.ts

@@ -0,0 +1,336 @@
+import { describe, test, expect } from "bun:test";
+import {
+  CATEGORY_TREE,
+  ECOSYSTEM_TREE,
+  isCategoryGroup,
+  getSubcategoriesForCategory,
+  getSubcategoriesForGroup,
+  getCategoryNames,
+  getGroupForSubcategory,
+  serializeCategoryTree,
+  serializeEcosystemTree,
+  getAllSubcategoryNames,
+  getCategoryForSubcategory,
+  getEcosystemsForManufacturer,
+  matchesEcosystem,
+} from "../../src/modules/catalog-categories/catalogCategories";
+
+describe("catalogCategories", () => {
+  // -------------------------------------------------------------------
+  // Data validation
+  // -------------------------------------------------------------------
+  describe("CATEGORY_TREE", () => {
+    test("exports a non-empty array", () => {
+      expect(Array.isArray(CATEGORY_TREE)).toBe(true);
+      expect(CATEGORY_TREE.length).toBeGreaterThan(0);
+    });
+
+    test("contains Technology, General, and Field categories", () => {
+      const names = CATEGORY_TREE.map((c) => c.name);
+      expect(names).toContain("Technology");
+      expect(names).toContain("General");
+      expect(names).toContain("Field");
+    });
+
+    test("each category has a name and entries", () => {
+      for (const cat of CATEGORY_TREE) {
+        expect(typeof cat.name).toBe("string");
+        expect(Array.isArray(cat.entries)).toBe(true);
+        expect(cat.entries.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe("ECOSYSTEM_TREE", () => {
+    test("exports a non-empty array", () => {
+      expect(Array.isArray(ECOSYSTEM_TREE)).toBe(true);
+      expect(ECOSYSTEM_TREE.length).toBeGreaterThan(0);
+    });
+
+    test("contains Networking, Video Surveillance, and Burg/Alarm", () => {
+      const names = ECOSYSTEM_TREE.map((e) => e.name);
+      expect(names).toContain("Networking");
+      expect(names).toContain("Video Surveillance");
+      expect(names).toContain("Burg/Alarm");
+    });
+
+    test("each ecosystem has manufacturers with required fields", () => {
+      for (const eco of ECOSYSTEM_TREE) {
+        expect(eco.manufacturers.length).toBeGreaterThan(0);
+        for (const mfg of eco.manufacturers) {
+          expect(typeof mfg.name).toBe("string");
+          expect(typeof mfg.category).toBe("string");
+          expect(typeof mfg.subcategoryPrefix).toBe("string");
+        }
+      }
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // isCategoryGroup
+  // -------------------------------------------------------------------
+  describe("isCategoryGroup()", () => {
+    test("returns true for group entries", () => {
+      const group = { name: "Network", children: [{ name: "Network-Switch" }] };
+      expect(isCategoryGroup(group)).toBe(true);
+    });
+
+    test("returns false for subcategory entries", () => {
+      const leaf = { name: "Batteries", cwId: 80 };
+      expect(isCategoryGroup(leaf)).toBe(false);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getSubcategoriesForCategory
+  // -------------------------------------------------------------------
+  describe("getSubcategoriesForCategory()", () => {
+    test("returns subcategories for Technology", () => {
+      const subcats = getSubcategoriesForCategory("Technology");
+      expect(subcats.length).toBeGreaterThan(0);
+      expect(subcats).toContain("GeneralEquip");
+      expect(subcats).toContain("Network-Switch");
+    });
+
+    test("returns subcategories for Field", () => {
+      const subcats = getSubcategoriesForCategory("Field");
+      expect(subcats).toContain("Conduit");
+      expect(subcats).toContain("AlarmBurg-Panels");
+      expect(subcats).toContain("Surveillance-CamerasIP");
+    });
+
+    test("returns empty for unknown category", () => {
+      expect(getSubcategoriesForCategory("NonExistent")).toEqual([]);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getSubcategoriesForGroup
+  // -------------------------------------------------------------------
+  describe("getSubcategoriesForGroup()", () => {
+    test("returns subcategories for Technology/Network", () => {
+      const subcats = getSubcategoriesForGroup("Technology", "Network");
+      expect(subcats).toContain("Network-Other");
+      expect(subcats).toContain("Network-Router");
+      expect(subcats).toContain("Network-Switch");
+      expect(subcats).toContain("Network-Wireless");
+    });
+
+    test("returns subcategories for Field/AlarmBurg", () => {
+      const subcats = getSubcategoriesForGroup("Field", "AlarmBurg");
+      expect(subcats).toContain("AlarmBurg-Panels");
+      expect(subcats).toContain("AlarmBurg-Keypads");
+    });
+
+    test("returns empty for unknown group", () => {
+      expect(getSubcategoriesForGroup("Technology", "NonExistent")).toEqual([]);
+    });
+
+    test("returns empty for unknown category", () => {
+      expect(getSubcategoriesForGroup("NonExistent", "Network")).toEqual([]);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getCategoryNames
+  // -------------------------------------------------------------------
+  describe("getCategoryNames()", () => {
+    test("returns all top-level category names", () => {
+      const names = getCategoryNames();
+      expect(names).toContain("Technology");
+      expect(names).toContain("General");
+      expect(names).toContain("Field");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getGroupForSubcategory
+  // -------------------------------------------------------------------
+  describe("getGroupForSubcategory()", () => {
+    test("returns group for a grouped subcategory", () => {
+      const result = getGroupForSubcategory("Network-Switch");
+      expect(result).toEqual({ category: "Technology", group: "Network" });
+    });
+
+    test("returns group for AlarmBurg subcategory", () => {
+      const result = getGroupForSubcategory("AlarmBurg-Panels");
+      expect(result).toEqual({ category: "Field", group: "AlarmBurg" });
+    });
+
+    test("returns null for a direct subcategory", () => {
+      const result = getGroupForSubcategory("GeneralEquip");
+      expect(result).toBeNull();
+    });
+
+    test("returns null for unknown subcategory", () => {
+      const result = getGroupForSubcategory("Unknown");
+      expect(result).toBeNull();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getCategoryForSubcategory
+  // -------------------------------------------------------------------
+  describe("getCategoryForSubcategory()", () => {
+    test("resolves grouped subcategory to its category", () => {
+      expect(getCategoryForSubcategory("Network-Switch")).toBe("Technology");
+    });
+
+    test("resolves direct subcategory to its category", () => {
+      expect(getCategoryForSubcategory("Batteries")).toBe("General");
+    });
+
+    test("resolves Field subcategories", () => {
+      expect(getCategoryForSubcategory("Conduit")).toBe("Field");
+    });
+
+    test("returns null for unknown subcategory", () => {
+      expect(getCategoryForSubcategory("Unknown")).toBeNull();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getAllSubcategoryNames
+  // -------------------------------------------------------------------
+  describe("getAllSubcategoryNames()", () => {
+    test("returns non-empty array", () => {
+      const names = getAllSubcategoryNames();
+      expect(names.length).toBeGreaterThan(0);
+    });
+
+    test("includes direct and grouped subcategories", () => {
+      const names = getAllSubcategoryNames();
+      expect(names).toContain("GeneralEquip");
+      expect(names).toContain("Network-Switch");
+      expect(names).toContain("Batteries");
+      expect(names).toContain("AlarmBurg-Panels");
+    });
+
+    test("does not include top-level categories", () => {
+      const names = getAllSubcategoryNames();
+      expect(names).not.toContain("Technology");
+      expect(names).not.toContain("General");
+      expect(names).not.toContain("Field");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getEcosystemsForManufacturer
+  // -------------------------------------------------------------------
+  describe("getEcosystemsForManufacturer()", () => {
+    test("returns Networking for Ubiquiti", () => {
+      const ecosystems = getEcosystemsForManufacturer("Ubiquiti");
+      expect(ecosystems).toContain("Networking");
+    });
+
+    test("returns Video Surveillance for Uniview", () => {
+      const ecosystems = getEcosystemsForManufacturer("Uniview");
+      expect(ecosystems).toContain("Video Surveillance");
+    });
+
+    test("returns empty for unknown manufacturer", () => {
+      expect(getEcosystemsForManufacturer("Unknown")).toEqual([]);
+    });
+
+    test("is case-insensitive", () => {
+      const result = getEcosystemsForManufacturer("ubiquiti");
+      expect(result).toContain("Networking");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // matchesEcosystem
+  // -------------------------------------------------------------------
+  describe("matchesEcosystem()", () => {
+    test("matches Ubiquiti Network-Switch to Networking", () => {
+      expect(matchesEcosystem("Networking", "Ubiquiti", "Network-Switch")).toBe(
+        true,
+      );
+    });
+
+    test("matches Uniview Surveillance-CamerasIP to Video Surveillance", () => {
+      expect(
+        matchesEcosystem(
+          "Video Surveillance",
+          "Uniview",
+          "Surveillance-CamerasIP",
+        ),
+      ).toBe(true);
+    });
+
+    test("does not match wrong ecosystem", () => {
+      expect(
+        matchesEcosystem("Networking", "Uniview", "Surveillance-CamerasIP"),
+      ).toBe(false);
+    });
+
+    test("returns false for unknown ecosystem", () => {
+      expect(matchesEcosystem("Unknown", "Ubiquiti", "Network-Switch")).toBe(
+        false,
+      );
+    });
+
+    test("handles null manufacturer", () => {
+      expect(matchesEcosystem("Networking", null, "Network-Switch")).toBe(
+        false,
+      );
+    });
+
+    test("handles null subcategory", () => {
+      expect(matchesEcosystem("Networking", "Ubiquiti", null)).toBe(false);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // serializeCategoryTree
+  // -------------------------------------------------------------------
+  describe("serializeCategoryTree()", () => {
+    test("returns array with same length as CATEGORY_TREE", () => {
+      const result = serializeCategoryTree();
+      expect(result).toHaveLength(CATEGORY_TREE.length);
+    });
+
+    test("entries have type 'group' or 'subcategory'", () => {
+      const result = serializeCategoryTree();
+      for (const cat of result) {
+        for (const entry of cat.entries) {
+          expect(["group", "subcategory"]).toContain(entry.type);
+        }
+      }
+    });
+
+    test("group entries have subcategories array", () => {
+      const result = serializeCategoryTree();
+      const techCat = result.find((c) => c.name === "Technology")!;
+      const networkGroup = techCat.entries.find(
+        (e) => e.type === "group" && e.name === "Network",
+      );
+      expect(networkGroup).toBeDefined();
+      if (networkGroup && "subcategories" in networkGroup) {
+        expect(networkGroup.subcategories.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // serializeEcosystemTree
+  // -------------------------------------------------------------------
+  describe("serializeEcosystemTree()", () => {
+    test("returns array with same length as ECOSYSTEM_TREE", () => {
+      const result = serializeEcosystemTree();
+      expect(result).toHaveLength(ECOSYSTEM_TREE.length);
+    });
+
+    test("each ecosystem has manufacturers with category and prefix", () => {
+      const result = serializeEcosystemTree();
+      for (const eco of result) {
+        expect(eco.manufacturers.length).toBeGreaterThan(0);
+        for (const mfg of eco.manufacturers) {
+          expect(typeof mfg.name).toBe("string");
+          expect(typeof mfg.category).toBe("string");
+          expect(typeof mfg.subcategoryPrefix).toBe("string");
+        }
+      }
+    });
+  });
+});

tests/unit/companySites.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect } from "bun:test";
+import {
+  type CWCompanySite,
+  serializeCwSite,
+} from "../../src/modules/cw-utils/sites/companySites";
+
+function buildMockSite(overrides: Partial<CWCompanySite> = {}): CWCompanySite {
+  return {
+    id: 1,
+    name: "Main Office",
+    addressLine1: "123 Test St",
+    city: "Austin",
+    stateReference: { id: 1, identifier: "TX", name: "Texas" },
+    zip: "78701",
+    country: { id: 1, name: "United States" },
+    phoneNumber: "512-555-0100",
+    faxNumber: "512-555-0101",
+    taxCodeId: 10,
+    expenseReimbursement: 0,
+    primaryAddressFlag: true,
+    defaultShippingFlag: false,
+    defaultBillingFlag: true,
+    defaultMailingFlag: false,
+    mobileGuid: "guid-123",
+    calendar: null,
+    timeZone: null,
+    company: { id: 100, identifier: "TestCo", name: "Test Company" },
+    _info: {},
+    ...overrides,
+  };
+}
+
+describe("serializeCwSite", () => {
+  test("serializes a full site correctly", () => {
+    const site = buildMockSite();
+    const result = serializeCwSite(site);
+
+    expect(result.id).toBe(1);
+    expect(result.name).toBe("Main Office");
+    expect(result.address.line1).toBe("123 Test St");
+    expect(result.address.line2).toBeNull();
+    expect(result.address.city).toBe("Austin");
+    expect(result.address.state).toBe("Texas");
+    expect(result.address.zip).toBe("78701");
+    expect(result.address.country).toBe("United States");
+    expect(result.phoneNumber).toBe("512-555-0100");
+    expect(result.faxNumber).toBe("512-555-0101");
+    expect(result.primaryAddressFlag).toBe(true);
+    expect(result.defaultShippingFlag).toBe(false);
+    expect(result.defaultBillingFlag).toBe(true);
+    expect(result.defaultMailingFlag).toBe(false);
+  });
+
+  test("handles addressLine2 present", () => {
+    const site = buildMockSite({ addressLine2: "Suite 200" });
+    const result = serializeCwSite(site);
+    expect(result.address.line2).toBe("Suite 200");
+  });
+
+  test("handles null stateReference", () => {
+    const site = buildMockSite({ stateReference: null });
+    const result = serializeCwSite(site);
+    expect(result.address.state).toBeNull();
+  });
+
+  test("handles null country — defaults to United States", () => {
+    const site = buildMockSite({ country: null });
+    const result = serializeCwSite(site);
+    expect(result.address.country).toBe("United States");
+  });
+
+  test("handles empty phoneNumber and faxNumber", () => {
+    const site = buildMockSite({ phoneNumber: "", faxNumber: "" });
+    const result = serializeCwSite(site);
+    expect(result.phoneNumber).toBeNull();
+    expect(result.faxNumber).toBeNull();
+  });
+
+  test("does not include internal fields", () => {
+    const site = buildMockSite();
+    const result = serializeCwSite(site);
+    expect(result).not.toHaveProperty("_info");
+    expect(result).not.toHaveProperty("mobileGuid");
+    expect(result).not.toHaveProperty("company");
+    expect(result).not.toHaveProperty("taxCodeId");
+  });
+});

tests/unit/computeCacheTTL.test.ts

@@ -0,0 +1,477 @@
+import { describe, test, expect } from "bun:test";
+import {
+  computeCacheTTL,
+  TTL_HIGH_ACTIVITY,
+  TTL_MODERATE_ACTIVITY,
+  TTL_LOW_ACTIVITY,
+} from "../../src/modules/algorithms/computeCacheTTL";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Fixed reference point so tests are deterministic. */
+const NOW = new Date("2026-03-02T12:00:00Z");
+
+/** Return a Date offset from NOW by `days` (negative = past, positive = future). */
+const daysFromNow = (days: number): Date =>
+  new Date(NOW.getTime() + days * 24 * 60 * 60 * 1000);
+
+// ---------------------------------------------------------------------------
+// Rule 1a — Closed records older than 30 days should not be cached
+// ---------------------------------------------------------------------------
+describe("computeCacheTTL — Rule 1a: Closed records (>30 days)", () => {
+  test("returns null when closedFlag is true and closedDate is null", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBeNull();
+  });
+
+  test("returns null when closedFlag is true and closedDate is 60 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: daysFromNow(-60),
+        expectedCloseDate: daysFromNow(-1),
+        lastUpdated: daysFromNow(-1),
+        now: NOW,
+      }),
+    ).toBeNull();
+  });
+
+  test("returns null when closedFlag is true and closedDate is 31 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: new Date(NOW.getTime() - 31 * 24 * 60 * 60 * 1000),
+        expectedCloseDate: daysFromNow(2),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rule 1b — Recently closed (within 30 days) → 15 minutes
+// ---------------------------------------------------------------------------
+describe("computeCacheTTL — Rule 1b: Recently closed (≤30 days)", () => {
+  test("returns 15min when closed 1 day ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: daysFromNow(-1),
+        expectedCloseDate: null,
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("returns 15min when closed 15 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: daysFromNow(-15),
+        expectedCloseDate: null,
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("returns 15min when closed exactly 30 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: daysFromNow(-30),
+        expectedCloseDate: null,
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("returns 15min when closed today even with recent activity dates", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: NOW,
+        expectedCloseDate: daysFromNow(-1),
+        lastUpdated: NOW,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("just past 30-day boundary returns null", () => {
+    const justPast30Days = new Date(
+      NOW.getTime() - 30 * 24 * 60 * 60 * 1000 - 1,
+    );
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: justPast30Days,
+        expectedCloseDate: null,
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rule 2 — High activity (within 5 days) → 30 seconds
+// ---------------------------------------------------------------------------
+describe("computeCacheTTL — Rule 2: High activity (≤5 days)", () => {
+  test("returns 30s when lastUpdated is today", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: NOW,
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("returns 30s when lastUpdated is 3 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-3),
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("returns 30s when lastUpdated is exactly 5 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-5),
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("returns 30s when expectedCloseDate is 2 days in the future", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(2),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("returns 30s when expectedCloseDate is 5 days in the future", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(5),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("returns 30s when expectedCloseDate is 4 days ago (recently passed)", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(-4),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("returns 30s when either date is within 5 days (lastUpdated wins)", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(-30),
+        lastUpdated: daysFromNow(-2),
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("returns 30s when either date is within 5 days (expectedCloseDate wins)", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(3),
+        lastUpdated: daysFromNow(-30),
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rule 3 — Moderate activity (within 14 days but > 5 days) → 60 seconds
+// ---------------------------------------------------------------------------
+describe("computeCacheTTL — Rule 3: Moderate activity (6–14 days)", () => {
+  test("returns 60s when lastUpdated is 6 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-6),
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+
+  test("returns 60s when lastUpdated is 10 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-10),
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+
+  test("returns 60s when lastUpdated is exactly 14 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-14),
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+
+  test("returns 60s when expectedCloseDate is 8 days in the future", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(8),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+
+  test("returns 60s when expectedCloseDate is 14 days in the future", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(14),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+
+  test("returns 60s when expectedCloseDate is 12 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(-12),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rule 4 — Low activity (older than 14 days) → 15 minutes
+// ---------------------------------------------------------------------------
+describe("computeCacheTTL — Rule 4: Low activity (>14 days)", () => {
+  test("returns 15min when lastUpdated is 15 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-15),
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("returns 15min when lastUpdated is 60 days ago", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-60),
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("returns 15min when expectedCloseDate is 20 days in the future", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(20),
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("returns 15min when both dates are null", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: null,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("returns 15min when both dates are far in the past", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(-100),
+        lastUpdated: daysFromNow(-90),
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases
+// ---------------------------------------------------------------------------
+describe("computeCacheTTL — edge cases", () => {
+  test("defaults `now` to current time when omitted", () => {
+    // Open, no dates → should return LOW_ACTIVITY (15min)
+    const result = computeCacheTTL({
+      closedFlag: false,
+      closedDate: null,
+      expectedCloseDate: null,
+      lastUpdated: null,
+    });
+    expect(result).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("5-day boundary is inclusive", () => {
+    // Exactly 5 days should match high activity
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-5),
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("just past 5-day boundary falls to moderate", () => {
+    // 5 days + 1 millisecond past → moderate
+    const justPast5Days = new Date(NOW.getTime() - 5 * 24 * 60 * 60 * 1000 - 1);
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: justPast5Days,
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+
+  test("14-day boundary is inclusive", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: daysFromNow(-14),
+        now: NOW,
+      }),
+    ).toBe(TTL_MODERATE_ACTIVITY);
+  });
+
+  test("just past 14-day boundary falls to low activity", () => {
+    const justPast14Days = new Date(
+      NOW.getTime() - 14 * 24 * 60 * 60 * 1000 - 1,
+    );
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: null,
+        lastUpdated: justPast14Days,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+
+  test("higher-priority rule wins when both dates span different tiers", () => {
+    // expectedCloseDate in 5-day window, lastUpdated in 14-day window → 30s
+    expect(
+      computeCacheTTL({
+        closedFlag: false,
+        closedDate: null,
+        expectedCloseDate: daysFromNow(3),
+        lastUpdated: daysFromNow(-10),
+        now: NOW,
+      }),
+    ).toBe(TTL_HIGH_ACTIVITY);
+  });
+
+  test("closed >30 days always returns null regardless of other dates", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: daysFromNow(-60),
+        expectedCloseDate: NOW,
+        lastUpdated: NOW,
+        now: NOW,
+      }),
+    ).toBeNull();
+  });
+
+  test("recently closed always returns 15min regardless of activity dates", () => {
+    expect(
+      computeCacheTTL({
+        closedFlag: true,
+        closedDate: daysFromNow(-5),
+        expectedCloseDate: NOW,
+        lastUpdated: NOW,
+        now: NOW,
+      }),
+    ).toBe(TTL_LOW_ACTIVITY);
+  });
+});

tests/unit/controllers/ActivityController.test.ts

@@ -0,0 +1,196 @@
+import { describe, test, expect } from "bun:test";
+import { ActivityController } from "../../../src/controllers/ActivityController";
+import { buildMockCWActivity } from "../../setup";
+
+describe("ActivityController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets all public properties from CW data", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.cwActivityId).toBe(5001);
+      expect(ctrl.name).toBe("Test Activity");
+      expect(ctrl.notes).toBe("Activity notes");
+    });
+
+    test("maps type reference", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.typeCwId).toBe(1);
+      expect(ctrl.typeName).toBe("Call");
+    });
+
+    test("maps status reference", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.statusCwId).toBe(2);
+      expect(ctrl.statusName).toBe("Open");
+    });
+
+    test("maps company reference", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.companyCwId).toBe(123);
+      expect(ctrl.companyName).toBe("Test Company");
+      expect(ctrl.companyIdentifier).toBe("TestCo");
+    });
+
+    test("maps contact reference", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.contactCwId).toBe(200);
+      expect(ctrl.contactName).toBe("Jane Doe");
+    });
+
+    test("maps opportunity reference", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.opportunityCwId).toBe(1001);
+      expect(ctrl.opportunityName).toBe("Test Opportunity");
+    });
+
+    test("maps assignTo reference", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.assignToCwId).toBe(10);
+      expect(ctrl.assignToName).toBe("John Roberts");
+      expect(ctrl.assignToIdentifier).toBe("jroberts");
+    });
+
+    test("maps dates correctly", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.dateStart).toBeInstanceOf(Date);
+      expect(ctrl.dateEnd).toBeInstanceOf(Date);
+    });
+
+    test("maps _info dates", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.cwLastUpdated).toBeInstanceOf(Date);
+      expect(ctrl.cwDateEntered).toBeInstanceOf(Date);
+      expect(ctrl.cwEnteredBy).toBe("jroberts");
+      expect(ctrl.cwUpdatedBy).toBe("jroberts");
+    });
+
+    test("handles null optional fields gracefully", () => {
+      const ctrl = new ActivityController(
+        buildMockCWActivity({
+          type: undefined,
+          status: undefined,
+          company: undefined,
+          contact: undefined,
+          opportunity: undefined,
+          assignTo: undefined,
+          dateStart: undefined,
+          dateEnd: undefined,
+          notes: undefined,
+          _info: {},
+        }),
+      );
+      expect(ctrl.typeCwId).toBeNull();
+      expect(ctrl.typeName).toBeNull();
+      expect(ctrl.statusCwId).toBeNull();
+      expect(ctrl.companyCwId).toBeNull();
+      expect(ctrl.contactCwId).toBeNull();
+      expect(ctrl.opportunityCwId).toBeNull();
+      expect(ctrl.assignToCwId).toBeNull();
+      expect(ctrl.dateStart).toBeNull();
+      expect(ctrl.dateEnd).toBeNull();
+      expect(ctrl.notes).toBeNull();
+      expect(ctrl.cwLastUpdated).toBeNull();
+    });
+
+    test("maps phoneNumber and email", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.phoneNumber).toBe("555-1234");
+      expect(ctrl.email).toBe("jane@test.com");
+    });
+
+    test("maps notifyFlag", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.notifyFlag).toBe(false);
+    });
+
+    test("maps customFields", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.customFields).toEqual([]);
+    });
+
+    test("maps mobileGuid", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      expect(ctrl.mobileGuid).toBe("guid-abc123");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns cwActivityId", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.cwActivityId).toBe(5001);
+    });
+
+    test("returns name and notes", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.name).toBe("Test Activity");
+      expect(json.notes).toBe("Activity notes");
+    });
+
+    test("formats type as reference object", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.type).toEqual({ id: 1, name: "Call" });
+    });
+
+    test("type is null when no type set", () => {
+      const ctrl = new ActivityController(
+        buildMockCWActivity({ type: undefined }),
+      );
+      const json = ctrl.toJson();
+      expect(json.type).toBeNull();
+    });
+
+    test("formats company as reference object with identifier", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.company).toEqual({
+        id: 123,
+        identifier: "TestCo",
+        name: "Test Company",
+      });
+    });
+
+    test("formats assignTo as reference object with identifier", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.assignTo).toEqual({
+        id: 10,
+        identifier: "jroberts",
+        name: "John Roberts",
+      });
+    });
+
+    test("formats opportunity as reference object", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.opportunity).toEqual({
+        id: 1001,
+        name: "Test Opportunity",
+      });
+    });
+
+    test("includes dates and meta", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.dateStart).toBeInstanceOf(Date);
+      expect(json.dateEnd).toBeInstanceOf(Date);
+      expect(json.cwLastUpdated).toBeInstanceOf(Date);
+      expect(json.cwDateEntered).toBeInstanceOf(Date);
+      expect(json.cwEnteredBy).toBe("jroberts");
+      expect(json.cwUpdatedBy).toBe("jroberts");
+    });
+
+    test("includes customFields array", () => {
+      const ctrl = new ActivityController(buildMockCWActivity());
+      const json = ctrl.toJson();
+      expect(json.customFields).toEqual([]);
+    });
+  });
+});

tests/unit/controllers/ForecastProductController.test.ts

@@ -0,0 +1,283 @@
+import { describe, test, expect } from "bun:test";
+import { ForecastProductController } from "../../../src/controllers/ForecastProductController";
+import { buildMockCWForecastItem } from "../../setup";
+
+describe("ForecastProductController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets core identification fields", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.cwForecastId).toBe(7001);
+      expect(ctrl.forecastDescription).toBe("Network Switch");
+    });
+
+    test("maps opportunity reference", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.opportunityCwId).toBe(1001);
+      expect(ctrl.opportunityName).toBe("Test Opportunity");
+    });
+
+    test("maps quantity", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.quantity).toBe(5);
+    });
+
+    test("maps status reference", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.statusCwId).toBe(1);
+      expect(ctrl.statusName).toBe("Won");
+    });
+
+    test("maps catalogItem reference", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.catalogItemCwId).toBe(500);
+      expect(ctrl.catalogItemIdentifier).toBe("USW-Pro-24");
+    });
+
+    test("maps product details", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.productDescription).toBe("UniFi Switch Pro 24");
+      expect(ctrl.productClass).toBe("Product");
+      expect(ctrl.forecastType).toBe("Product");
+    });
+
+    test("maps financials", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.revenue).toBe(2500.0);
+      expect(ctrl.cost).toBe(1800.0);
+      expect(ctrl.margin).toBe(700.0);
+      expect(ctrl.percentage).toBe(100);
+    });
+
+    test("maps boolean flags", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.includeFlag).toBe(true);
+      expect(ctrl.linkFlag).toBe(false);
+      expect(ctrl.recurringFlag).toBe(false);
+      expect(ctrl.taxableFlag).toBe(true);
+    });
+
+    test("maps sequence and sub number", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.sequenceNumber).toBe(1);
+      expect(ctrl.subNumber).toBe(0);
+    });
+
+    test("maps recurring fields", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.recurringRevenue).toBe(0);
+      expect(ctrl.recurringCost).toBe(0);
+      expect(ctrl.cycles).toBe(0);
+    });
+
+    test("sets cancellation defaults", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.cancelledFlag).toBe(false);
+      expect(ctrl.quantityCancelled).toBe(0);
+      expect(ctrl.cancelledReason).toBeNull();
+      expect(ctrl.cancelledBy).toBeNull();
+      expect(ctrl.cancelledDate).toBeNull();
+    });
+
+    test("sets inventory defaults", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.onHand).toBeNull();
+      expect(ctrl.inStock).toBeNull();
+    });
+
+    test("maps _info to cwLastUpdated", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.cwLastUpdated).toBeInstanceOf(Date);
+      expect(ctrl.cwUpdatedBy).toBe("jroberts");
+    });
+
+    test("handles missing optional fields", () => {
+      const ctrl = new ForecastProductController(
+        buildMockCWForecastItem({
+          opportunity: undefined,
+          status: undefined,
+          catalogItem: undefined,
+          _info: undefined,
+        }),
+      );
+      expect(ctrl.opportunityCwId).toBeNull();
+      expect(ctrl.statusCwId).toBeNull();
+      expect(ctrl.catalogItemCwId).toBeNull();
+      expect(ctrl.cwLastUpdated).toBeNull();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // applyCancellationData
+  // -------------------------------------------------------------------
+  describe("applyCancellationData()", () => {
+    test("applies cancellation data", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      ctrl.applyCancellationData({
+        cancelledFlag: true,
+        quantityCancelled: 3,
+        cancelledReason: "Out of stock",
+        cancelledBy: 42,
+        cancelledDate: "2026-02-20T00:00:00Z",
+      });
+      expect(ctrl.cancelledFlag).toBe(true);
+      expect(ctrl.quantityCancelled).toBe(3);
+      expect(ctrl.cancelledReason).toBe("Out of stock");
+      expect(ctrl.cancelledBy).toBe(42);
+      expect(ctrl.cancelledDate).toBeInstanceOf(Date);
+    });
+
+    test("handles partial cancellation data", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      ctrl.applyCancellationData({});
+      expect(ctrl.cancelledFlag).toBe(false);
+      expect(ctrl.quantityCancelled).toBe(0);
+      expect(ctrl.cancelledReason).toBeNull();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // applyInventoryData
+  // -------------------------------------------------------------------
+  describe("applyInventoryData()", () => {
+    test("sets onHand and inStock true when quantity > 0", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      ctrl.applyInventoryData({ onHand: 10 });
+      expect(ctrl.onHand).toBe(10);
+      expect(ctrl.inStock).toBe(true);
+    });
+
+    test("sets inStock false when onHand is 0", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      ctrl.applyInventoryData({ onHand: 0 });
+      expect(ctrl.onHand).toBe(0);
+      expect(ctrl.inStock).toBe(false);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // Computed properties
+  // -------------------------------------------------------------------
+  describe("computed properties", () => {
+    test("profit returns revenue - cost", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.profit).toBe(700.0);
+    });
+
+    test("cancelled returns false by default", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.cancelled).toBe(false);
+    });
+
+    test("cancelled returns true after applyCancellationData", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      ctrl.applyCancellationData({ cancelledFlag: true, quantityCancelled: 1 });
+      expect(ctrl.cancelled).toBe(true);
+    });
+
+    test("cancellationType returns null when not cancelled", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      expect(ctrl.cancellationType).toBeNull();
+    });
+
+    test("cancellationType returns 'full' when all units cancelled", () => {
+      const ctrl = new ForecastProductController(
+        buildMockCWForecastItem({ quantity: 5 }),
+      );
+      ctrl.applyCancellationData({
+        cancelledFlag: true,
+        quantityCancelled: 5,
+      });
+      expect(ctrl.cancellationType).toBe("full");
+    });
+
+    test("cancellationType returns 'partial' when some units cancelled", () => {
+      const ctrl = new ForecastProductController(
+        buildMockCWForecastItem({ quantity: 5 }),
+      );
+      ctrl.applyCancellationData({
+        cancelledFlag: true,
+        quantityCancelled: 2,
+      });
+      expect(ctrl.cancellationType).toBe("partial");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns id as cwForecastId", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.id).toBe(7001);
+    });
+
+    test("returns financial fields", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.revenue).toBe(2500.0);
+      expect(json.cost).toBe(1800.0);
+      expect(json.margin).toBe(700.0);
+      expect(json.profit).toBe(700.0);
+    });
+
+    test("returns cancellation info", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.cancelled).toBe(false);
+      expect(json.cancellationType).toBeNull();
+    });
+
+    test("returns status as reference object", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.status).toEqual({ id: 1, name: "Won" });
+    });
+
+    test("returns catalogItem as reference object", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.catalogItem).toEqual({
+        id: 500,
+        identifier: "USW-Pro-24",
+      });
+    });
+
+    test("returns opportunity as reference object", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.opportunity).toEqual({
+        id: 1001,
+        name: "Test Opportunity",
+      });
+    });
+
+    test("includes inventory data", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      ctrl.applyInventoryData({ onHand: 10 });
+      const json = ctrl.toJson();
+      expect(json.onHand).toBe(10);
+      expect(json.inStock).toBe(true);
+    });
+
+    test("includes boolean flags", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.includeFlag).toBe(true);
+      expect(json.linkFlag).toBe(false);
+      expect(json.recurringFlag).toBe(false);
+      expect(json.taxableFlag).toBe(true);
+    });
+
+    test("includes sequence and timing info", () => {
+      const ctrl = new ForecastProductController(buildMockCWForecastItem());
+      const json = ctrl.toJson();
+      expect(json.sequenceNumber).toBe(1);
+      expect(json.subNumber).toBe(0);
+      expect(json.cwLastUpdated).toBeInstanceOf(Date);
+    });
+  });
+});

tests/unit/controllers/OpportunityController.test.ts

@@ -0,0 +1,283 @@
+import { describe, test, expect } from "bun:test";
+import { OpportunityController } from "../../../src/controllers/OpportunityController";
+import { ActivityController } from "../../../src/controllers/ActivityController";
+import { CompanyController } from "../../../src/controllers/CompanyController";
+import {
+  buildMockOpportunity,
+  buildMockCompany,
+  buildMockCWActivity,
+} from "../../setup";
+
+describe("OpportunityController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets core identification fields", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      expect(ctrl.id).toBe("opp-1");
+      expect(ctrl.cwOpportunityId).toBe(1001);
+      expect(ctrl.name).toBe("Test Opportunity");
+      expect(ctrl.notes).toBe("Some notes");
+    });
+
+    test("sets type, stage, status references", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      expect(ctrl.typeName).toBe("New Business");
+      expect(ctrl.typeCwId).toBe(1);
+      expect(ctrl.stageName).toBe("Proposal");
+      expect(ctrl.stageCwId).toBe(2);
+      expect(ctrl.statusName).toBe("Active");
+      expect(ctrl.statusCwId).toBe(3);
+    });
+
+    test("sets priority, rating, source", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      expect(ctrl.priorityName).toBe("High");
+      expect(ctrl.priorityCwId).toBe(4);
+      expect(ctrl.ratingName).toBe("Hot");
+      expect(ctrl.ratingCwId).toBe(5);
+      expect(ctrl.source).toBe("Referral");
+    });
+
+    test("sets sales rep fields", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      expect(ctrl.primarySalesRepName).toBe("John");
+      expect(ctrl.primarySalesRepIdentifier).toBe("jroberts");
+      expect(ctrl.primarySalesRepCwId).toBe(10);
+      expect(ctrl.secondarySalesRepName).toBeNull();
+    });
+
+    test("sets company/contact/site fields", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      expect(ctrl.companyCwId).toBe(123);
+      expect(ctrl.companyName).toBe("Test Company");
+      expect(ctrl.contactCwId).toBe(200);
+      expect(ctrl.contactName).toBe("Jane Doe");
+      expect(ctrl.siteCwId).toBe(300);
+      expect(ctrl.siteName).toBe("Main Office");
+    });
+
+    test("sets financial and location fields", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      expect(ctrl.totalSalesTax).toBe(50.0);
+      expect(ctrl.customerPO).toBe("PO-12345");
+      expect(ctrl.locationName).toBe("HQ");
+      expect(ctrl.departmentName).toBe("Sales");
+    });
+
+    test("sets date fields", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      expect(ctrl.expectedCloseDate).toBeInstanceOf(Date);
+      expect(ctrl.pipelineChangeDate).toBeInstanceOf(Date);
+      expect(ctrl.dateBecameLead).toBeInstanceOf(Date);
+      expect(ctrl.closedDate).toBeNull();
+      expect(ctrl.closedFlag).toBe(false);
+    });
+
+    test("accepts company controller via opts", () => {
+      const company = new CompanyController(buildMockCompany());
+      const ctrl = new OpportunityController(buildMockOpportunity(), {
+        company,
+      });
+      const json = ctrl.toJson();
+      // Company should be a full object, not just {id, name}
+      expect(json.company.id).toBe("company-1");
+      expect(json.company.name).toBe("Test Company");
+    });
+
+    test("accepts activities via opts", () => {
+      const activities = [new ActivityController(buildMockCWActivity())];
+      const ctrl = new OpportunityController(buildMockOpportunity(), {
+        activities,
+      });
+      const json = ctrl.toJson();
+      expect(json.activities).toHaveLength(1);
+      expect(json.activities[0].cwActivityId).toBe(5001);
+    });
+
+    test("accepts customFields via opts", () => {
+      const customFields = [
+        {
+          id: 1,
+          caption: "Custom1",
+          type: "Text",
+          entryMethod: "EntryField",
+          numberOfDecimals: 0,
+          value: "test",
+        },
+      ];
+      const ctrl = new OpportunityController(buildMockOpportunity(), {
+        customFields,
+      });
+      const json = ctrl.toJson();
+      expect(json.customFields).toHaveLength(1);
+    });
+
+    test("has empty activities/customFields without opts", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.activities).toEqual([]);
+      expect(json.customFields).toEqual([]);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // mapCwToDb (static)
+  // -------------------------------------------------------------------
+  describe("mapCwToDb()", () => {
+    const cwOpportunity = {
+      id: 1001,
+      name: "CW Opp",
+      notes: "CW notes",
+      type: { id: 1, name: "New Business" },
+      stage: { id: 2, name: "Proposal" },
+      status: { id: 3, name: "Active" },
+      priority: { id: 4, name: "High" },
+      rating: null,
+      source: "Web",
+      campaign: null,
+      primarySalesRep: { id: 10, identifier: "jroberts", name: "John" },
+      secondarySalesRep: null,
+      company: { id: 123, identifier: "TestCo", name: "Test Co" },
+      contact: { id: 200, name: "Jane" },
+      site: { id: 300, name: "Main" },
+      customerPO: "PO-1",
+      totalSalesTax: 25.5,
+      location: { id: 400, name: "HQ" },
+      department: { id: 500, name: "Sales" },
+      expectedCloseDate: "2026-04-01T00:00:00Z",
+      pipelineChangeDate: "2026-02-15T00:00:00Z",
+      dateBecameLead: "2026-01-01T00:00:00Z",
+      closedDate: null,
+      closedFlag: false,
+      closedBy: null,
+      customFields: [],
+      _info: { lastUpdated: "2026-02-28T12:00:00Z" },
+    } as any;
+
+    test("maps name and notes", () => {
+      const result = OpportunityController.mapCwToDb(cwOpportunity);
+      expect(result.name).toBe("CW Opp");
+      expect(result.notes).toBe("CW notes");
+    });
+
+    test("maps type, stage, status references", () => {
+      const result = OpportunityController.mapCwToDb(cwOpportunity);
+      expect(result.typeName).toBe("New Business");
+      expect(result.typeCwId).toBe(1);
+      expect(result.stageName).toBe("Proposal");
+      expect(result.statusName).toBe("Active");
+    });
+
+    test("maps null references to null", () => {
+      const result = OpportunityController.mapCwToDb(cwOpportunity);
+      expect(result.ratingName).toBeNull();
+      expect(result.ratingCwId).toBeNull();
+      expect(result.campaignName).toBeNull();
+    });
+
+    test("maps sales rep fields", () => {
+      const result = OpportunityController.mapCwToDb(cwOpportunity);
+      expect(result.primarySalesRepName).toBe("John");
+      expect(result.primarySalesRepIdentifier).toBe("jroberts");
+      expect(result.secondarySalesRepName).toBeNull();
+    });
+
+    test("maps dates to Date objects", () => {
+      const result = OpportunityController.mapCwToDb(cwOpportunity);
+      expect(result.expectedCloseDate).toBeInstanceOf(Date);
+      expect(result.closedDate).toBeNull();
+    });
+
+    test("maps closedFlag", () => {
+      const result = OpportunityController.mapCwToDb(cwOpportunity);
+      expect(result.closedFlag).toBe(false);
+    });
+
+    test("maps cwLastUpdated from _info", () => {
+      const result = OpportunityController.mapCwToDb(cwOpportunity);
+      expect(result.cwLastUpdated).toBeInstanceOf(Date);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns core fields", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.id).toBe("opp-1");
+      expect(json.cwOpportunityId).toBe(1001);
+      expect(json.name).toBe("Test Opportunity");
+    });
+
+    test("formats type as reference object", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.type).toEqual({ id: 1, name: "New Business" });
+    });
+
+    test("formats stage as reference object", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.stage).toEqual({ id: 2, name: "Proposal" });
+    });
+
+    test("formats status as reference object", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.status).toEqual({ id: 3, name: "Active" });
+    });
+
+    test("formats primarySalesRep with identifier", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.primarySalesRep).toEqual({
+        id: 10,
+        identifier: "jroberts",
+        name: "John",
+      });
+    });
+
+    test("secondarySalesRep is null when not set", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.secondarySalesRep).toBeNull();
+    });
+
+    test("contact formats as reference object", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.contact).toEqual({ id: 200, name: "Jane Doe" });
+    });
+
+    test("company falls back to CW reference when no controller", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.company).toEqual({ id: 123, name: "Test Company" });
+    });
+
+    test("includes financial data", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.totalSalesTax).toBe(50.0);
+      expect(json.customerPO).toBe("PO-12345");
+    });
+
+    test("includes dates", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.expectedCloseDate).toBeInstanceOf(Date);
+      expect(json.closedFlag).toBe(false);
+    });
+
+    test("includes timestamps", () => {
+      const ctrl = new OpportunityController(buildMockOpportunity());
+      const json = ctrl.toJson();
+      expect(json.createdAt).toBeInstanceOf(Date);
+      expect(json.updatedAt).toBeInstanceOf(Date);
+    });
+  });
+});

tests/unit/controllers/UserController.test.ts

@@ -14,6 +14,14 @@ describe("UserController", () => {
       expect(ctrl.login).toBe("test@example.com");
       expect(ctrl.email).toBe("test@example.com");
       expect(ctrl.image).toBeNull();
+      expect(ctrl.cwIdentifier).toBeNull();
+    });
+
+    test("sets cwIdentifier when provided", () => {
+      const ctrl = new UserController(
+        buildMockUser({ cwIdentifier: "jroberts" }),
+      );
+      expect(ctrl.cwIdentifier).toBe("jroberts");
     });
 
     test("sets timestamps", () => {
@@ -61,10 +69,19 @@ describe("UserController", () => {
       expect(json.name).toBe("Test User");
       expect(json.login).toBeUndefined();
       expect(json.email).toBeUndefined();
+      expect(json.cwIdentifier).toBeUndefined();
       expect(json.roles).toBeUndefined();
       expect(json.permissions).toBeUndefined();
     });
 
+    test("cwIdentifier included in full JSON", () => {
+      const ctrl = new UserController(
+        buildMockUser({ cwIdentifier: "jroberts" }),
+      );
+      const json = ctrl.toJson();
+      expect(json.cwIdentifier).toBe("jroberts");
+    });
+
     test("roles is undefined when user has no roles", () => {
       const ctrl = new UserController(buildMockUser({ roles: [] }));
       const json = ctrl.toJson();