asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
bb87db83424e2625e273fd5cf06cece37245b6da
medusa-store/www/apps/docs/content/references/services/classes/services.SwapService.mdx
Shahed Nasser bb87db8342 docs: prep for v2 documentation (#6710) 
This PR includes documentation that preps for v2 docs (but doesn't introduce new docs).

_Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._

## Changes

- Change Medusa version in base OAS used for v2.
- Fix to docblock generator related to not catching all path parameters.
- Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules.
- Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used.
- Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment.
- Upgraded docusaurus to v3.0.1
- Added new Vale rules to ensure correct spelling of Medusa Admin and module names.
- Added new components to the `docs-ui` package that will be used in future documentation changes.
2024-03-18 07:47:35 +00:00

284 lines
23 KiB
Plaintext
Raw Blame History

---
displayed_sidebar: servicesSidebar
---
import TypeList from "@site/src/components/TypeList"
# SwapService
Handles swaps
## constructor
### Parameters
<TypeList types={[{"name":"__namedParameters","type":"`InjectedProps`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="new SwapService"/>
___
## Properties
<TypeList types={[{"name":"manager_","type":"`EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionManager_","type":"`undefined` \\| `EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"__container__","type":"`any`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"Events","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"Events.CREATED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.created\"","expandable":false,"children":[]},{"name":"Events.RECEIVED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.received\"","expandable":false,"children":[]},{"name":"Events.SHIPMENT_CREATED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.shipment_created\"","expandable":false,"children":[]},{"name":"Events.PAYMENT_COMPLETED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.payment_completed\"","expandable":false,"children":[]},{"name":"Events.PAYMENT_CAPTURED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.payment_captured\"","expandable":false,"children":[]},{"name":"Events.PAYMENT_CAPTURE_FAILED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.payment_capture_failed\"","expandable":false,"children":[]},{"name":"Events.PROCESS_REFUND_FAILED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.process_refund_failed\"","expandable":false,"children":[]},{"name":"Events.REFUND_PROCESSED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.refund_processed\"","expandable":false,"children":[]},{"name":"Events.FULFILLMENT_CREATED","type":"`string`","description":"","optional":false,"defaultValue":"\"swap.fulfillment_created\"","expandable":false,"children":[]},{"name":"swapRepository_","type":"Repository&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cartService_","type":"[CartService](services.CartService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"eventBus_","type":"[EventBusService](services.EventBusService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"orderService_","type":"[OrderService](services.OrderService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"returnService_","type":"[ReturnService](services.ReturnService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"totalsService_","type":"[TotalsService](services.TotalsService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"lineItemService_","type":"[LineItemService](services.LineItemService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"fulfillmentService_","type":"[FulfillmentService](services.FulfillmentService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shippingOptionService_","type":"[ShippingOptionService](services.ShippingOptionService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"paymentProviderService_","type":"[PaymentProviderService](services.PaymentProviderService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"lineItemAdjustmentService_","type":"[LineItemAdjustmentService](services.LineItemAdjustmentService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customShippingOptionService_","type":"[CustomShippingOptionService](services.CustomShippingOptionService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"productVariantInventoryService_","type":"[ProductVariantInventoryService](services.ProductVariantInventoryService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"__configModule__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"__moduleDeclaration__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="SwapService"/>
___
## Accessors
### activeManager\_
#### Returns
<TypeList types={[{"name":"EntityManager","type":"`EntityManager`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="activeManager_"/>
___
## Methods
### withTransaction
#### Parameters
<TypeList types={[{"name":"transactionManager","type":"`EntityManager`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="withTransaction"/>
#### Returns
<TypeList types={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="withTransaction"/>
### shouldRetryTransaction\_
#### Parameters
<TypeList types={[{"name":"err","type":"`Record<string, unknown>` \\| `object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="shouldRetryTransaction_"/>
#### Returns
<TypeList types={[{"name":"boolean","type":"`boolean`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="shouldRetryTransaction_"/>
### atomicPhase\_
Wraps some work within a transactional block. If the service already has
a transaction manager attached this will be reused, otherwise a new
transaction manager is created.
#### Type Parameters
<TypeList types={[{"name":"TResult","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"TError","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
#### Parameters
<TypeList types={[{"name":"work","type":"(`transactionManager`: `EntityManager`) => Promise&#60;TResult&#62;","description":"the transactional work to be done","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationOrErrorHandler","type":"`IsolationLevel` \\| (`error`: TError) => Promise&#60;void \\| TResult&#62;","description":"the isolation level to be used for the work.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"maybeErrorHandlerOrDontFail","type":"(`error`: TError) => Promise&#60;void \\| TResult&#62;","description":"Potential error handler","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;TResult&#62;","optional":false,"defaultValue":"","description":"the result of the transactional work","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
### transformQueryForCart
Transform find config object for retrieval.
#### Parameters
<TypeList types={[{"name":"config","type":"Omit&#60;[FindConfig](../../medusa/interfaces/medusa.FindConfig.mdx)&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;, \"select\"&#62; & `object`","description":"parsed swap find config","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="transformQueryForCart"/>
#### Returns
<TypeList types={[{"name":"Omit","type":"Omit&#60;[FindConfig](../../medusa/interfaces/medusa.FindConfig.mdx)&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;, \"select\"&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]},{"name":"cartSelects","type":"`undefined` \\| keyof [Cart](../../entities/classes/entities.Cart.mdx)[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cartRelations","type":"`undefined` \\| `string`[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"select","type":"`string`[]","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="transformQueryForCart"/>
### retrieve
Retrieves a swap with the given id.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"the id of the swap to retrieve","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"Omit&#60;[FindConfig](../../medusa/interfaces/medusa.FindConfig.mdx)&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;, \"select\"&#62; & `object`","description":"the configuration to retrieve the swap","optional":false,"defaultValue":"{}","expandable":false,"children":[]}]} sectionTitle="retrieve"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the swap","expandable":false,"children":[]}]} sectionTitle="retrieve"/>
### retrieveByCartId
Retrieves a swap based on its associated cart id
#### Parameters
<TypeList types={[{"name":"cartId","type":"`string`","description":"the cart id that the swap's cart has","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"`undefined` \\| `string`[]","description":"the relations to retrieve swap","optional":false,"defaultValue":"[]","expandable":false,"children":[]}]} sectionTitle="retrieveByCartId"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the swap","expandable":false,"children":[]}]} sectionTitle="retrieveByCartId"/>
### list
List swaps.
#### Parameters
<TypeList types={[{"name":"selector","type":"[Selector](../../medusa/types/medusa.Selector.mdx)&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","description":"the query object for find","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"[FindConfig](../../medusa/interfaces/medusa.FindConfig.mdx)&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","description":"the configuration used to find the objects. contains relations, skip, and take.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="list"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)[]&#62;","optional":false,"defaultValue":"","description":"the result of the find operation","expandable":false,"children":[]}]} sectionTitle="list"/>
### listAndCount
List swaps.
#### Parameters
<TypeList types={[{"name":"selector","type":"[Selector](../../medusa/types/medusa.Selector.mdx)&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","description":"the query object for find","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"[FindConfig](../../medusa/interfaces/medusa.FindConfig.mdx)&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","description":"the configuration used to find the objects. contains relations, skip, and take.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="listAndCount"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[[Swap](../../entities/classes/entities.Swap.mdx)[], number]&#62;","optional":false,"defaultValue":"","description":"the result of the find operation","expandable":false,"children":[]}]} sectionTitle="listAndCount"/>
### create
Creates a swap from an order, with given return items, additional items
and an optional return shipping method.
#### Parameters
<TypeList types={[{"name":"order","type":"[Order](../../entities/classes/entities.Order.mdx)","description":"the order to base the swap off","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"returnItems","type":"[WithRequiredProperty](../../medusa/types/medusa.WithRequiredProperty.mdx)&#60;Partial&#60;[ReturnItem](../../entities/classes/entities.ReturnItem.mdx)&#62;, \"item_id\"&#62;[]","description":"the items to return in the swap","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"returnShipping.option_id","type":"`string`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"custom","type":"`object`","description":"contains relevant custom information. This object may\n include no\\_notification which will disable sending notification when creating\n swap. If set, it overrules the attribute inherited from the order","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"additionalItems","type":"Pick&#60;[LineItem](../../entities/classes/entities.LineItem.mdx), \"variant_id\" \\| \"quantity\"&#62;[]","description":"the items to send to the customer","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"returnShipping","type":"`object`","description":"an optional shipping method for returning the returnItems","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"returnShipping.price","type":"`number`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"custom.no_notification","type":"`boolean`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"custom.idempotency_key","type":"`string`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"custom.allow_backorder","type":"`boolean`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"custom.location_id","type":"`string`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="create"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the newly created swap","expandable":false,"children":[]}]} sectionTitle="create"/>
### processDifference
Process difference for the requested swap.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"id of a swap being processed","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="processDifference"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"processed swap","expandable":false,"children":[]}]} sectionTitle="processDifference"/>
### update
Update the swap record.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"id of a swap to update","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"update","type":"Partial&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","description":"new data","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="update"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"updated swap record","expandable":false,"children":[]}]} sectionTitle="update"/>
### createCart
Creates a cart from the given swap. The cart can be used to pay
for differences associated with the swap. The swap represented by the
swapId must belong to the order. Fails if there is already a cart on the
swap.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"the id of the swap to create the cart from","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customShippingOptions","type":"`object`[]","description":"the shipping options","optional":false,"defaultValue":"[]","expandable":false,"children":[]},{"name":"context","type":"`object`","description":"","optional":false,"defaultValue":"{}","expandable":false,"children":[]},{"name":"context.sales_channel_id","type":"`string`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="createCart"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the swap with its cart\\_id prop set to the id of the new cart.","expandable":false,"children":[]}]} sectionTitle="createCart"/>
### registerCartCompletion
Register a cart completion
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"The id of the swap","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="registerCartCompletion"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"swap related to the cart","expandable":false,"children":[]}]} sectionTitle="registerCartCompletion"/>
### cancel
Cancels a given swap if possible. A swap can only be canceled if all
related returns, fulfillments, and payments have been canceled. If a swap
is associated with a refund, it cannot be canceled.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"the id of the swap to cancel.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="cancel"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the canceled swap.","expandable":false,"children":[]}]} sectionTitle="cancel"/>
### createFulfillment
Fulfills the additional items associated with the swap. Will call the
fulfillment providers associated with the shipping methods.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"the id of the swap to fulfill,","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"`CreateShipmentConfig`","description":"optional configurations, includes optional metadata to attach to the shipment, and a no\\_notification flag.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="createFulfillment"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the updated swap with new status and fulfillments.","expandable":false,"children":[]}]} sectionTitle="createFulfillment"/>
### cancelFulfillment
Cancels a fulfillment (if related to a swap)
#### Parameters
<TypeList types={[{"name":"fulfillmentId","type":"`string`","description":"the ID of the fulfillment to cancel","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="cancelFulfillment"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"updated swap","expandable":false,"children":[]}]} sectionTitle="cancelFulfillment"/>
### createShipment
Marks a fulfillment as shipped and attaches tracking numbers.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"the id of the swap that has been shipped.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"fulfillmentId","type":"`string`","description":"the id of the specific fulfillment that has been shipped","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"`CreateShipmentConfig`","description":"optional configurations, includes optional metadata to attach to the shipment, and a noNotification flag.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"trackingLinks","type":"`object`[]","description":"the tracking numbers associated with the shipment","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="createShipment"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the updated swap with new fulfillments and status.","expandable":false,"children":[]}]} sectionTitle="createShipment"/>
### deleteMetadata
Dedicated method to delete metadata for a swap.
#### Parameters
<TypeList types={[{"name":"swapId","type":"`string`","description":"the order to delete metadata from.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"key","type":"`string`","description":"key for metadata field","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="deleteMetadata"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"resolves to the updated result.","expandable":false,"children":[]}]} sectionTitle="deleteMetadata"/>
### registerReceived
Registers the swap return items as received so that they cannot be used
as a part of other swaps/returns.
#### Parameters
<TypeList types={[{"name":"id","type":"`any`","description":"the id of the order with the swap.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="registerReceived"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;[Swap](../../entities/classes/entities.Swap.mdx)&#62;","optional":false,"defaultValue":"","description":"the resulting order","expandable":false,"children":[]}]} sectionTitle="registerReceived"/>
### areReturnItemsValid
#### Parameters
<TypeList types={[{"name":"returnItems","type":"[WithRequiredProperty](../../medusa/types/medusa.WithRequiredProperty.mdx)&#60;Partial&#60;[ReturnItem](../../entities/classes/entities.ReturnItem.mdx)&#62;, \"item_id\"&#62;[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="areReturnItemsValid"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;boolean&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="areReturnItemsValid"/>
Reference in New Issue View Git Blame Copy Permalink