@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/sales/docs/commands/RetrySyncJob.md

@@ -0,0 +1,39 @@
+# RetrySyncJob
+
+## Overview
+
+RetrySyncJob replays a previously failed, partial, or cancelled sync job using controlled idempotency. It creates a new running attempt while preserving traceability to the original job.
+
+## Business Rules
+
+- Only FAILED, PARTIALLY_SUCCEEDED, or CANCELLED jobs may be retried.
+- Retry must preserve the same channel and execution direction.
+- Retry logic must reuse idempotent channel-order identities instead of blindly duplicating records.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive retry request] --> B[Load sync job]
+    B --> C{Status retryable?}
+    C -->|No| D[Return INVALID_SYNC_JOB_STATUS]
+    C -->|Yes| E[Create new RUNNING retry attempt]
+    E --> F[Replay sync workload with idempotent keys]
+    F --> G[Return retried job]
+```
+
+## External Dependencies
+
+- [getSyncJob](../queries/GetSyncJob.md) - Load the original sync job and retry context.
+
+## Error Scenarios
+
+- **SYNC_JOB_NOT_FOUND**: Referenced sync job does not exist.
+- **INVALID_SYNC_JOB_STATUS**: Sync job is not in a retryable terminal state.
+
+## Test Cases
+
+- retries a failed sync job
+- retries a partially succeeded sync job
+- throws when sync job is still running
+- preserves idempotent identity during retry

package/src/modules/sales/docs/commands/SendSalesInvoice.md

@@ -0,0 +1,38 @@
+# SendSalesInvoice
+
+## Overview
+
+SendSalesInvoice records customer-facing delivery of an issued invoice. The command captures the metadata required by company policy to treat the invoice as sent.
+
+## Business Rules
+
+- Only ISSUED invoices may be marked as sent.
+- Required delivery metadata must be present before the status moves to SENT.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive send request] --> B[Load issued invoice]
+    B --> C{Status is ISSUED?}
+    C -->|No| D[Return INVALID_INVOICE_STATUS]
+    C -->|Yes| E[Validate delivery metadata]
+    E --> F[Set status to SENT]
+    F --> G[Return sent invoice]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_INVOICE_NOT_FOUND**: Referenced sales invoice does not exist.
+- **INVALID_INVOICE_STATUS**: Only ISSUED invoices may be sent.
+- **DELIVERY_METADATA_REQUIRED**: Required invoice delivery metadata is missing.
+
+## Test Cases
+
+- marks an issued invoice as sent when delivery metadata is present
+- throws when invoice is not issued
+- throws when delivery metadata is incomplete

package/src/modules/sales/docs/commands/StartSyncJob.md

@@ -0,0 +1,39 @@
+# StartSyncJob
+
+## Overview
+
+StartSyncJob creates and starts a sync execution for one channel and one direction. It is the operational record used to track import, export, replay, or recovery work against the external channel integration.
+
+## Business Rules
+
+- Referenced channel must exist and be eligible for sync execution.
+- Direction and execution context are required.
+- New sync jobs start in RUNNING status with counts initialized to zero.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive start request] --> B[Validate channel and direction]
+    B --> C[Create SyncJob in RUNNING status]
+    C --> D[Begin processing channel payloads or outbound events]
+    D --> E[Persist counts and terminal outcome]
+    E --> F[Return sync job summary]
+```
+
+## External Dependencies
+
+- [getChannel](../queries/GetChannel.md) - Validate the target channel and company scope.
+
+## Error Scenarios
+
+- **CHANNEL_NOT_FOUND**: Referenced channel does not exist.
+- **CHANNEL_NOT_SYNCABLE**: Channel is inactive or blocked for new sync execution.
+- **SYNC_DIRECTION_REQUIRED**: Sync direction is required.
+
+## Test Cases
+
+- starts a running sync job for an active channel
+- initializes sync counts to zero
+- throws when channel is inactive for new sync execution
+- throws when direction is missing

package/src/modules/sales/docs/commands/SubmitSalesOrder.md

