@clidey/dory 0.1.0 → 0.2.0

package/docs/usage/api-usage/api-inventory.mdx

@@ -1,213 +0,0 @@
----
-title: 'Inventory API'
-description: 'Endpoints to get, export, ignore, and favorite inventory items.'
----
-
-## Inventory API
-
-### 1. Purpose and Scope
-
-The **Inventory API** is a critical backend service component responsible for managing and exposing inventory-related data and operations within the Genie application. It acts as the interface between Shopify's data and internal business logic, providing aggregated, transformed, and actionable inventory information to both internal services and frontend clients.
-
-Within the system's architecture, this API handles inventory retrieval, adjustments, categorizations, and supports various inventory-focused workflows such as reporting, demand planning, and purchase order generation.
-
-### 2. Technical Overview
-
-This API is implemented primarily through the `ShopifyProductsService` and `InventoryService` classes, leveraging NestJS framework patterns including dependency injection (`@Injectable`) for modularity and testability.
-
-- **Main Integration Points:**
-  - **Shopify GraphQL and REST APIs:** Via the `ShopifyApiService`, it fetches real-time inventory and product information.
-  - **Database Views and Entities:** Uses PostgreSQL views such as `inventory_item` to consolidate product variant data with stock, sales metrics, supplier info, and location details.
-  - **Support Services:** Integrates with services for purchase order management, email notifications, and assets management.
-
-#### Architecture Diagram
-
-```mermaid
-flowchart TD
-    subgraph "API Services"
-      invSrv["InventoryService"]:::service
-      shopifyProdSrv["ShopifyProductsService"]:::service
-    end
-
-    subgraph "Shopify Integration"
-      shopifyApi["ShopifyApiService"]:::external
-    end
-
-    subgraph "Database"
-      invItemView[("inventory_item (Postgres View)"):::database
-      productVariant["product_variant"]:::database
-      productSupplier["product_supplier"]:::database
-      purchaseOrder["purchase_order"]:::database
-      location["location"]:::database
-      inventoryItemHistory["inventory_item_history"]:::database
-    end
-
-    subgraph "Other Internal Services"
-      poService["PurchaseOrdersService"]:::service
-      emailService["EmailService"]:::service
-      assetService["AssetsService"]:::service
-    end
-
-    shopifyProdSrv -->|"Calls"| shopifyApi
-    invSrv -->|"Reads/Writes"| invItemView
-    invSrv -->|"Reads"| productVariant
-    invSrv -->|"Reads"| productSupplier
-    invSrv -->|"Reads"| purchaseOrder
-    invSrv -->|"Reads"| location
-    invSrv -->|"Reads/Writes"| inventoryItemHistory
-    invSrv -->|"Uses"| poService
-    invSrv -->|"Uses"| emailService
-    invSrv -->|"Uses"| assetService
-
-    shopifyProdSrv -->|"Manages"| inventoryItemHistory
-
-    classDef service fill:#f9f,stroke:#333,stroke-width:2px,color:#000;
-    classDef database fill:#ccf,stroke:#333,stroke-width:2px,color:#000;
-    classDef external fill:#cfc,stroke:#333,stroke-width:2px,color:#000;
-```
-
-### 3. Core Concepts and Responsibilities
-
-- **Inventory Items and Product Variants:** The system treats each product variant from Shopify as an inventory item, tracking its SKU, quantity, sales, pricing, and metadata.
-
-- **Aggregated Inventory View:** Through the database `inventory_item` view, multiple data points are combined, including Shopify data, sales metrics, supplier info, and inventory at different locations.
-
-- **Grading and Status:** Inventory items are assigned grading levels (A, B, C) and statuses (e.g., NEW_PRODUCT, OUT_OF_STOCK, RUNNING_LOW) based on sales and stock metrics, driven by configurable team settings.
-
-- **Pagination and Chunking:** When dealing with large data sets like product categories or inventory items, the API breaks requests into manageable chunks (e.g., 250 or 300 item batches) for efficiency and API rate limit compliance.
-
-- **Shopify ID Conversion:** Shopify uses global IDs; the system maps between internal numeric IDs and Shopify global IDs prefixed by `gid://shopify/`.
-
-- **Exception Handling:** The API wraps Shopify and database calls within try/catch blocks, wrapping errors as `GenieException`s with context.
-
-- **Inventory Adjustments:** Supports batch adjustments of inventory quantities per location via Shopify's GraphQL mutation.
-
-- **Historical Data Management:** Periodically syncs history of inventory states and tracks events like last stockout to assist reporting and decision-making.
-
-- **Filtering and Searching:** Supports complex filter criteria and full-text search across SKU, product title, and variant title with search weighting.
-
-- **Ignore Flags:** Flags items or variants to be optionally excluded from certain operations via `ignore` flags.
-
-### 4. Code Structure
-
-- **Core Service:**
-  - `apps/api/src/shopify/services/shopify-products.service.ts` - Implements Shopify product-related APIs including fetching categories, products, inventory items, and inventory quantity adjustments.
-  
-- **Inventory Data Access:**
-  - `apps/api/src/pim/services/inventory.service.ts` - Handles deeper inventory item queries, filtering, sorting, history syncing, and exporting functions.
-
-- **Database Views & Migrations:**
-  - `apps/api/src/migrations/db/*.ts` - Migration files defining and updating `inventory_item` view, including complex SQL that aggregates multiple inventory and sales-related fields and implements grading and status logic.
-
-#### Example: Adjusting Inventory Quantities at a Location
-
-```ts
-async adjustLocationInventoryQuantities(
-  teamId: string,
-  itemsWithQuantities: AdjustInventoryQuantityItem[],
-  locationId: number
-) {
-  const auth = await this.shopify.getAuthOrThrow(teamId);
-
-  const shopifyLocationId = `gid://shopify/Location/${locationId}`;
-
-  const query = gql`
-    mutation inventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) {
-      inventoryAdjustQuantities(input: $input) {
-        userErrors {
-          field
-          message
-        }
-        inventoryAdjustmentGroup {
-          createdAt
-          reason
-          changes {
-            name
-            delta
-          }
-        }
-      }
-    }
-  `;
-
-  const result = await this.shopify.callApi(auth, async (sdk, session) =>
-    new sdk.clients.Graphql({ session }).request(query, {
-      input: {
-        reason: "correction",
-        name: "available",
-        changes: itemsWithQuantities.map(item => ({
-          delta: item.quantity,
-          inventoryItemId: `gid://shopify/InventoryItem/${item.id}`,
-          locationId: shopifyLocationId,
-        })),
-      },
-    })
-  );
-
-  if (result.errors?.message || result.data?.inventoryAdjustQuantities?.userErrors?.length) {
-    throw new GenieException(result.errors?.message ?? "Failed to adjust shopify location quantities", {
-      userErrors: result.data?.inventoryAdjustQuantities?.userErrors,
-    });
-  }
-
-  return result.data?.inventoryAdjustQuantities?.inventoryAdjustmentGroup;
-}
-```
-
-### 5. API and Interfaces
-
-- **`ShopifyProductsService`**
-  - `getProductCategory(teamId: string, productId: number): Promise<string | null>`
-      Retrieves the category name of a single product via Shopify GraphQL.
-
-  - `getProductCategories(teamId: string, productIds: number[]): Promise<Record<string, string>>`
-      Retrieves categories for multiple products by chunking requests.
-
-  - `getProducts(teamId: string, args?: { ids?: number[]; query?: string })`
-      Retrieves products matching optional IDs or query string, paginated.
-
-  - `getInventoryItems(teamId: string, ids: number[]): Promise<InventoryItem[]>`
-      Retrieves inventory items in batches via REST with pagination.
-
-  - `adjustLocationInventoryQuantities(teamId: string, itemsWithQuantities: AdjustInventoryQuantityItem[], locationId: number)`
-      Adjusts inventory quantities at a Shopify location.
-
-  - And others: fetching collections, variants count, creating products and variants in bulk.
-
-- **`InventoryService`**
-  - Core methods for filtering, sorting, search weighting, exporting inventory items.
-  - History syncing and retrieving historical inventory data.
-  - Methods for reports: stockout risk, asset values, dead stock, sales velocity.
-
-- **Error Handling:**
-  All public methods throw `GenieException` on failures with contextual data about the operation and parameters.
-
-### 6. Environment & Configuration
-
-- No explicit environment variables are detailed here.
-- The services depend on runtime configuration for Shopify API credentials supplied via `ShopifyApiService` and require PostgreSQL setup with the defined views.
-
-### 7. Testing, Monitoring, and Deployment
-
-- No explicit testing or deployment instructions are provided.
-- Logging is integrated using NestJS Logger at the service level.
-- Error handling uses `GenieException` for consistent exception wrapping.
-
-### 8. Troubleshooting & Known Issues
-
-- No documented known issues or troubleshooting procedures.
-
----
-
-This concludes the internal Inventory API documentation, designed to provide comprehensive understanding for developers maintaining or extending the inventory-related backend services.
-
----
-
-### References
-- [ShopifyProductsService Source](/apps/api/src/shopify/services/shopify-products.service.ts)
-- [InventoryService Source](/apps/api/src/pim/services/inventory.service.ts)
-- Database Views Migration Samples:
-  - /apps/api/src/migrations/db/1716211523354-shipments-inventory.ts
-  - /apps/api/src/migrations/db/1701944032657-inventory-grading-values.ts
-  - /apps/api/src/migrations/db/1723014724470-sales-at-risk.ts
-  - And others in /apps/api/src/migrations/db/

package/docs/usage/api-usage/api-products.mdx

@@ -1,249 +0,0 @@
----
-title: 'Product Management API'
-description: 'Endpoints related to products, product variants, bundles, and supplier mappings.'
----
-
-## Product Management API
-
-### 1. Purpose and Scope
-
-The Product Management API provides comprehensive functionality to manage products, product variants, bundles, collections, and supplier relationships within the Genie system. It enables syncing with Shopify, manipulation of product and variant metadata, managing supplier associations, and handling product bundles and collections.
-
-This API is primarily used by the backend services and web clients to ensure seamless integration between Shopify data stores and Genie’s internal data model. It addresses challenges such as:
-
-- Synchronizing product and inventory data from Shopify.
-- Managing supplier mappings and variant tags.
-- Handling bundles and collections relationships.
-- Updating stock level settings and manual adjustments.
-
-The system boundaries include interaction with Shopify services, internal repositories (Postgres via TypeORM), tracking services, and integrations with purchase order and workflow services.
-
-### 2. Technical Overview
-
-The Product Management API sits inside the `pim` (Product Information Management) domain. It integrates deeply with external Shopify services, internal sales order metrics, and team/user management for scoping data access.
-
-Key backend services involved:
-
-- **InsightsSyncService:** Syncs products, variants, collections, locations, and sales insights from Shopify.
-- **ProductsService:** Exposes CRUD operations, bulk updates, supplier mappings, variant tagging, and bundle management.
-- **IdeaProductsService:** Manages conceptual products before publishing to Shopify.
-
-Dependencies and integrations:
-
-- **ShopifyProductsService / ShopifyOrdersService:** Fetches product and order data from Shopify.
-- **TeamsService:** For team-specific operations and access control.
-- **InventorySalesMetricsService:** Updates sales and inventory metrics.
-- **SalesOrdersService / PurchaseOrdersService:** For syncing sales data and purchase-related enhancements.
-- **TrackingService:** Event tracking and analytics.
-
-Technologies:
-
-- Node.js with NestJS framework
-- TypeORM for database interactions
-- Various shared DTOs and validation via Zod
-
-Design patterns include:
-
-- Service-Oriented Architecture (SOA) with clearly defined domain services.
-- Event-driven tracking and monitoring.
-- Transactional database operations with upserts and batch processing.
-
----
-
-### Mermaid Diagram: Component Interaction
-
-```mermaid
-flowchart TD
-  subgraph Frontend
-    UI["Web UI / API Clients"]:::frontend
-  end
-
-  subgraph Backend
-    subgraph "Product Management Domain"
-      PC["ProductsController"]:::service
-      PS["ProductsService"]:::service
-      IS["InsightsSyncService"]:::service
-      IPS["IdeaProductsService"]:::service
-    end
-    subgraph "Shopify Integration"
-      SPS["ShopifyProductsService"]:::service
-      SOS["ShopifyOrdersService"]:::service
-      SAS["ShopifyApiService"]:::service
-    end
-    subgraph "Inventory & Sales"
-      SS["SalesOrdersService"]:::service
-      ISM["InventorySalesMetricsService"]:::service
-      PPOS["PurchaseOrdersService"]:::service
-    end
-    subgraph "User Management"
-      TS["TeamsService"]:::service
-    end
-    subgraph "Tracking & Analytics"
-      TRS["TrackingService"]:::service
-      WFS["WorkflowService"]:::service
-      SLS["SlackService"]:::service
-    end
-    DB["Postgres DB"]:::database
-  end
-
-  UI -->|REST API calls| PC
-  PC -->|calls| PS
-  PC -->|calls| IS
-  PC -->|calls| IPS
-
-  IS -->|uses| SPS
-  IS -->|uses| SOS
-  IS -->|uses| SAS
-  IS -->|uses| TS
-  IS -->|updates| SS
-  IS -->|updates| ISM
-
-  PS -->|reads/writes| DB
-  IPS -->|reads/writes| DB
-  SS -->|reads/writes| DB
-  PPOS -->|reads/writes| DB
-  TRS -->|logs events| DB
-  WFS -->|workflow orchestration| DB
-  SLS -->|notifications| DB
-
-  classDef service fill:#1f78b4,stroke:#155d8a,color:#fff,font-weight:bold
-  classDef database fill:#33a02c,stroke:#1b6d17,color:#fff,font-weight:bold
-  classDef frontend fill:#fb9a99,stroke:#c6696b,color:#000,font-weight:bold
-
-  click PC "apps/api/src/pim/controllers/products.controller.ts"
-  click PS "apps/api/src/pim/services/products.service.ts"
-  click IS "apps/api/src/pim/services/insights-sync.service.ts"
-  click IPS "apps/api/src/pim/services/idea-products.service.ts"
-```
-
----
-
-### 3. Core Concepts and Responsibilities
-
-- **Team Scoping:** All major APIs require a valid `teamId` context to operate. This scopes data to authorized entities.
-- **Shopify Sync:** `InsightsSyncService` manages syncing from Shopify, including products, variants, collections, and inventory levels.
-- **Manual Sync Control:** There is in-memory state tracking (`currentManualShopifyInsightsSyncingTeams`) to prevent concurrent manual sync requests per team.
-- **Product Variants & Tags:** Variants are managed separately with tagging, supplier data, and stock levels.
-- **Bundles:** Bundles are product variants of type `Bundle` that aggregate child components. Their relations can be updated via batch or individual operations.
-- **Supplier Management:** Products and variants can have multiple suppliers mapped with primary designation and variant-level data such as unit cost and SKU.
-- **Soft Deletes:** Products and variants missing from Shopify are soft deleted by setting `deletedAt` timestamp instead of hard delete.
-- **Metrics Updates:** Sales and order metrics are updated asynchronously to maintain inventory insights.
-
-**Ownership and Maintenance:**
-
-- Maintained by the Product Management team.
-- Logs via NestJS `Logger` for traceability.
-- Exceptions wrapped in custom `GenieException` class.
-
-**Non-Functional Requirements:**
-
-- Scalability with batch processing and chunking (e.g., product upload chunks of 1000).
-- Reliable sync by tracking with `DailySyncPerformanceTrackerService`.
-- Conflict prevention for manual syncs.
-- Security via team-based authorization (enforced at controller/service level).
-
----
-
-### 4. Code Structure
-
-- **Controllers:** Located under `apps/api/src/pim/controllers/`.
-  - `products.controller.ts` exposes HTTP endpoints for product CRUD, tagging, supplier management, bundles, collections.
-- **Services:** Located under `apps/api/src/pim/services/`.
-  - `insights-sync.service.ts`: Handles Shopify synchronization and data import.
-  - `products.service.ts`: Core business logic for product querying, updates, and supplier relationships.
-  - `idea-products.service.ts`: Manages idea products workflow and publishing.
-
-#### Key Service Methods from `InsightsSyncService`
-```ts
-public async syncDataForTeam({ teamId, sinceDays, trackingId, manual }) {
-  // Orchestrates syncing products, insights, and settings
-}
-
-public async importShopifyProducts(teamId, products) {
-  // Transforms and batch imports Shopify products and variants
-}
-
-private async markDeletedProductsAndVariants(teamId, shopifyProducts) {
-  // Marks missing products/variants as deleted
-}
-
-private async syncLocations(teamId) {
-  // Syncs Shopify locations and inventory levels
-}
-
-private async syncCollections(teamId) {
-  // Syncs Shopify collections and their associated products
-}
-
-private async syncInsights({ teamId, sinceDays, trackingId }) {
-  // Syncs sales order data and updates sales/order metrics
-}
-```
-
-#### Key Controller Endpoints in `ProductsController`
-- `POST /products` - Fetch products with filtering, sorting, and pagination.
-- `POST /products/sync-shopify` - Manually trigger Shopify sync for current user’s team.
-- `GET /products/shopify-tags`, `/shopify-vendors`, `/shopify-categories` - Retrieve aggregated Shopify metadata.
-- `POST /products/:productId/suppliers` - Set product suppliers.
-- `POST /products/update-suppliers-for-variants` - Update suppliers across multiple variants.
-- `PUT /products/:productId/variants/:variantId/landed-cost` - Update manual landed cost.
-
-For extensive method and DTO details, refer to the source files noted above.
-
----
-
-### 5. API and Interfaces
-
-The main Product API exposes REST endpoints that:
-
-- Allow fetching products with flexible filters.
-- Enable tagging of variants.
-- Permit management of product-supplier and variant-supplier mappings.
-- Support bundle relations management.
-- Provide manual sync entrypoints for Shopify data ingestion.
-
-APIs rely on Zod schemas for input validation to ensure data integrity.
-
-Failure modes mostly manifest as exceptions wrapped in `GenieException`, often with error contextual information such as `teamId` and entity IDs for traceability.
-
-Authorization is enforced via user context containing `teamId`, ensuring all actions are scoped.
-
----
-
-### 6. Environment & Configuration
-
-The services depend on integration credentials for Shopify managed by `ShopifyApiService`.
-
-No specific environment variables are described here.
-
-Development setups require a running PostgreSQL database with entities defined under the `pim/entities/` directory.
-
----
-
-### 7. Testing, Monitoring, and Deployment
-
-While not explicitly covered in the provided context, logging is integral with NestJS `Logger`. Exception capturing uses the custom `captureException` utility, potentially tied to Sentry or alternative error-tracking.
-
-Sync operations are tracked via `DailySyncPerformanceTrackerService` to monitor sync progress and performance.
-
----
-
-### 8. Troubleshooting & Known Issues
-
-- Manual Shopify syncs are guarded against concurrency per team. Attempting concurrent sync triggers a `ConflictException`.
-- Soft deletes retain historical data; missing items in Shopify are soft deleted via timestamp.
-- Batch operations process up to 1000 items at once to avoid DB overload.
-
-No documented known bugs or operational runbooks are included.
-
----
-
-### References
-- [InsightsSyncService implementation](apps/api/src/pim/services/insights-sync.service.ts)
-- [ProductsController implementation](apps/api/src/pim/controllers/products.controller.ts)
-- [ProductsService implementation](apps/api/src/pim/services/products.service.ts)
-- [IdeaProductsService implementation](apps/api/src/pim/services/idea-products.service.ts)
-
----
-
-This document serves as a comprehensive technical reference for contributors and maintainers working on the Product Management API layer.