@@ -0,0 +1,43 @@
+# SubmitSalesOrder
+
+## Overview
+
+SubmitSalesOrder moves a draft sales order into SUBMITTED status so it can be reviewed and confirmed. Submission validates that the commercial document is complete enough for approval and downstream execution checks.
+
+## Business Rules
+
+- Only DRAFT orders may be submitted.
+- The order must contain at least one line.
+- If any line requires physical fulfillment, a shipping address snapshot must be present.
+- Assigned payment term and customer context must remain valid at submission time.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive submit request] --> B[Load draft order]
+    B --> C[Validate lines, addresses, and customer context]
+    C --> D{Validation passed?}
+    D -->|No| E[Return validation error]
+    D -->|Yes| F[Set status to SUBMITTED]
+    F --> G[Return submitted order]
+```
+
+## External Dependencies
+
+- [business-partner::GetDefaultPartnerAddress](../../../business-partner/docs/queries/GetDefaultPartnerAddress.md) - Resolve or validate shipping and billing address context.
+- [getSalesPaymentTerm](../queries/GetSalesPaymentTerm.md) - Revalidate active payment-term assignment.
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_ORDER_STATUS**: Only DRAFT orders may be submitted.
+- **EMPTY_ORDER_NOT_ALLOWED**: Orders without lines cannot be submitted.
+- **SHIPPING_ADDRESS_REQUIRED**: A shipping address is required for shippable lines.
+
+## Test Cases
+
+- submits a complete draft order
+- throws when the order is not in DRAFT status
+- throws when the order has no lines
+- throws when shipping address is missing for physical fulfillment lines

package/src/modules/sales/docs/commands/UpdateChannel.md

@@ -0,0 +1,43 @@
+# UpdateChannel
+
+## Overview
+
+UpdateChannel revises mutable Channel fields while the record remains editable under policy.
+
+## Business Rules
+
+- The Channel must exist before it can be updated.
+- The Channel must remain in an editable lifecycle state.
+- Channel type is required.
+- Channel name must be unique enough to avoid operational ambiguity within the company.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load Channel]
+    B --> C{Record editable?}
+    C -->|No| D[Return CHANNEL_NOT_EDITABLE]
+    C -->|Yes| E[Validate changed fields]
+    E --> F[Persist updates]
+    F --> G[Return updated Channel]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the channel.
+
+## Error Scenarios
+
+- **CHANNEL_NOT_FOUND**: Referenced Channel does not exist.
+- **CHANNEL_NOT_EDITABLE**: Channel is not in an editable lifecycle state.
+- **INVALID_CHANNEL_TYPE**: Channel type is missing or unsupported.
+- **DUPLICATE_CHANNEL_NAME**: A conflicting channel name already exists.
+
+## Test Cases
+
+- updates mutable Channel fields
+- throws when Channel does not exist
+- throws when Channel is not editable
+- throws when the resulting channel type is empty
+- throws when the updated channel name conflicts within the company

package/src/modules/sales/docs/commands/UpdateListing.md

@@ -0,0 +1,38 @@
+# UpdateListing
+
+## Overview
+
+UpdateListing revises listing metadata such as identifiers, assortment settings, or channel-specific operational attributes before or after activation when policy permits.
+
+## Business Rules
+
+- Retired listings cannot be updated through this command.
+- Updated external identifiers must remain unique within the channel context.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load listing]
+    B --> C{Listing retired?}
+    C -->|Yes| D[Return LISTING_NOT_EDITABLE]
+    C -->|No| E[Validate changed metadata]
+    E --> F[Persist listing changes]
+    F --> G[Return updated listing]
+```
+
+## External Dependencies
+
+- [getListing](../queries/GetListing.md) - Load the current listing and channel context.
+
+## Error Scenarios
+
+- **LISTING_NOT_FOUND**: Referenced listing does not exist.
+- **LISTING_NOT_EDITABLE**: Retired listings cannot be updated.
+- **DUPLICATE_EXTERNAL_IDENTIFIER**: External identifier conflicts with another listing on the same channel.
+
+## Test Cases
+
+- updates listing metadata while listing remains active or paused
+- throws when listing is retired
+- throws when updated external identifier conflicts with another listing

package/src/modules/sales/docs/commands/UpdateSalesCreditNote.md

@@ -0,0 +1,38 @@
+# UpdateSalesCreditNote
+
+## Overview
+
+UpdateSalesCreditNote revises draft credit-note content before issue. It supports correction of quantities, amounts, references, and reason codes while the document remains draft.
+
+## Business Rules
+
+- Only DRAFT credit notes may be updated directly.
+- Updated correction lines must still reference valid issued invoice lines.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load credit note]
+    B --> C{Status is DRAFT?}
+    C -->|No| D[Return CREDIT_NOTE_NOT_EDITABLE]
+    C -->|Yes| E[Validate updated correction content]
+    E --> F[Persist updates]
+    F --> G[Return updated credit note]
+```
+
+## External Dependencies
+
+- [getSalesCreditNote](../queries/GetSalesCreditNote.md) - Load current credit-note state before applying changes.
+
+## Error Scenarios
+
+- **SALES_CREDIT_NOTE_NOT_FOUND**: Referenced sales credit note does not exist.
+- **CREDIT_NOTE_NOT_EDITABLE**: Only DRAFT credit notes may be updated.
+- **INVALID_CREDIT_NOTE_LINE**: Updated correction content is invalid.
+
+## Test Cases
+
+- updates draft credit-note lines
+- throws when updating an issued credit note
+- throws when correction content is invalid

package/src/modules/sales/docs/commands/UpdateSalesInvoice.md

@@ -0,0 +1,38 @@
+# UpdateSalesInvoice
+
+## Overview
+
+UpdateSalesInvoice revises mutable draft invoice fields before issue. It supports correction of line composition, customer-facing references, and draft billing metadata.
+
+## Business Rules
+
+- Only DRAFT invoices may be updated directly.
+- Updated invoice lines must still satisfy quantity and reference validity rules.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load invoice]
+    B --> C{Status is DRAFT?}
+    C -->|No| D[Return INVOICE_NOT_EDITABLE]
+    C -->|Yes| E[Validate changed fields and lines]
+    E --> F[Persist updates]
+    F --> G[Return updated invoice]
+```
+
+## External Dependencies
+
+- [getSalesInvoice](../queries/GetSalesInvoice.md) - Load current invoice state before applying changes.
+
+## Error Scenarios
+
+- **SALES_INVOICE_NOT_FOUND**: Referenced sales invoice does not exist.
+- **INVOICE_NOT_EDITABLE**: Only DRAFT invoices may be updated.
+- **INVALID_INVOICE_LINE**: Updated invoice line content is invalid.
+
+## Test Cases
+
+- updates draft invoice metadata
+- throws when updating an issued invoice
+- throws when updated line content is invalid

package/src/modules/sales/docs/commands/UpdateSalesOrder.md

@@ -0,0 +1,45 @@
+# UpdateSalesOrder
+
+## Overview
+
+UpdateSalesOrder revises mutable sales-order fields while the order is still editable. It supports draft correction of addresses, payment terms, commercial notes, and line composition before the order is submitted or revised through a future explicit workflow.
+
+## Business Rules
+
+- Only DRAFT orders may be updated directly by this command.
+- Updated order lines must still satisfy item, quantity, and pricing validity rules.
+- The order must retain at least one line after the update completes.
+- Commercial snapshots frozen at confirmation cannot be changed through this command.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load sales order]
+    B --> C{Status is DRAFT?}
+    C -->|No| D[Return ORDER_NOT_EDITABLE]
+    C -->|Yes| E[Validate updated fields and lines]
+    E --> F[Persist order and line changes]
+    F --> G[Return updated sales order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Revalidate customer changes when customer context is edited.
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Revalidate changed item references on lines.
+- [getSalesPaymentTerm](../queries/GetSalesPaymentTerm.md) - Revalidate changed payment-term assignment.
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **ORDER_NOT_EDITABLE**: Only DRAFT orders may be updated directly.
+- **INVALID_ORDER_LINE**: Updated line content is incomplete or invalid.
+- **EMPTY_ORDER_NOT_ALLOWED**: The order would have no remaining lines after the update.
+
+## Test Cases
+
+- updates mutable draft order header fields
+- updates draft order lines and preserves line integrity
+- throws when the order does not exist
+- throws when updating a non-draft order
+- throws when the update would remove all lines

package/src/modules/sales/docs/commands/UpdateSalesPaymentTerm.md

@@ -0,0 +1,41 @@
+# UpdateSalesPaymentTerm
+
+## Overview
+
+UpdateSalesPaymentTerm revises mutable SalesPaymentTerm fields while the record remains editable under policy.
+
+## Business Rules
+
+- The SalesPaymentTerm must exist before it can be updated.
+- The SalesPaymentTerm must remain in an editable lifecycle state.
+- At least one schedule line is required.
+- Percentage-based schedules must total 100 percent.
+- Discount cutoff must not fall after the final due date.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load SalesPaymentTerm]
+    B --> C{Record editable?}
+    C -->|No| D[Return SALESPAYMENTTERM_NOT_EDITABLE]
+    C -->|Yes| E[Validate changed fields]
+    E --> F[Persist updates]
+    F --> G[Return updated SalesPaymentTerm]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the term.
+
+## Error Scenarios
+
+- **SALESPAYMENTTERM_NOT_FOUND**: Referenced SalesPaymentTerm does not exist.
+- **SALESPAYMENTTERM_NOT_EDITABLE**: SalesPaymentTerm is not in an editable lifecycle state.
+- **INVALID_PAYMENT_SCHEDULE**: Schedule lines do not satisfy payment-term rules.
+
+## Test Cases
+
+- updates mutable SalesPaymentTerm fields
+- throws when SalesPaymentTerm does not exist
+- throws when SalesPaymentTerm is not editable

package/src/modules/sales/docs/commands/UpdateSalesPriceList.md

@@ -0,0 +1,40 @@
+# UpdateSalesPriceList
+
+## Overview
+
+UpdateSalesPriceList revises mutable SalesPriceList fields while the record remains editable under policy.
+
+## Business Rules
+
+- The SalesPriceList must exist before it can be updated.
+- The SalesPriceList must remain in an editable lifecycle state.
+- Company must be ACTIVE or otherwise eligible for commercial configuration.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load SalesPriceList]
+    B --> C{Record editable?}
+    C -->|No| D[Return SALESPRICELIST_NOT_EDITABLE]
+    C -->|Yes| E[Validate changed fields]
+    E --> F[Persist updates]
+    F --> G[Return updated SalesPriceList]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the price list.
+
+## Error Scenarios
+
+- **SALESPRICELIST_NOT_FOUND**: Referenced SalesPriceList does not exist.
+- **SALESPRICELIST_NOT_EDITABLE**: SalesPriceList is not in an editable lifecycle state.
+- **COMPANY_NOT_FOUND**: Referenced company does not exist.
+
+## Test Cases
+
+- updates mutable SalesPriceList fields
+- throws when SalesPriceList does not exist
+- throws when SalesPriceList is not editable
+- throws when the company backing the price list does not exist

package/src/modules/sales/docs/commands/UpdateSalesPriceRule.md

@@ -0,0 +1,49 @@
+# UpdateSalesPriceRule
+
+## Overview
+
+UpdateSalesPriceRule revises mutable SalesPriceRule fields while the record remains editable under policy.
+
+## Business Rules
+
+- The SalesPriceRule must exist before it can be updated.
+- The SalesPriceRule must remain in an editable lifecycle state.
+- Unit price must be positive.
+- Effective end date cannot precede start date.
+- Minimum quantity cannot be negative.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load SalesPriceRule]
+    B --> C{Record editable?}
+    C -->|No| D[Return SALESPRICERULE_NOT_EDITABLE]
+    C -->|Yes| E[Validate changed fields]
+    E --> F[Persist updates]
+    F --> G[Return updated SalesPriceRule]
+```
+
+## External Dependencies
+
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate the referenced sellable item.
+- [primitives::GetCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validate currency assignment.
+- [primitives::GetUnit](../../../primitives/docs/queries/GetUnit.md) - Validate sales UoM assignment.
+- [getSalesPriceList](../queries/GetSalesPriceList.md) - Validate parent price-list scope.
+
+## Error Scenarios
+
+- **SALESPRICERULE_NOT_FOUND**: Referenced SalesPriceRule does not exist.
+- **SALESPRICERULE_NOT_EDITABLE**: SalesPriceRule is not in an editable lifecycle state.
+- **PRICE_LIST_NOT_FOUND**: Parent sales price list does not exist.
+- **INVALID_UNIT_PRICE**: Unit price must be greater than zero.
+- **INVALID_EFFECTIVE_RANGE**: Effective end date precedes start date.
+
+## Test Cases
+
+- updates mutable SalesPriceRule fields
+- throws when SalesPriceRule does not exist
+- throws when SalesPriceRule is not editable
+- throws when the parent price list does not exist
+- throws on invalid unit price
+- throws on invalid effective date range

package/src/modules/sales/docs/commands/UpdateShipment.md

@@ -0,0 +1,38 @@
+# UpdateShipment
+
+## Overview
+
+UpdateShipment revises draft shipment details before posting. It supports correction of shipment lines, addresses, ship dates, carrier metadata, or tracking references.
+
+## Business Rules
+
+- Only DRAFT shipments may be updated directly.
+- Updated shipment quantities must remain within remaining shippable order quantities.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B[Load shipment]
+    B --> C{Status is DRAFT?}
+    C -->|No| D[Return SHIPMENT_NOT_EDITABLE]
+    C -->|Yes| E[Validate updated shipment details]
+    E --> F[Persist shipment changes]
+    F --> G[Return updated shipment]
+```
+
+## External Dependencies
+
+- [getShipment](../queries/GetShipment.md) - Load current shipment state before applying changes.
+
+## Error Scenarios
+
+- **SHIPMENT_NOT_FOUND**: Referenced shipment does not exist.
+- **SHIPMENT_NOT_EDITABLE**: Only DRAFT shipments may be updated.
+- **INVALID_SHIPMENT_LINE**: Updated shipment line content is invalid.
+
+## Test Cases
+
+- updates draft shipment metadata
+- throws when updating a posted shipment
+- throws when updated quantity exceeds remaining order quantity

package/src/modules/sales/docs/commands/bin/rm.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+

package/src/modules/sales/docs/commands/opt/homebrew/bin/codex.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+