From ef39985d66ee16ff00fb3734dccee09e01ec2660 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 8 Apr 2024 11:17:38 +0300 Subject: [PATCH] chore: Added TSDocs for the Fulfillment Module (#6912) Added TSDocs for the Fulfillment Module --- packages/types/src/common/rule.ts | 3 + .../types/src/fulfillment/common/address.ts | 66 + .../fulfillment/common/fulfillment-item.ts | 50 + .../fulfillment/common/fulfillment-label.ts | 38 + .../common/fulfillment-provider.ts | 30 + .../src/fulfillment/common/fulfillment-set.ts | 52 + .../src/fulfillment/common/fulfillment.ts | 117 + .../types/src/fulfillment/common/geo-zone.ts | 70 +- .../src/fulfillment/common/service-zone.ts | 64 + .../common/shipping-option-rule.ts | 66 +- .../common/shipping-option-type.ts | 56 + .../src/fulfillment/common/shipping-option.ts | 150 +- .../fulfillment/common/shipping-profile.ts | 52 + .../mutations/fulfillment-address.ts | 50 + .../fulfillment/mutations/fulfillment-item.ts | 30 + .../mutations/fulfillment-label.ts | 18 + .../fulfillment/mutations/fulfillment-set.ts | 44 +- .../src/fulfillment/mutations/fulfillment.ts | 83 + .../src/fulfillment/mutations/geo-zone.ts | 138 ++ .../src/fulfillment/mutations/service-zone.ts | 38 +- .../mutations/shipping-option-rule.ts | 22 + .../mutations/shipping-option-type.ts | 24 + .../fulfillment/mutations/shipping-option.ts | 97 +- .../fulfillment/mutations/shipping-profile.ts | 17 + packages/types/src/fulfillment/service.ts | 2204 +++++++++++++++-- 25 files changed, 3352 insertions(+), 227 deletions(-) diff --git a/packages/types/src/common/rule.ts b/packages/types/src/common/rule.ts index b520abca12..4427e61495 100644 --- a/packages/types/src/common/rule.ts +++ b/packages/types/src/common/rule.ts @@ -1,3 +1,6 @@ +/** + * The accepted values for the shipping rule option's operator. + */ export type RuleOperatorType = | "in" | "eq" diff --git a/packages/types/src/fulfillment/common/address.ts b/packages/types/src/fulfillment/common/address.ts index 9ca639e5c2..649555b5eb 100644 --- a/packages/types/src/fulfillment/common/address.ts +++ b/packages/types/src/fulfillment/common/address.ts @@ -1,18 +1,84 @@ +/** + * The fulfillment address details. + */ export interface FulfillmentAddressDTO { + /** + * The ID of the address. + */ id: string + + /** + * The associated fulfillment's ID. + */ fulfillment_id: string | null + + /** + * The company of the address. + */ company: string | null + + /** + * The first name of the address. + */ first_name: string | null + + /** + * The last name of the address. + */ last_name: string | null + + /** + * The first line of the address. + */ address_1: string | null + + /** + * The second line of the address. + */ address_2: string | null + + /** + * The city of the address. + */ city: string | null + + /** + * The ISO 2 character country code of the address. + */ country_code: string | null + + /** + * The province of the address. + */ province: string | null + + /** + * The postal code of the address. + */ postal_code: string | null + + /** + * The phone of the address. + */ phone: string | null + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The creation date of the address. + */ created_at: Date + + /** + * The update date of the address. + */ updated_at: Date + + /** + * The deletion date of the address. + */ deleted_at: Date | null } diff --git a/packages/types/src/fulfillment/common/fulfillment-item.ts b/packages/types/src/fulfillment/common/fulfillment-item.ts index 1c0d5a5114..f3ae8bfdce 100644 --- a/packages/types/src/fulfillment/common/fulfillment-item.ts +++ b/packages/types/src/fulfillment/common/fulfillment-item.ts @@ -1,16 +1,66 @@ import { FulfillmentDTO } from "./fulfillment" +/** + * The fulfillment item details. + */ export interface FulfillmentItemDTO { + /** + * The ID of the fulfillment item. + */ id: string + + /** + * The title of the fulfillment item. + */ title: string + + /** + * The quantity of the fulfillment item. + */ quantity: number + + /** + * The sku of the fulfillment item. + */ sku: string + + /** + * The barcode of the fulfillment item. + */ barcode: string + + /** + * The associated line item's ID. + */ line_item_id: string | null + + /** + * The associated inventory item's ID. + */ inventory_item_id: string | null + + /** + * The associated fulfillment's ID. + */ fulfillment_id: string + + /** + * The associated fulfillment. + */ fulfillment: FulfillmentDTO + + /** + * The creation date of the fulfillment item. + */ created_at: Date + + /** + * The update date of the fulfillment item. + */ updated_at: Date + + /** + * The deletion date of the fulfillment item. + */ deleted_at: Date | null } diff --git a/packages/types/src/fulfillment/common/fulfillment-label.ts b/packages/types/src/fulfillment/common/fulfillment-label.ts index 914f7be2e6..0dbb9fe0e3 100644 --- a/packages/types/src/fulfillment/common/fulfillment-label.ts +++ b/packages/types/src/fulfillment/common/fulfillment-label.ts @@ -1,13 +1,51 @@ import { FulfillmentDTO } from "./fulfillment" +/** + * The fulfillment label details. + */ export interface FulfillmentLabelDTO { + /** + * The ID of the fulfillment label. + */ id: string + + /** + * The tracking number of the fulfillment label. + */ tracking_number: string + + /** + * The tracking URL of the fulfillment label. + */ tracking_url: string + + /** + * The label's URL. + */ label_url: string + + /** + * The associated fulfillment's ID. + */ fulfillment_id: string + + /** + * The associated fulfillment. + */ fulfillment: FulfillmentDTO + + /** + * The creation date of the fulfillment label. + */ created_at: Date + + /** + * The update date of the fulfillment label. + */ updated_at: Date + + /** + * The deletion date of the fulfillment label. + */ deleted_at: Date | null } diff --git a/packages/types/src/fulfillment/common/fulfillment-provider.ts b/packages/types/src/fulfillment/common/fulfillment-provider.ts index e62b2f10bc..34ba71f6c9 100644 --- a/packages/types/src/fulfillment/common/fulfillment-provider.ts +++ b/packages/types/src/fulfillment/common/fulfillment-provider.ts @@ -1,11 +1,41 @@ import { ShippingOptionDTO } from "./shipping-option" +/** + * The fulfillment provider details. + */ export interface FulfillmentProviderDTO { + /** + * The ID of the fulfillment provider. + */ id: string + + /** + * The name of the fulfillment provider. + */ name: string + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The shipping options associated with the fulfillment provider. + */ shipping_options: ShippingOptionDTO[] + + /** + * The creation date of the fulfillment provider. + */ created_at: Date + + /** + * The update date of the fulfillment provider. + */ updated_at: Date + + /** + * The deletion date of the fulfillment provider. + */ deleted_at: Date | null } diff --git a/packages/types/src/fulfillment/common/fulfillment-set.ts b/packages/types/src/fulfillment/common/fulfillment-set.ts index 0858768f55..4b0a0e8f9a 100644 --- a/packages/types/src/fulfillment/common/fulfillment-set.ts +++ b/packages/types/src/fulfillment/common/fulfillment-set.ts @@ -1,21 +1,73 @@ import { FilterableServiceZoneProps, ServiceZoneDTO } from "./service-zone" import { BaseFilterable } from "../../dal" +/** + * The fulfillment set details. + */ export interface FulfillmentSetDTO { + /** + * The ID of the fulfillment set. + */ id: string + + /** + * The name of the fulfillment set. + */ name: string + + /** + * The type of the fulfillment set. + */ type: string + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The service zones associated with the fulfillment set. + */ service_zones: ServiceZoneDTO[] + + /** + * The creation date of the fulfillment set. + */ created_at: Date + + /** + * The update date of the fulfillment set. + */ updated_at: Date + + /** + * The deletion date of the fulfillment set. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved fulfillment sets. + */ export interface FilterableFulfillmentSetProps extends BaseFilterable { + /** + * The IDs to filter the fulfillment sets by. + */ id?: string | string[] + + /** + * Filter the fulfillment sets by their name. + */ name?: string | string[] + + /** + * Filter the fulfillment sets by their type. + */ type?: string | string[] + + /** + * The filters to apply on the retrieved service zones. + */ service_zones?: FilterableServiceZoneProps } diff --git a/packages/types/src/fulfillment/common/fulfillment.ts b/packages/types/src/fulfillment/common/fulfillment.ts index abab0af6ad..81099c84ef 100644 --- a/packages/types/src/fulfillment/common/fulfillment.ts +++ b/packages/types/src/fulfillment/common/fulfillment.ts @@ -5,37 +5,154 @@ import { FulfillmentItemDTO } from "./fulfillment-item" import { FulfillmentLabelDTO } from "./fulfillment-label" import { BaseFilterable, OperatorMap } from "../../dal" +/** + * The fulfillment details. + */ export interface FulfillmentDTO { + /** + * The ID of the fulfillment. + */ id: string + + /** + * The associated location's ID. + */ location_id: string + + /** + * The date the fulfillment was packed. + */ packed_at: Date | null + + /** + * The date the fulfillment was shipped. + */ shipped_at: Date | null + + /** + * The date the fulfillment was delivered. + */ delivered_at: Date | null + + /** + * The date the fulfillment was canceled. + */ canceled_at: Date | null + + /** + * The data necessary for the fulfillment provider to process + * the fulfillment. + */ data: Record | null + + /** + * The associated fulfillment provider's ID. + */ provider_id: string + + /** + * The associated shipping option's ID. + */ shipping_option_id: string | null + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The associated shipping option. + */ shipping_option: ShippingOptionDTO | null + + /** + * The associated fulfillment provider. + */ provider: FulfillmentProviderDTO + + /** + * The associated fulfillment address used for delivery. + */ delivery_address: FulfillmentAddressDTO + + /** + * The items of the fulfillment. + */ items: FulfillmentItemDTO[] + + /** + * The labels of the fulfillment. + */ labels: FulfillmentLabelDTO[] + + /** + * The creation date of the fulfillment. + */ created_at: Date + + /** + * The update date of the fulfillment. + */ updated_at: Date + + /** + * The deletion date of the fulfillment. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved fulfillments. + */ export interface FilterableFulfillmentProps extends BaseFilterable { + /** + * The IDs to filter the fulfillments by. + */ id?: string | string[] | OperatorMap + + /** + * Filter the fulfillments by the ID of their associated location. + */ location_id?: string | string[] | OperatorMap + + /** + * Filter the fulfillments by their packing date. + */ packed_at?: Date | OperatorMap + + /** + * Filter the fulfillments by their shipping date. + */ shipped_at?: Date | OperatorMap + + /** + * Filter the fulfillments by their delivery date. + */ delivered_at?: Date | OperatorMap + + /** + * Filter the fulfillments by their cancelation date. + */ canceled_at?: Date | OperatorMap + + /** + * Filter the fulfillments by the ID of their associated fulfillment provider. + */ provider_id?: string | string[] | OperatorMap + + /** + * Filter the fulfillments by the ID of their associated shipping option. + */ shipping_option_id?: string | null + + /** + * Filter the fulfillments by their creation date. + */ created_at?: Date | OperatorMap + + /** + * Filter the fulfillments by their update date. + */ updated_at?: Date | OperatorMap } diff --git a/packages/types/src/fulfillment/common/geo-zone.ts b/packages/types/src/fulfillment/common/geo-zone.ts index 4ee450e520..4b0553625f 100644 --- a/packages/types/src/fulfillment/common/geo-zone.ts +++ b/packages/types/src/fulfillment/common/geo-zone.ts @@ -1,26 +1,94 @@ import { BaseFilterable } from "../../dal" +/** + * The type of the geo zone. + */ export type GeoZoneType = "country" | "province" | "city" | "zip" +/** + * The geo zone details. + */ export interface GeoZoneDTO { + /** + * The ID of the geo zone. + */ id: string + + /** + * The type of the geo zone. + */ type: GeoZoneType + + /** + * The country code of the geo zone. + */ country_code: string + + /** + * The province code of the geo zone. + */ province_code: string | null + + /** + * The city of the geo zone. + */ city: string | null + + /** + * The postal expression of the geo zone. + */ postal_expression: Record | null + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The creation date of the geo zone. + */ created_at: Date + + /** + * The update date of the geo zone. + */ updated_at: Date + + /** + * The deletion date of the geo zone. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved geo zones. + */ export interface FilterableGeoZoneProps extends BaseFilterable { + /** + * The IDs to filter the geo zones by. + */ id?: string | string[] + + /** + * Filter the geo zones by their type. + */ type?: GeoZoneType | GeoZoneType[] + + /** + * Filter the geo zones by their country code. + */ country_code?: string | string[] + + /** + * Filter the geo zones by their province code. + */ province_code?: string | string[] + + /** + * Filter the geo zones by their city. + */ city?: string | string[] - // postal_expression?: Record | Record[] // TODO: Add support for postal_expression filtering + + // TODO add support for postal_expression filtering } diff --git a/packages/types/src/fulfillment/common/service-zone.ts b/packages/types/src/fulfillment/common/service-zone.ts index be9ba5a523..31483e7f88 100644 --- a/packages/types/src/fulfillment/common/service-zone.ts +++ b/packages/types/src/fulfillment/common/service-zone.ts @@ -6,23 +6,87 @@ import { FilterableGeoZoneProps, GeoZoneDTO } from "./geo-zone" import { ShippingOptionDTO } from "./shipping-option" import { BaseFilterable, OperatorMap } from "../../dal" +/** + * The service zone details. + */ export interface ServiceZoneDTO { + /** + * The ID of the service zone. + */ id: string + + /** + * The name of the service zone. + */ name: string + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The fulfillment sets assoiated with the service zone. + */ fulfillment_sets: FulfillmentSetDTO[] + + /** + * The geo zones assoiated with the service zone. + */ geo_zones: GeoZoneDTO[] + + /** + * The shipping options assoiated with the service zone. + */ shipping_options: ShippingOptionDTO[] + + /** + * The creation date of the service zone. + */ created_at: Date + + /** + * The update date of the service zone. + */ updated_at: Date + + /** + * The deletion date of the service zone. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved service zones. + */ export interface FilterableServiceZoneProps extends BaseFilterable { + /** + * The IDs to filter the service zones by. + */ id?: string | string[] | OperatorMap + + /** + * Filter the service zones by their name. + */ name?: string | string[] | OperatorMap + + /** + * The filters to apply on the associated geo zones. + */ geo_zones?: FilterableGeoZoneProps + + /** + * The filters to apply on the associated fulfillment sets. + */ fulfillment_set?: FilterableFulfillmentSetProps + + /** + * @ignore + * + * @privateRemarks + * Added the `@\ignore` because of the `TODO`. Once implemented, the + * `@\ignore` (and this comment) should be removed. + */ shipping_options?: any // TODO } diff --git a/packages/types/src/fulfillment/common/shipping-option-rule.ts b/packages/types/src/fulfillment/common/shipping-option-rule.ts index d9ac5f4f67..89bf770f2e 100644 --- a/packages/types/src/fulfillment/common/shipping-option-rule.ts +++ b/packages/types/src/fulfillment/common/shipping-option-rule.ts @@ -1,22 +1,86 @@ import { ShippingOptionDTO } from "./shipping-option" import { BaseFilterable, OperatorMap } from "../../dal" +/** + * The shipping option rule details. + */ export interface ShippingOptionRuleDTO { + /** + * The ID of the shipping option rule. + */ id: string + + /** + * The attribute of the shipping option rule. + */ attribute: string + + /** + * The operator of the shipping option rule. + * + * @example + * in + */ operator: string - value: { value: string | string[] } | null + + /** + * The values of the shipping option rule. + */ + value: { + /** + * The values of the shipping option rule. + */ + value: string | string[] + } | null + + /** + * The associated shipping option's ID. + */ shipping_option_id: string + + /** + * The associated shipping option. + */ shipping_option: ShippingOptionDTO + + /** + * The creation date of the shipping option rule. + */ created_at: Date + + /** + * The update date of the shipping option rule. + */ updated_at: Date + + /** + * The deletion date of the shipping option rule. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved shipping option rules. + */ export interface FilterableShippingOptionRuleProps extends BaseFilterable { + /** + * The IDs to filter the shipping option rules by. + */ id?: string | string[] | OperatorMap + + /** + * Filter the shipping option rules by their attribute. + */ attribute?: string | string[] | OperatorMap + + /** + * Filter the shipping option rules by their operator. + */ operator?: string | string[] | OperatorMap + + /** + * Filter the shipping option rules by their values. + */ value?: string | string[] | OperatorMap } diff --git a/packages/types/src/fulfillment/common/shipping-option-type.ts b/packages/types/src/fulfillment/common/shipping-option-type.ts index b52a1b93c4..deb4873359 100644 --- a/packages/types/src/fulfillment/common/shipping-option-type.ts +++ b/packages/types/src/fulfillment/common/shipping-option-type.ts @@ -1,22 +1,78 @@ import { ShippingOptionDTO } from "./shipping-option" import { BaseFilterable, OperatorMap } from "../../dal" +/** + * The shipping option type details. + */ export interface ShippingOptionTypeDTO { + /** + * The ID of the shipping option type. + */ id: string + + /** + * The label of the shipping option type. + */ label: string + + /** + * The description of the shipping option type. + */ description: string + + /** + * The code of the shipping option type. + */ code: string + + /** + * The associated shipping option's ID. + */ shipping_option_id: string + + /** + * The associated shipping option. + */ shipping_option: ShippingOptionDTO + + /** + * The creation date of the shipping option type. + */ created_at: Date + + /** + * The update date of the shipping option type. + */ updated_at: Date + + /** + * The deletion date of the shipping option type. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved shipping option types. + */ export interface FilterableShippingOptionTypeProps extends BaseFilterable { + /** + * The IDs to filter the shipping option types by. + */ id?: string | string[] | OperatorMap + + /** + * Filter the shipping option types by their label. + */ label?: string | string[] | OperatorMap + + /** + * Filter the shipping option types by their description. + */ description?: string | string[] | OperatorMap + + /** + * Filter the shipping option types by their code. + */ code?: string | string[] | OperatorMap } diff --git a/packages/types/src/fulfillment/common/shipping-option.ts b/packages/types/src/fulfillment/common/shipping-option.ts index ce2e37cabc..2ac9633671 100644 --- a/packages/types/src/fulfillment/common/shipping-option.ts +++ b/packages/types/src/fulfillment/common/shipping-option.ts @@ -12,57 +12,203 @@ import { } from "./shipping-option-type" import { ShippingProfileDTO } from "./shipping-profile" +/** + * The shipping option's price type. + * + * - Use `calculated` if the shipping option's price amount is calculated by the fulfillment provider. + * - Use `flat_rate` if the shipping option's price is always the same amount. + * + */ export type ShippingOptionPriceType = "calculated" | "flat" +/** + * The shipping option details. + */ export interface ShippingOptionDTO { + /** + * The ID of the shipping option. + */ id: string + + /** + * The name of the shipping option. + */ name: string + + /** + * The type of the shipping option's price. + */ price_type: ShippingOptionPriceType + + /** + * The associated service zone's ID. + */ service_zone_id: string + + /** + * The associated shipping profile's ID. + */ shipping_profile_id: string + + /** + * The associated fulfillment provider's ID. + */ provider_id: string + + /** + * The associated shipping option type's ID. + */ shipping_option_type_id: string | null + + /** + * The data necessary for the associated fulfillment provider to process the shipping option + * and, later, its associated fulfillments. + */ data: Record | null + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The associated service zone. + */ service_zone: ServiceZoneDTO + + /** + * The associated shipping profile. + */ shipping_profile: ShippingProfileDTO + + /** + * The associated fulfillment provider. + */ fulfillment_provider: FulfillmentProviderDTO + + /** + * The associated shipping option type. + */ type: ShippingOptionTypeDTO + + /** + * The rules associated with the shipping option. + */ rules: ShippingOptionRuleDTO[] + + /** + * The fulfillments associated with the shipping option. + */ fulfillments: FulfillmentDTO[] + + /** + * The creation date of the shipping option. + */ created_at: Date + + /** + * The update date of the shipping option. + */ updated_at: Date + + /** + * The deletion date of the shipping option. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved shipping options. + */ export interface FilterableShippingOptionProps extends BaseFilterable { + /** + * The IDs to filter the shipping options by. + */ id?: string | string[] | OperatorMap + + /** + * Filter the shipping options by their name. + */ name?: string | string[] | OperatorMap + + /** + * Filter the shipping options by the ID of their associated shipping profile. + */ shipping_profile_id?: string | string[] | OperatorMap + + /** + * Filter the shipping options by their price type. + */ price_type?: | ShippingOptionPriceType | ShippingOptionPriceType[] | OperatorMap + + /** + * The filters to apply on the retrieved service zones. + */ service_zone?: FilterableServiceZoneProps + + /** + * The filters to apply on the retrieved shipping option types. + */ shipping_option_type?: FilterableShippingOptionTypeProps + + /** + * The filters to apply on the retrieved shipping option rules. + */ rules?: FilterableShippingOptionRuleProps } +/** + * A context's details used to filter the shipping option. + */ export interface FilterableShippingOptionForContextProps extends FilterableShippingOptionProps { - fulfillment_set_id?: string | string[] | OperatorMap - fulfillment_set_type?: string | string[] | OperatorMap /** + * The fulfillment set's ID used in the context. + */ + fulfillment_set_id?: string | string[] | OperatorMap + + /** + * The fulfillment set's type used in the context. + */ + fulfillment_set_type?: string | string[] | OperatorMap + + /** + * The address used in the context. It filters the shipping options based on + * the geo zones of their associated service zone. + * + * @privateRemarks * The address is a shortcut to filter through geo_zones * and build opinionated validation and filtering around the geo_zones. * For custom filtering you can go through the service_zone.geo_zones directly. */ address?: { + /** + * The ISO 2 character country code. + */ country_code?: string + + /** + * The province code. + */ province_code?: string + + /** + * The city. + */ city?: string + + /** + * The postal expression + */ postal_expression?: string } + + /** + * The shipping option's context to filter directly. + */ context?: Record } diff --git a/packages/types/src/fulfillment/common/shipping-profile.ts b/packages/types/src/fulfillment/common/shipping-profile.ts index 03336147ab..e95ccc59f5 100644 --- a/packages/types/src/fulfillment/common/shipping-profile.ts +++ b/packages/types/src/fulfillment/common/shipping-profile.ts @@ -4,21 +4,73 @@ import { } from "./shipping-option" import { BaseFilterable, OperatorMap } from "../../dal" +/** + * The shipping profile details. + */ export interface ShippingProfileDTO { + /** + * The ID of the shipping profile. + */ id: string + + /** + * The name of the shipping profile. + */ name: string + + /** + * The type of the shipping profile. + */ type: string + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The shipping options associated with the shipping profile. + */ shipping_options: ShippingOptionDTO[] + + /** + * The creation date of the shipping profile. + */ created_at: Date + + /** + * The update date of the shipping profile. + */ updated_at: Date + + /** + * The deletion date of the shipping profile. + */ deleted_at: Date | null } +/** + * The filters to apply on the retrieved shipping profiles. + */ export interface FilterableShippingProfileProps extends BaseFilterable { + /** + * The IDs to filter the shipping profiles by. + */ id?: string | string[] | OperatorMap + + /** + * Filter the shipping profiles by their name. + */ name?: string | string[] | OperatorMap + + /** + * Filter the shipping profiles by their type. + */ type?: string | string[] | OperatorMap + + /** + * The filters to apply on the retrieved shipping options. + */ shipping_options?: FilterableShippingOptionProps } diff --git a/packages/types/src/fulfillment/mutations/fulfillment-address.ts b/packages/types/src/fulfillment/mutations/fulfillment-address.ts index b76a7ad5e1..7876cc4d2a 100644 --- a/packages/types/src/fulfillment/mutations/fulfillment-address.ts +++ b/packages/types/src/fulfillment/mutations/fulfillment-address.ts @@ -1,14 +1,64 @@ +/** + * The fulfillment address to be created. + */ export interface CreateFulfillmentAddressDTO { + /** + * The associated fulfillment's ID. + */ fulfillment_id: string + + /** + * The company of the fulfillment address. + */ company?: string | null + + /** + * The first name of the fulfillment address. + */ first_name?: string | null + + /** + * The last name of the fulfillment address. + */ last_name?: string | null + + /** + * The first line of the fulfillment address. + */ address_1?: string | null + + /** + * The second line of the fulfillment address. + */ address_2?: string | null + + /** + * The city of the fulfillment address. + */ city?: string | null + + /** + * The ISO 2 character country code of the fulfillment address. + */ country_code?: string | null + + /** + * The province of the fulfillment address. + */ province?: string | null + + /** + * The postal code of the fulfillment address. + */ postal_code?: string | null + + /** + * The phone of the fulfillment address. + */ phone?: string | null + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record | null } diff --git a/packages/types/src/fulfillment/mutations/fulfillment-item.ts b/packages/types/src/fulfillment/mutations/fulfillment-item.ts index 8c863d40ab..1f248822f8 100644 --- a/packages/types/src/fulfillment/mutations/fulfillment-item.ts +++ b/packages/types/src/fulfillment/mutations/fulfillment-item.ts @@ -1,9 +1,39 @@ +/** + * The fulfillment item to be created. + */ export interface CreateFulfillmentItemDTO { + /** + * The associated fulfillment's ID. + */ fulfillment_id: string + + /** + * The title of the fulfillment item. + */ title: string + + /** + * The SKU of the fulfillment item. + */ sku: string + + /** + * The quantity of the fulfillment item. + */ quantity: number + + /** + * The barcode of the fulfillment item. + */ barcode: string + + /** + * The associated line item's ID. + */ line_item_id?: string | null + + /** + * The associated inventory item's ID. + */ inventory_item_id?: string | null } diff --git a/packages/types/src/fulfillment/mutations/fulfillment-label.ts b/packages/types/src/fulfillment/mutations/fulfillment-label.ts index a1581c22f4..d3f712ea57 100644 --- a/packages/types/src/fulfillment/mutations/fulfillment-label.ts +++ b/packages/types/src/fulfillment/mutations/fulfillment-label.ts @@ -1,6 +1,24 @@ +/** + * The fulfillment label to be created. + */ export interface CreateFulfillmentLabelDTO { + /** + * The tracking number of the fulfillment label. + */ tracking_number: string + + /** + * The tracking URL of the fulfillment label. + */ tracking_url: string + + /** + * The URL of the label. + */ label_url: string + + /** + * The associated fulfillment's ID. + */ fulfillment_id: string } diff --git a/packages/types/src/fulfillment/mutations/fulfillment-set.ts b/packages/types/src/fulfillment/mutations/fulfillment-set.ts index 9d70778676..440f547acf 100644 --- a/packages/types/src/fulfillment/mutations/fulfillment-set.ts +++ b/packages/types/src/fulfillment/mutations/fulfillment-set.ts @@ -1,14 +1,54 @@ import { CreateServiceZoneDTO } from "./service-zone" +/** + * The fulfillment set to be created. + */ export interface CreateFulfillmentSetDTO { + /** + * The name of the fulfillment set. + */ name: string + + /** + * The type of the fulfillment set. + */ type: string - service_zones?: Omit[] + + /** + * The service zones associated with the fulfillment set. + */ + service_zones?: Omit[] } +/** + * The attributes to update in the fulfillment set. + */ export interface UpdateFulfillmentSetDTO { + /** + * The ID of the fulfillment set. + */ id: string + + /** + * The name of the fulfillment set. + */ name?: string + + /** + * The type of the fulfillment set. + */ type?: string - service_zones?: (Omit | { id: string })[] + + /** + * The service zones associated with the fulfillment set. + */ + service_zones?: ( + | Omit + | { + /** + * The ID of the service zone. + */ + id: string + } + )[] } diff --git a/packages/types/src/fulfillment/mutations/fulfillment.ts b/packages/types/src/fulfillment/mutations/fulfillment.ts index e0703101f0..5ae15f8295 100644 --- a/packages/types/src/fulfillment/mutations/fulfillment.ts +++ b/packages/types/src/fulfillment/mutations/fulfillment.ts @@ -2,29 +2,112 @@ import { CreateFulfillmentAddressDTO } from "./fulfillment-address" import { CreateFulfillmentItemDTO } from "./fulfillment-item" import { CreateFulfillmentLabelDTO } from "./fulfillment-label" +/** + * The fulfillment order to be created. + */ export interface CreateFulfillmentOrderDTO {} +/** + * The fulfillment to be created. + */ export interface CreateFulfillmentDTO { + /** + * The associated location's ID. + */ location_id: string + + /** + * The date the fulfillment was packed. + */ packed_at?: Date | null + + /** + * The date the fulfillment was shipped. + */ shipped_at?: Date | null + + /** + * The date the fulfillment was delivered. + */ delivered_at?: Date | null + + /** + * The date the fulfillment was canceled. + */ canceled_at?: Date | null + + /** + * The data necessary for the associated fulfillment provider to process the fulfillment. + */ data?: Record | null + + /** + * The associated fulfillment provider's ID. + */ provider_id: string + + /** + * The associated shipping option's ID. + */ shipping_option_id?: string | null + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record | null + + /** + * The address associated with the fulfillment. It's used for delivery. + */ delivery_address: Omit + + /** + * The items associated with the fulfillment. + */ items: Omit[] + + /** + * The labels associated with the fulfillment. + */ labels: Omit[] + + /** + * The associated fulfillment order. + */ order: CreateFulfillmentOrderDTO } +/** + * The attributes to update in the fulfillment. + */ export interface UpdateFulfillmentDTO { + /** + * The associated location's ID. + */ location_id?: string + + /** + * The date the fulfillment was packed. + */ packed_at?: Date | null + + /** + * The date the fulfillment was shipped. + */ shipped_at?: Date | null + + /** + * The date the fulfillment was delivered. + */ delivered_at?: Date | null + + /** + * The data necessary for the associated fulfillment provider to process the fulfillment. + */ data?: Record | null + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record | null } diff --git a/packages/types/src/fulfillment/mutations/geo-zone.ts b/packages/types/src/fulfillment/mutations/geo-zone.ts index 4cb10c2c05..e908179fe5 100644 --- a/packages/types/src/fulfillment/mutations/geo-zone.ts +++ b/packages/types/src/fulfillment/mutations/geo-zone.ts @@ -1,66 +1,204 @@ import { GeoZoneType } from "../common" +/** + * The geo zone to be created. + */ interface CreateGeoZoneBaseDTO { + /** + * The type of the geo zone. + */ type: GeoZoneType + + /** + * The associated service zone's ID. + */ service_zone_id: string + + /** + * The ISO 2 character country code of the geo zone. + */ country_code: string + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record | null } +/** + * The geo zone to be created of type `country`. + */ export interface CreateCountryGeoZoneDTO extends CreateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"country"` + */ type: "country" } +/** + * The geo zone to be created of type `province`. + */ export interface CreateProvinceGeoZoneDTO extends CreateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"province"` + */ type: "province" + + /** + * The province code of the geo zone. + */ province_code: string } +/** + * The geo zone to be created of type `city`. + */ export interface CreateCityGeoZoneDTO extends CreateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"city"` + */ type: "city" + + /** + * The province code of the geo zone. + */ province_code: string + + /** + * The city of the geo zone. + */ city: string } +/** + * The geo zone to be created of type `zip`. + */ export interface CreateZipGeoZoneDTO extends CreateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"zip"` + */ type: "zip" + + /** + * The province code of the geo zone. + */ province_code: string + + /** + * The city of the geo zone. + */ city: string + + /** + * The postal expression of the geo zone. + */ postal_expression: Record } +/** + * @interface + * + * The geo zone to be created. The value of the `type` attributes allows for passing more attributes. + */ export type CreateGeoZoneDTO = | CreateCountryGeoZoneDTO | CreateProvinceGeoZoneDTO | CreateCityGeoZoneDTO | CreateZipGeoZoneDTO +/** + * The attributes to update in the geo zone. + */ export interface UpdateGeoZoneBaseDTO extends Partial { + /** + * The ID of the geo zone. + */ id: string } +/** + * The attributes to update in the geo zone of type `country`. + */ export interface UpdateCountryGeoZoneDTO extends UpdateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"country"` + */ type: "country" } +/** + * The attributes to update in the geo zone of type `province`. + */ export interface UpdateProvinceGeoZoneDTO extends UpdateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"province"` + */ type: "province" + + /** + * The province code of the geo zone. + */ province_code: string } +/** + * The attributes to update in the geo zone of type `city`. + */ export interface UpdateCityGeoZoneDTO extends UpdateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"city"` + */ type: "city" + + /** + * The province code of the geo zone. + */ province_code?: string + + /** + * The city of the geo zone. + */ city?: string } +/** + * The attributes to update in the geo zone of type `zip`. + */ export interface UpdateZipGeoZoneDTO extends UpdateGeoZoneBaseDTO { + /** + * The type of the geo zone. + * @defaultValue `"zip"` + */ type: "zip" + + /** + * The province code of the geo zone. + */ province_code?: string + + /** + * The city of the geo zone. + */ city?: string + + /** + * The postal expression of the geo zone. + */ postal_expression?: Record } +/** + * @interface + * + * The attributes to update in the geo zone. The value of the `type` attributes allows for passing more attributes. + */ export type UpdateGeoZoneDTO = | UpdateCountryGeoZoneDTO | UpdateProvinceGeoZoneDTO diff --git a/packages/types/src/fulfillment/mutations/service-zone.ts b/packages/types/src/fulfillment/mutations/service-zone.ts index 72f23f0d84..a986369239 100644 --- a/packages/types/src/fulfillment/mutations/service-zone.ts +++ b/packages/types/src/fulfillment/mutations/service-zone.ts @@ -5,9 +5,23 @@ import { CreateZipGeoZoneDTO, } from "./geo-zone" +/** + * The service zone to be created. + */ export interface CreateServiceZoneDTO { + /** + * The name of the service zone. + */ name: string + + /** + * The associated fulfillment set's ID. + */ fulfillment_set_id: string + + /** + * The geo zones associated with the service zone. + */ geo_zones?: ( | Omit | Omit @@ -16,16 +30,38 @@ export interface CreateServiceZoneDTO { )[] } +/** + * The attributes to update in the service zone. + */ export interface UpdateServiceZoneDTO { + /** + * The ID of the service zone. + */ id?: string + + /** + * The name of the service zone. + */ name?: string + + /** + * The geo zones associated with the service zone. + */ geo_zones?: ( | Omit | Omit | Omit | Omit - | { id: string } + | { + /** + * The ID of the geo zone. + */ + id: string + } )[] } +/** + * A service zone to be created or updated. + */ export interface UpsertServiceZoneDTO extends UpdateServiceZoneDTO {} diff --git a/packages/types/src/fulfillment/mutations/shipping-option-rule.ts b/packages/types/src/fulfillment/mutations/shipping-option-rule.ts index e6bb20affc..e0e3d3086e 100644 --- a/packages/types/src/fulfillment/mutations/shipping-option-rule.ts +++ b/packages/types/src/fulfillment/mutations/shipping-option-rule.ts @@ -1,13 +1,35 @@ import { RuleOperatorType } from "../../common" +/** + * The shipping option rule to be created. + */ export interface CreateShippingOptionRuleDTO { + /** + * The attribute of the shipping option rule. + */ attribute: string + /** + * The operator of the shipping option rule. + */ operator: RuleOperatorType + /** + * The value(s) of the shipping option rule. + */ value: string | string[] + + /** + * The associated shipping option's ID. + */ shipping_option_id: string } +/** + * The attributes to update in the shipping option rule. + */ export interface UpdateShippingOptionRuleDTO extends Partial { + /** + * The ID of the shipping option rule. + */ id: string } diff --git a/packages/types/src/fulfillment/mutations/shipping-option-type.ts b/packages/types/src/fulfillment/mutations/shipping-option-type.ts index ed882a31da..785ec365bb 100644 --- a/packages/types/src/fulfillment/mutations/shipping-option-type.ts +++ b/packages/types/src/fulfillment/mutations/shipping-option-type.ts @@ -1,11 +1,35 @@ +/** + * The shipping option type to be created. + */ export interface CreateShippingOptionTypeDTO { + /** + * The label of the shipping option type. + */ label: string + + /** + * The description of the shipping option type. + */ description: string + + /** + * The code of the shipping option type. + */ code: string + + /** + * The associated shipping option's ID. + */ shipping_option_id: string } +/** + * The attributes to update in the shipping option type. + */ export interface UpdateShippingOptionTypeDTO extends Partial { + /** + * The ID of the shipping option type. + */ id: string } diff --git a/packages/types/src/fulfillment/mutations/shipping-option.ts b/packages/types/src/fulfillment/mutations/shipping-option.ts index 8bc12c5a87..b7432a1d0d 100644 --- a/packages/types/src/fulfillment/mutations/shipping-option.ts +++ b/packages/types/src/fulfillment/mutations/shipping-option.ts @@ -2,32 +2,119 @@ import { CreateShippingOptionTypeDTO } from "./shipping-option-type" import { ShippingOptionPriceType } from "../common" import { CreateShippingOptionRuleDTO } from "./shipping-option-rule" +/** + * The shipping option to be created. + */ export interface CreateShippingOptionDTO { + /** + * The name of the shipping option. + */ name: string + + /** + * The type of the shipping option's price. + */ price_type: ShippingOptionPriceType + + /** + * The associated service zone's ID. + */ service_zone_id: string + + /** + * The associated shipping profile's ID. + */ shipping_profile_id: string + + /** + * The associated provider's ID. + */ provider_id: string + + /** + * The shipping option type associated with the shipping option. + */ type: Omit + + /** + * The data necessary for the associated fulfillment provider to process the shipping option + * and its associated fulfillments. + */ data?: Record | null + + /** + * The shipping option rules associated with the shipping option. + */ rules?: Omit[] } +/** + * The attributes to update in the shipping option. + */ export interface UpdateShippingOptionDTO { + /** + * The ID of the shipping option. + */ id?: string + + /** + * The name of the shipping option. + */ name?: string + + /** + * The type of the shipping option's price. + */ price_type?: ShippingOptionPriceType + + /** + * The associated service zone's ID. + */ service_zone_id?: string + + /** + * The associated shipping profile's ID. + */ shipping_profile_id?: string + + /** + * The associated provider's ID. + */ provider_id?: string - type: Omit | { id: string } + + /** + * The shipping option type associated with the shipping option. + */ + type: + | Omit + | { + /** + * The ID of the shipping option type. + */ + id: string + } + + /** + * The data necessary for the associated fulfillment provider to process the shipping option + * and its associated fulfillments. + */ data?: Record | null + + /** + * The shipping option rules associated with the shipping option. + */ rules?: ( | Omit - | { id: string } + | { + /** + * The ID of the shipping option rule. + */ + id: string + } )[] } -export interface UpsertShippingOptionDTO extends UpdateShippingOptionDTO { - -} +/** + * A shipping option to be created or updated. + */ +export interface UpsertShippingOptionDTO extends UpdateShippingOptionDTO {} diff --git a/packages/types/src/fulfillment/mutations/shipping-profile.ts b/packages/types/src/fulfillment/mutations/shipping-profile.ts index c663fa1616..06813e3be9 100644 --- a/packages/types/src/fulfillment/mutations/shipping-profile.ts +++ b/packages/types/src/fulfillment/mutations/shipping-profile.ts @@ -1,8 +1,25 @@ +/** + * The shipping profile to be created. + */ export interface CreateShippingProfileDTO { + /** + * The name of the shipping profile. + */ name: string + + /** + * The type of the shipping profile. + */ type?: string + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record } +/** + * The attributes to update in the shipping profile. + */ export interface UpdateShippingProfileDTO extends Partial {} diff --git a/packages/types/src/fulfillment/service.ts b/packages/types/src/fulfillment/service.ts index 13fe28bf14..743ac4220b 100644 --- a/packages/types/src/fulfillment/service.ts +++ b/packages/types/src/fulfillment/service.ts @@ -40,89 +40,302 @@ import { import { CreateFulfillmentDTO } from "./mutations/fulfillment" import { CreateShippingProfileDTO } from "./mutations/shipping-profile" +/** + * The main service interface for the Fulfillment Module. + */ export interface IFulfillmentModuleService extends IModuleService { /** - * Retrieve a fulfillment set - * @param id - * @param config - * @param sharedContext + * This method retrieves a fulfillment set by its ID. + * + * @param {string} id - The ID of the fulfillment set. + * @param {FindConfig} config - The configurations determining how the fulfillment set is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a fulfillment set. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved fulfillment set. + * + * @example + * A simple example that retrieves a fulfillment set by its ID: + * + * ```ts + * const fulfillmentSet = + * await fulfillmentModuleService.retrieve("fuset_123") + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const fulfillmentSet = await fulfillmentModuleService.retrieve( + * "fuset_123", + * { + * relations: ["service_zones"], + * } + * ) + * ``` */ retrieve( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List fulfillment sets - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of fulfillment sets based on optional filters and configuration. + * + * @param {FilterableFulfillmentSetProps} filters - The filters to apply on the retrieved fulfillment sets. + * @param {FindConfig} config - The configurations determining how the fulfillment set is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a fulfillment set. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of fulfillment sets. + * + * @example + * To retrieve a list of fulfillment sets using their IDs: + * + * ```ts + * const fulfillmentSets = await fulfillmentModuleService.list({ + * id: ["fuset_123", "fuset_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the fulfillment set: + * + * ```ts + * const fulfillmentSets = await fulfillmentModuleService.list( + * { + * id: ["fuset_123", "fuset_321"], + * }, + * { + * relations: ["search_zones"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const fulfillmentSets = await fulfillmentModuleService.list( + * { + * id: ["fuset_123", "fuset_321"], + * }, + * { + * relations: ["search_zones"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ list( filters?: FilterableFulfillmentSetProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count fulfillment sets - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of fulfillment sets along with the total count of available fulfillment sets satisfying the provided filters. + * + * @param {FilterableFulfillmentSetProps} filters - The filters to apply on the retrieved fulfillment sets. + * @param {FindConfig} config - The configurations determining how the fulfillment set is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a fulfillment set. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[FulfillmentSetDTO[], number]>} The list of fulfillment sets along with their total count. + * + * @example + * To retrieve a list of fulfillment sets using their IDs: + * + * ```ts + * const [fulfillmentSets, count] = + * await fulfillmentModuleService.listAndCount({ + * id: ["fuset_123", "fuset_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the fulfillment set: + * + * ```ts + * const [fulfillmentSets, count] = + * await fulfillmentModuleService.listAndCount( + * { + * id: ["fuset_123", "fuset_321"], + * }, + * { + * relations: ["search_zones"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [fulfillmentSets, count] = + * await fulfillmentModuleService.listAndCount( + * { + * id: ["fuset_123", "fuset_321"], + * }, + * { + * relations: ["search_zones"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listAndCount( filters?: FilterableFulfillmentSetProps, config?: FindConfig, sharedContext?: Context ): Promise<[FulfillmentSetDTO[], number]> + /** - * Create a new fulfillment set - * @param data - * @param sharedContext + * This method creates fulfillment sets. + * + * @param {CreateFulfillmentSetDTO[]} data - The fulfillment sets to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created fulfillment sets. + * + * @example + * const fulfillmentSets = await fulfillmentModuleService.create( + * [ + * { + * name: "Shipping", + * type: "default", + * }, + * { + * name: "Pickup", + * type: "provider-controlled", + * }, + * ] + * ) */ create( data: CreateFulfillmentSetDTO[], sharedContext?: Context ): Promise + + /** + * This method creates a fulfillment set. + * + * @param {CreateFulfillmentSetDTO} data - The fulfillment set to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created fulfillment set. + * + * @example + * const fulfillmentSet = await fulfillmentModuleService.create({ + * name: "Shipping", + * type: "default", + * }) + */ create( data: CreateFulfillmentSetDTO, sharedContext?: Context ): Promise + /** - * Update a fulfillment set - * @param data - * @param sharedContext + * This method updates existing fulfillment sets. + * + * @param {UpdateFulfillmentSetDTO[]} data - The attributes to update in the fulfillment sets. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated fulfillment sets. + * + * @example + * const fulfillmentSets = await fulfillmentModuleService.update( + * [ + * { + * id: "fuset_123", + * name: "Shipping", + * }, + * { + * id: "fuset_321", + * name: "Pickup", + * }, + * ] + * ) */ update( data: UpdateFulfillmentSetDTO[], sharedContext?: Context ): Promise + + /** + * This method updates an existing fulfillment set. + * + * @param {UpdateFulfillmentSetDTO} data - The attributes to update in the fulfillment set. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated fulfillment set. + * + * @example + * const fulfillmentSet = await fulfillmentModuleService.update({ + * id: "fuset_123", + * name: "Shipping", + * }) + */ update( data: UpdateFulfillmentSetDTO, sharedContext?: Context ): Promise + /** - * Delete a fulfillment set - * @param ids - * @param sharedContext + * This method deletes fulfillment sets by their IDs. + * + * @param {string[]} ids - The IDs of the fulfillment sets. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the fulfillment sets are deleted successfully. + * + * @example + * await fulfillmentModuleService.delete([ + * "fuset_123", + * "fuset_321", + * ]) */ delete(ids: string[], sharedContext?: Context): Promise - delete(id: string, sharedContext?: Context): Promise + /** - * Soft delete fulfillment sets - * @param fulfillmentIds - * @param config - * @param sharedContext + * This method deletes a fulfillment set by its ID. + * + * @param {string} id - The ID of the fulfillment set. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the fulfillment set is deleted successfully. + * + * @example + * await fulfillmentModuleService.delete("fuset_123") + */ + delete(id: string, sharedContext?: Context): Promise + + /** + * This method soft deletes fulfillment sets by their IDs. + * + * @param {string[]} fulfillmentIds - The IDs of the fulfillment sets. + * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted. + * If there are no related records, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.softDelete([ + * "fuset_123", + * "fuset_321", + * ]) */ softDelete( fulfillmentIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** - * Restore fulfillment sets - * @param fulfillmentIds - * @param config - * @param sharedContext + * This method restores a soft deleted fulfillment by its IDs. + * + * @param {string[]} fulfillmentIds - The IDs of the fulfillment sets. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the fulfillment sets. You can pass to its `returnLinkableKeys` + * property any of the fulfillment set's relation attribute names. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.restore([ + * "fuset_123", + * "fuset_321", + * ]) */ restore( fulfillmentIds: string[], @@ -131,59 +344,238 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise | void> /** - * Retrieve a service zone - * @param id - * @param config - * @param sharedContext + * This method retrieves a service zone by its ID. + * + * @param {string} id - The ID of the service zone. + * @param {FindConfig} config - The configurations determining how the service zone is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a service zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved service zone. + * + * @example + * A simple example that retrieves a service zone by its ID: + * + * ```ts + * const serviceZone = + * await fulfillmentModuleService.retrieveServiceZone( + * "serzo_123" + * ) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const serviceZone = + * await fulfillmentModuleService.retrieveServiceZone( + * "serzo_123", + * { + * relations: ["shipping_options"], + * } + * ) + * ``` */ retrieveServiceZone( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List service zones - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of service zones based on optional filters and configuration. + * + * @param {FilterableServiceZoneProps} filters - The filters to apply on the retrieved service zones. + * @param {FindConfig} config - The configurations determining how the service zone is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a service zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of service zones. + * + * @example + * To retrieve a list of service zones using their IDs: + * + * ```ts + * const serviceZones = + * await fulfillmentModuleService.listServiceZones({ + * id: ["serzo_123", "serzo_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the service zone: + * + * ```ts + * const serviceZones = + * await fulfillmentModuleService.listServiceZones( + * { + * id: ["serzo_123", "serzo_321"], + * }, + * { + * relations: ["shipping_options"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const serviceZones = + * await fulfillmentModuleService.listServiceZones( + * { + * id: ["serzo_123", "serzo_321"], + * }, + * { + * relations: ["shipping_options"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listServiceZones( filters?: FilterableServiceZoneProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count service zones - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of service zones along with the total count of available service zones satisfying the provided filters. + * + * @param {FilterableServiceZoneProps} filters - The filters to apply on the retrieved service zones. + * @param {FindConfig} config - The configurations determining how the service zone is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a service zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ServiceZoneDTO[], number]>} The list of service zones along with their total count. + * + * @example + * To retrieve a list of service zones using their IDs: + * + * ```ts + * const [serviceZones, count] = + * await fulfillmentModuleService.listAndCountServiceZones({ + * id: ["serzo_123", "serzo_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the service zone: + * + * ```ts + * const [serviceZones, count] = + * await fulfillmentModuleService.listAndCountServiceZones( + * { + * id: ["serzo_123", "serzo_321"], + * }, + * { + * relations: ["shipping_options"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [serviceZones, count] = + * await fulfillmentModuleService.listAndCountServiceZones( + * { + * id: ["serzo_123", "serzo_321"], + * }, + * { + * relations: ["shipping_options"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listAndCountServiceZones( filters?: FilterableServiceZoneProps, config?: FindConfig, sharedContext?: Context ): Promise<[ServiceZoneDTO[], number]> + /** - * Create a new service zone - * @param data - * @param sharedContext + * This method creates service zones. + * + * @param {CreateServiceZoneDTO[]} data - The service zones to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created service zones. + * + * @example + * const serviceZones = + * await fulfillmentModuleService.createServiceZones([ + * { + * name: "Nordic Shipping Methods", + * fulfillment_set_id: "fuset_123", + * }, + * { + * name: "Pickup Service Area", + * fulfillment_set_id: "fuset_321", + * }, + * ]) */ createServiceZones( data: CreateServiceZoneDTO[], sharedContext?: Context ): Promise + + /** + * This method creates a service zone. + * + * @param {CreateServiceZoneDTO} data - The service zone to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created service zone. + * + * @example + * const serviceZone = + * await fulfillmentModuleService.createServiceZones({ + * name: "Nordic Shipping Methods", + * fulfillment_set_id: "fuset_123", + * }) + */ createServiceZones( data: CreateServiceZoneDTO, sharedContext?: Context ): Promise + /** - * Update a service zone + * This method updates an existing service zone. + * + * @param {string} id - The ID of the service zone. + * @param {UpdateServiceZoneDTO} data - The attributes to update in the service zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated service zone. + * + * @example + * const serviceZone = + * await fulfillmentModuleService.updateServiceZones( + * "serzo_123", + * { + * name: "US", + * } + * ) */ updateServiceZones( id: string, data: UpdateServiceZoneDTO, sharedContext?: Context ): Promise + + /** + * This method updates existing service zones matching the specified filters. + * + * @param {FilterableServiceZoneProps} selector - The filters specifying which service zones to update. + * @param {UpdateServiceZoneDTO} data - The attributes to update in the service zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated service zones. + * + * @example + * const serviceZones = + * await fulfillmentModuleService.updateServiceZones( + * { + * id: ["serzo_123", "serzo_321"], + * }, + * { + * name: "US", + * } + * ) + */ updateServiceZones( selector: FilterableServiceZoneProps, data: UpdateServiceZoneDTO, @@ -191,39 +583,112 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise /** - * Upsert a service zone + * This method updates or creates a service zone if it doesn't exist. + * + * @param {UpsertServiceZoneDTO} data - The attributes in the service zone to be created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created or updated service zone. + * + * @example + * const serviceZone = + * await fulfillmentModuleService.upsertServiceZones({ + * id: "serzo_123", + * name: "US", + * }) */ upsertServiceZones( data: UpsertServiceZoneDTO, sharedContext?: Context ): Promise + + /** + * This method updates or creates service zones if they don't exist. + * + * @param {UpsertServiceZoneDTO[]} data - The attributes in the service zones to be created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created or updated service zones. + * + * @example + * const serviceZones = + * await fulfillmentModuleService.upsertServiceZones([ + * { + * id: "serzo_123", + * name: "US", + * }, + * { + * name: "US", + * fulfillment_set_id: "fuset_123", + * }, + * ]) + */ upsertServiceZones( data: UpsertServiceZoneDTO[], sharedContext?: Context ): Promise + /** - * Delete a service zone - * @param ids - * @param sharedContext + * This method deletes service zones by their IDs. + * + * @param {string[]} ids - The IDs of the service zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the service zones are deleted. + * + * @example + * await fulfillmentModuleService.deleteServiceZones([ + * "serzo_123", + * "serzo_321", + * ]) */ deleteServiceZones(ids: string[], sharedContext?: Context): Promise - deleteServiceZones(id: string, sharedContext?: Context): Promise + /** - * Soft delete service zones - * @param serviceZoneIds - * @param config - * @param sharedContext + * This method deletes a service zone by its ID. + * + * @param {string} id - The ID of the service zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the service zone is deleted. + * + * @example + * await fulfillmentModuleService.deleteServiceZones("serzo_123") + */ + deleteServiceZones(id: string, sharedContext?: Context): Promise + + /** + * This method soft deletes service zones by their IDs. + * + * @param {string[]} serviceZoneIds - The IDs of the service zones. + * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted. + * If there are no related records, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.softDeleteServiceZones([ + * "serzo_123", + * "serzo_321", + * ]) */ softDeleteServiceZones( serviceZoneIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** - * Restore service zones - * @param serviceZoneIds - * @param config - * @param sharedContext + * This method restores a soft deleted service zones by their IDs. + * + * @param {string[]} serviceZoneIds - The IDs of the service zones. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the service zones. You can pass to its `returnLinkableKeys` + * property any of the service zone's relation attribute names, such as `{type relation name}`. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.restoreServiceZones([ + * "serzo_123", + * "serzo_321", + * ]) */ restoreServiceZones( serviceZoneIds: string[], @@ -232,87 +697,303 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise | void> /** - * Retrieve a geo zone - * @param id - * @param config - * @param sharedContext + * This method retrieves a geo zone by its ID. + * + * @param {string} id - The ID of the geo zone. + * @param {FindConfig} config - The configurations determining how the geo zone is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a geo zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved geo zone. + * + * @example + * A simple example that retrieves a geo zone by its ID: + * + * ```ts + * const geoZone = + * await fulfillmentModuleService.retrieveGeoZone("fgz_123") + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const geoZone = + * await fulfillmentModuleService.retrieveGeoZone("fgz_123", { + * relations: ["service_zone"], + * }) + * ``` */ retrieveGeoZone( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List geo zones - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of geo zones based on optional filters and configuration. + * + * @param {FilterableGeoZoneProps} filters - The filters to apply on the retrieved geo zones. + * @param {FindConfig} config - The configurations determining how the geo zone is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a geo zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of geo zones. + * + * @example + * To retrieve a list of geo zones using their IDs: + * + * ```ts + * const geoZones = await fulfillmentModuleService.listGeoZones({ + * id: ["fgz_123", "fgz_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the geo zone: + * + * ```ts + * const geoZones = await fulfillmentModuleService.listGeoZones( + * { + * id: ["fgz_123", "fgz_321"], + * }, + * { + * relations: ["service_zone"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const geoZones = await fulfillmentModuleService.listGeoZones( + * { + * id: ["fgz_123", "fgz_321"], + * }, + * { + * relations: ["service_zone"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listGeoZones( filters?: FilterableGeoZoneProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count geo zones - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of geo zones along with the total count of available geo zones satisfying the provided filters. + * + * @param {FilterableGeoZoneProps} filters - The filters to apply on the retrieved geo zones. + * @param {FindConfig} config - The configurations determining how the geo zone is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a geo zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[GeoZoneDTO[], number]>} The list of geo zones along with their total count. + * + * @example + * To retrieve a list of geo zones using their IDs: + * + * ```ts + * const [geoZones, count] = + * await fulfillmentModuleService.listAndCountGeoZones({ + * id: ["fgz_123", "fgz_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the geo zone: + * + * ```ts + * const [geoZones, count] = + * await fulfillmentModuleService.listAndCountGeoZones( + * { + * id: ["fgz_123", "fgz_321"], + * }, + * { + * relations: ["service_zone"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [geoZones, count] = + * await fulfillmentModuleService.listAndCountGeoZones( + * { + * id: ["fgz_123", "fgz_321"], + * }, + * { + * relations: ["service_zone"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listAndCountGeoZones( filters?: FilterableGeoZoneProps, config?: FindConfig, sharedContext?: Context ): Promise<[GeoZoneDTO[], number]> + /** - * Create a new geo zone - * @param data - * @param sharedContext + * This method creates geo zones. + * + * @param {CreateGeoZoneDTO[]} data - The geo zones to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created geo zones. + * + * @example + * const geoZones = + * await fulfillmentModuleService.createGeoZones([ + * { + * type: "country", + * service_zone_id: "serzo_123", + * country_code: "us", + * }, + * { + * type: "city", + * service_zone_id: "serzo_321", + * province_code: "VT", + * city: "Vermont", + * country_code: "us", + * }, + * ]) */ createGeoZones( data: CreateGeoZoneDTO[], sharedContext?: Context ): Promise + + /** + * This method creates a geo zones. + * + * @param {CreateGeoZoneDTO} data - The geo zone to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created geo zones. + * + * @example + * const geoZones = + * await fulfillmentModuleService.createGeoZones({ + * type: "country", + * service_zone_id: "serzo_123", + * country_code: "us", + * }) + */ createGeoZones( data: CreateGeoZoneDTO, sharedContext?: Context ): Promise + /** - * Update a geo zone - * @param data - * @param sharedContext + * This method updates existing geo zones. + * + * @param {UpdateGeoZoneDTO[]} data - The attributes to update in the geo zones. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated geo zones. + * + * @example + * const geoZones = + * await fulfillmentModuleService.updateGeoZones([ + * { + * id: "fgz_123", + * type: "country", + * country_code: "us", + * }, + * { + * id: "fgz_321", + * type: "city", + * province_code: "VT", + * }, + * ]) */ updateGeoZones( data: UpdateGeoZoneDTO[], sharedContext?: Context ): Promise + + /** + * This method updates an existing fulfillment. + * + * @param {UpdateGeoZoneDTO} data - The attributes to update in the geo zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated fulfillment. + * + * @example + * const geoZones = + * await fulfillmentModuleService.updateGeoZones({ + * id: "fgz_123", + * type: "country", + * country_code: "us", + * }) + */ updateGeoZones( data: UpdateGeoZoneDTO, sharedContext?: Context ): Promise + /** - * Delete a geo zone - * @param ids - * @param sharedContext + * This method deletes geo zones by their IDs. + * + * @param {string[]} ids - The IDs of the geo zones. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the geo zones are deleted. + * + * @example + * await fulfillmentModuleService.deleteGeoZones([ + * "fgz_123", + * "fgz_321", + * ]) */ deleteGeoZones(ids: string[], sharedContext?: Context): Promise - deleteGeoZones(id: string, sharedContext?: Context): Promise + /** - * Soft delete geo zones - * @param geoZoneIds - * @param config - * @param sharedContext + * This method deletes a geo zone by its ID. + * + * @param {string} id - The ID of the geo zone. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the geo zone is deleted. + * + * @example + * await fulfillmentModuleService.deleteGeoZones("fgz_123") + */ + deleteGeoZones(id: string, sharedContext?: Context): Promise + + /** + * This method soft deletes geo zones by their IDs. + * + * @param {string[]} geoZoneIds - The IDs of the geo zones. + * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted. + * If there are no related records, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.softDeleteGeoZones([ + * "fgz_123", + * "fgz_321", + * ]) */ softDeleteGeoZones( geoZoneIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** - * Restore geo zones - * @param geoZoneIds - * @param config - * @param sharedContext + * This method restores soft deleted geo zones by their IDs. + * + * @param {string[]} geoZoneIds - The IDs of the geo zones. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the geo zones. You can pass to its `returnLinkableKeys` + * property any of the geo zone's relation attribute names, such as `{type relation name}`. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.restoreGeoZones([ + * "fgz_123", + * "fgz_321", + * ]) */ restoreGeoZones( geoZoneIds: string[], @@ -321,74 +1002,329 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise | void> /** - * Retrieve a shipping option - * @param id - * @param config - * @param sharedContext + * This method retrieves a shipping option by its ID. + * + * @param {string} id - The ID of the shipping option. + * @param {FindConfig} config - The configurations determining how the shipping option is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved shipping option. + * + * @example + * A simple example that retrieves a shipping option by its ID: + * + * ```ts + * const shippingOption = + * await fulfillmentModuleService.retrieveShippingOption( + * "so_123" + * ) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const shippingOption = + * await fulfillmentModuleService.retrieveShippingOption( + * "so_123", + * { + * relations: ["fulfillments"], + * } + * ) + * ``` */ retrieveShippingOption( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List shipping options - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping options based on optional filters and configuration. + * + * @param {FilterableShippingOptionProps} filters - The filters to apply on the retrieved shipping options. + * @param {FindConfig} config - The configurations determining how the shipping option is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of shipping options. + * + * @example + * To retrieve a list of shipping options using their IDs: + * + * ```ts + * const shippingOptions = + * await fulfillmentModuleService.listShippingOptions({ + * id: ["so_123", "so_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the shipping option: + * + * ```ts + * const shippingOptions = + * await fulfillmentModuleService.listShippingOptions( + * { + * id: ["so_123", "so_321"], + * }, + * { + * relations: ["fulfillments"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const shippingOptions = + * await fulfillmentModuleService.listShippingOptions( + * { + * id: ["so_123", "so_321"], + * }, + * { + * relations: ["fulfillments"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listShippingOptions( filters?: FilterableShippingOptionProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List shipping options and eventually filter the result based on the context and their rules - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping options based on the provided context. + * + * @param {FilterableShippingOptionForContextProps} filters - The context of the how the shipping option is being used. It + * acts as a filter for the retrieved shipping options. + * @param {FindConfig} config - The configurations determining how the shipping option is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of shipping options. + * + * @example + * To retrieve a list of shipping options matching a context: + * + * ```ts + * const shippingOptions = + * await fulfillmentModuleService.listShippingOptionsForContext( + * { + * fulfillment_set_id: ["fuset_123"], + * address: { + * country_code: "us", + * }, + * } + * ) + * ``` + * + * To specify relations that should be retrieved within the shipping option: + * + * ```ts + * const shippingOptions = + * await fulfillmentModuleService.listShippingOptionsForContext( + * { + * fulfillment_set_id: ["fuset_123"], + * address: { + * country_code: "us", + * }, + * }, + * { + * relations: ["fulfillments"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const shippingOptions = + * await fulfillmentModuleService.listShippingOptionsForContext( + * { + * fulfillment_set_id: ["fuset_123"], + * address: { + * country_code: "us", + * }, + * }, + * { + * relations: ["fulfillments"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listShippingOptionsForContext( filters: FilterableShippingOptionForContextProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count shipping options without taking into account the context - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping options along with the total count of available shipping options satisfying the provided filters. + * + * @param {Omit} filters - Construct a type with the properties of T except for those in type K. + * @param {FindConfig} config - The configurations determining how the shipping option is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ShippingOptionDTO[], number]>} The list of shipping options along with their total count. + * + * @example + * To retrieve a list of shipping options using their IDs: + * + * ```ts + * const [shippingOptions, count] = + * await fulfillmentModuleService.listAndCountShippingOptions({ + * id: ["so_123", "so_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the shipping option: + * + * ```ts + * const [shippingOptions, count] = + * await fulfillmentModuleService.listAndCountShippingOptions( + * { + * id: ["so_123", "so_321"], + * }, + * { + * relations: ["fulfillments"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [shippingOptions, count] = + * await fulfillmentModuleService.listAndCountShippingOptions( + * { + * id: ["so_123", "so_321"], + * }, + * { + * relations: ["fulfillments"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listAndCountShippingOptions( filters?: Omit, config?: FindConfig, sharedContext?: Context ): Promise<[ShippingOptionDTO[], number]> + /** - * Create a new shipping option - * @param data - * @param sharedContext + * This method creates shipping options. + * + * @param {CreateShippingOptionDTO[]} data - The shipping options to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created shipping options. + * + * @example + * const shippingOptions = + * await fulfillmentModuleService.createShippingOptions([ + * { + * name: "DHL Express Shipping", + * price_type: "flat", + * service_zone_id: "serzo_123", + * shipping_profile_id: "sp_123", + * provider_id: "dhl", + * type: { + * label: "Express", + * description: "Ship in 24 hours", + * code: "express", + * }, + * }, + * { + * name: "Webshipper Shipping", + * price_type: "flat", + * service_zone_id: "serzo_321", + * shipping_profile_id: "sp_321", + * provider_id: "webshipper", + * type: { + * label: "Express", + * description: "Ship in 24 hours", + * code: "express", + * }, + * }, + * ]) */ createShippingOptions( data: CreateShippingOptionDTO[], sharedContext?: Context ): Promise + + /** + * This method creates a shipping option. + * + * @param {CreateShippingOptionDTO} data - The shipping option to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created shipping option. + * + * @example + * const shippingOption = + * await fulfillmentModuleService.createShippingOptions({ + * name: "DHL Express Shipping", + * price_type: "flat", + * service_zone_id: "serzo_123", + * shipping_profile_id: "sp_123", + * provider_id: "dhl", + * type: { + * label: "Express", + * description: "Ship in 24 hours", + * code: "express", + * }, + * }) + */ createShippingOptions( data: CreateShippingOptionDTO, sharedContext?: Context ): Promise /** - * Update a shipping option - * @param id - * @param data - * @param sharedContext + * This method updates an existing shipping option. + * + * @param {string} id - The ID of the shipping option. + * @param {UpdateShippingOptionDTO} data - The attributes to update in the shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated shipping option. + * + * @example + * const shippingOption = + * await fulfillmentModuleService.updateShippingOptions( + * "so_123", + * { + * name: "Express shipping", + * } + * ) */ updateShippingOptions( id: string, data: UpdateShippingOptionDTO, sharedContext?: Context ): Promise + + /** + * This method updates existing shipping options matching the specified filters. + * + * @param {FilterableShippingOptionProps} selector - The filters specifying which shipping options to update. + * @param {UpdateShippingOptionDTO} data - The attributes to update in the shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated shipping options. + * + * @example + * const shippingOptions = + * await fulfillmentModuleService.updateShippingOptions( + * { + * id: ["so_123", "so_321"], + * }, + * { + * name: "Express Shipping", + * } + * ) + */ updateShippingOptions( selector: FilterableShippingOptionProps, data: UpdateShippingOptionDTO, @@ -396,39 +1332,120 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise /** - * Upsert a shipping option + * This method updates or creates a shipping option if it doesn't exist. + * + * @param {UpsertShippingOptionDTO} data - The attributes in the shipping option to be created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created or updated shipping option. + * + * @example + * const shippingOptions = + * await fulfillmentModuleService.upsertShippingOptions({ + * id: "so_123", + * name: "Express Shipping", + * }) */ upsertShippingOptions( data: UpsertShippingOptionDTO, sharedContext?: Context ): Promise + + /** + * This method updates or creates shipping options if they don't exist. + * + * @param {UpsertShippingOptionDTO[]} data - The attributes in the shipping options to be created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created or updated shipping options. + * + * @example + * const shippingOptions = + * await fulfillmentModuleService.upsertShippingOptions([ + * { + * id: "so_123", + * name: "Express Shipping", + * }, + * { + * name: "Express Shipping", + * price_type: "flat", + * service_zone_id: "serzo_123", + * shipping_profile_id: "sp_123", + * provider_id: "webshipper", + * type: { + * label: "Express", + * description: "express shipping", + * code: "express", + * }, + * }, + * ]) + */ upsertShippingOptions( data: UpsertShippingOptionDTO[], sharedContext?: Context ): Promise + /** - * Delete a shippingOption - * @param ids - * @param sharedContext + * This method deletes shipping options by their IDs. + * + * @param {string[]} ids - The IDs of the shipping options. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping options are deleted successfully. + * + * @example + * await fulfillmentModuleService.deleteShippingOptions([ + * "so_123", + * "so_321", + * ]) */ deleteShippingOptions(ids: string[], sharedContext?: Context): Promise - deleteShippingOptions(id: string, sharedContext?: Context): Promise + /** - * Soft delete shipping options - * @param shippingOptionIds - * @param config - * @param sharedContext + * This method deletes a shipping option by its ID. + * + * @param {string} id - The ID of the shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping option is deleted successfully. + * + * @example + * await fulfillmentModuleService.deleteShippingOptions("so_123") + */ + deleteShippingOptions(id: string, sharedContext?: Context): Promise + + /** + * This method soft deletes shipping option by their IDs. + * + * @param {string[]} shippingOptionIds - The IDs of the shipping options. + * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted. + * If there are no related records, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.softDeleteShippingOptions([ + * "so_123", + * "so_321", + * ]) */ softDeleteShippingOptions( shippingOptionIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** - * Restore shipping options - * @param shippingOptionIds - * @param config - * @param sharedContext + * This method restores soft deleted shipping options by their IDs. + * + * @param {string[]} shippingOptionIds - The list of {summary} + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the shipping options. You can pass to its `returnLinkableKeys` + * property any of the shipping option's relation attribute names. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.restoreShippingOptions([ + * "so_123", + * "so_321", + * ]) */ restoreShippingOptions( shippingOptionIds: string[], @@ -437,87 +1454,304 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise | void> /** - * Retrieve a shipping profile - * @param id - * @param config - * @param sharedContext + * This method retrieves a shipping profile by its ID. + * + * @param {string} id - The ID of the shipping profile. + * @param {FindConfig} config - The configurations determining how the shipping profile is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping profile. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved shipping profile. + * + * @example + * A simple example that retrieves a shipping profile by its ID: + * + * ```ts + * const shippingProfile = + * await fulfillmentModuleService.retrieveShippingProfile( + * "sp_123" + * ) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const shippingProfile = + * await fulfillmentModuleService.retrieveShippingProfile( + * "sp_123", + * { + * relations: ["options"], + * } + * ) + * ``` */ retrieveShippingProfile( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List shipping profiles - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping profiles based on optional filters and configuration. + * + * @param {FilterableShippingProfileProps} filters - The filters to apply on the retrieved shipping profiles. + * @param {FindConfig} config - The configurations determining how the shipping profile is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping profile. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of shipping profiles. + * + * @example + * To retrieve a list of shipping profiles using their IDs: + * + * ```ts + * const shippingProfiles = + * await fulfillmentModuleService.listShippingProfiles({ + * id: ["sp_123", "sp_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the shipping profile: + * + * ```ts + * const shippingProfiles = + * await fulfillmentModuleService.listShippingProfiles( + * { + * id: ["sp_123", "sp_321"], + * }, + * { + * relations: ["shipping_options"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const shippingProfiles = + * await fulfillmentModuleService.listShippingProfiles( + * { + * id: ["sp_123", "sp_321"], + * }, + * { + * relations: ["shipping_options"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listShippingProfiles( filters?: FilterableShippingProfileProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count shipping profiles - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping profiles along with the total count of available shipping profiles satisfying the provided filters. + * + * @param {FilterableShippingProfileProps} filters - The filters to apply on the retrieved shipping profiles. + * @param {FindConfig} config - The configurations determining how the shipping profile is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping profile. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ShippingProfileDTO[], number]>} The list of shipping profiles along with their total count. + * + * @example + * To retrieve a list of shipping profiles using their IDs: + * + * ```ts + * const [shippingProfiles, count] = + * await fulfillmentModuleService.listAndCountShippingProfiles( + * { + * id: ["sp_123", "sp_321"], + * } + * ) + * ``` + * + * To specify relations that should be retrieved within the shipping profile: + * + * ```ts + * const [shippingProfiles, count] = + * await fulfillmentModuleService.listAndCountShippingProfiles( + * { + * id: ["sp_123", "sp_321"], + * }, + * { + * relations: ["shipping_options"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [shippingProfiles, count] = + * await fulfillmentModuleService.listAndCountShippingProfiles( + * { + * id: ["sp_123", "sp_321"], + * }, + * { + * relations: ["shipping_options"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listAndCountShippingProfiles( filters?: FilterableShippingProfileProps, config?: FindConfig, sharedContext?: Context ): Promise<[ShippingProfileDTO[], number]> + /** - * Create a new shipping profile - * @param data - * @param sharedContext + * This method creates shipping profiles. + * + * @param {CreateShippingProfileDTO[]} data - The shipping profiles to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created shipping profiles. + * + * @example + * const shippingProfiles = + * await fulfillmentModuleService.createShippingProfiles([ + * { + * name: "Default", + * }, + * { + * name: "Digital", + * }, + * ]) */ createShippingProfiles( data: CreateShippingProfileDTO[], sharedContext?: Context ): Promise + + /** + * This method creates a shipping profile. + * + * @param {CreateShippingProfileDTO} data - The shipping profile to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created shipping profile. + * + * @example + * const shippingProfile = + * await fulfillmentModuleService.createShippingProfiles({ + * name: "Default", + * }) + */ createShippingProfiles( data: CreateShippingProfileDTO, sharedContext?: Context ): Promise + /** - * Update a shipping profile - * @param data - * @param sharedContext + * This method updates existing shipping profiles. + * + * @param {CreateShippingProfileDTO[]} data - The shipping profiles to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated shipping profiles. + * + * @example + * const shippingProfiles = + * await fulfillmentModuleService.updateShippingProfiles([ + * { + * id: "sp_123", + * name: "Default", + * }, + * { + * id: "sp_321", + * name: "Digital", + * }, + * ]) */ updateShippingProfiles( data: UpdateShippingProfileDTO[], sharedContext?: Context ): Promise + + /** + * This method updates an existing shipping profiles. + * + * @param {CreateShippingProfileDTO} data - The shipping profile to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated shipping profiles. + * + * @example + * const shippingProfiles = + * await fulfillmentModuleService.updateShippingProfiles({ + * id: "sp_123", + * name: "Default", + * }) + */ updateShippingProfiles( data: UpdateShippingProfileDTO, sharedContext?: Context ): Promise + /** - * Delete a shipping profile - * @param ids - * @param sharedContext + * This method deletes shipping profiles by their IDs. + * + * @param {string[]} ids - The IDs of the shipping profiles. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping profiles are deleted. + * + * @example + * await fulfillmentModuleService.deleteShippingProfiles([ + * "sp_123", + * "sp_321", + * ]) */ deleteShippingProfiles(ids: string[], sharedContext?: Context): Promise - deleteShippingProfiles(id: string, sharedContext?: Context): Promise + /** - * Soft delete shipping profiles - * @param shippingProfileIds - * @param config - * @param sharedContext + * This method deletes a shipping profile by its ID. + * + * @param {string} id - The ID of the shipping profile. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping profile is deleted. + * + * @example + * await fulfillmentModuleService.deleteShippingProfiles( + * "sp_123" + * ) + */ + deleteShippingProfiles(id: string, sharedContext?: Context): Promise + + /** + * This method soft deletes shipping profiles by their IDs. + * + * @param {string[]} shippingProfileIds - The IDs of the shipping profiles. + * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted. + * If there are no related records, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.softDeleteShippingProfiles([ + * "sp_123", + * "sp_321", + * ]) */ softDeleteShippingProfiles( shippingProfileIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** - * Restore shipping profiles - * @param shippingProfileIds - * @param config - * @param sharedContext + * This method restores soft deleted shipping profiles by their IDs. + * + * @param {string[]} shippingProfileIds - The IDs of the shipping profiles. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the shipping profiles. You can pass to its `returnLinkableKeys` + * property any of the shipping profile's relation attribute names, such as `{type relation name}`. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. + * + * @example + * await fulfillmentModuleService.restoreShippingProfiles([ + * "sp_123", + * "sp_321", + * ]) */ restoreShippingProfiles( shippingProfileIds: string[], @@ -526,102 +1760,423 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise | void> /** - * Retrieve a shipping option rule - * @param id - * @param config - * @param sharedContext + * This method retrieves a shipping option rule by its ID. + * + * @param {string} id - The ID of the shipping option rule. + * @param {FindConfig} config - The configurations determining how the shipping option rule is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option rule. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved shipping option rule. + * + * @example + * A simple example that retrieves a shipping option rule by its ID: + * + * ```ts + * const shippingOptionRule = + * await fulfillmentModuleService.retrieveShippingOptionRule( + * "sorul_123" + * ) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const shippingOptionRule = + * await fulfillmentModuleService.retrieveShippingOptionRule( + * "sorul_123", + * { + * relations: ["shipping_option"], + * } + * ) + * ``` */ retrieveShippingOptionRule( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List shipping option rules - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping option rules based on optional filters and configuration. + * + * @param {FilterableShippingOptionRuleProps} filters - The filters to apply on the retrieved shipping option rules. + * @param {FindConfig} config - The configurations determining how the shipping option rule is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option rule. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of shipping option rules. + * + * @example + * To retrieve a list of shipping option rules using their IDs: + * + * ```ts + * const shippingOptionRules = + * await fulfillmentModuleService.listShippingOptionRules({ + * id: ["sorul_123", "sorul_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the shipping option rule: + * + * ```ts + * const shippingOptionRules = + * await fulfillmentModuleService.listShippingOptionRules( + * { + * id: ["sorul_123", "sorul_321"], + * }, + * { + * relations: ["shipping_option"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const shippingOptionRules = + * await fulfillmentModuleService.listShippingOptionRules( + * { + * id: ["sorul_123", "sorul_321"], + * }, + * { + * relations: ["shipping_option"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listShippingOptionRules( filters?: FilterableShippingOptionRuleProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count shipping option rules - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping option rules along with the total count of available shipping option rules satisfying the provided filters. + * + * @param {FilterableShippingOptionRuleProps} filters - The filters to apply on the retrieved shipping option rules. + * @param {FindConfig} config - The configurations determining how the shipping option rule is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option rule. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ShippingOptionRuleDTO[], number]>} The list of shipping option rules along with their total count. + * + * @example + * To retrieve a list of shipping option rules using their IDs: + * + * ```ts + * const [shippingOptionRules, count] = + * await fulfillmentModuleService.listAndCountShippingOptionRules( + * { + * id: ["sorul_123", "sorul_321"], + * } + * ) + * ``` + * + * To specify relations that should be retrieved within the shipping option rule: + * + * ```ts + * const [shippingOptionRules, count] = + * await fulfillmentModuleService.listAndCountShippingOptionRules( + * { + * id: ["sorul_123", "sorul_321"], + * }, + * { + * relations: ["shipping_option"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [shippingOptionRules, count] = + * await fulfillmentModuleService.listAndCountShippingOptionRules( + * { + * id: ["sorul_123", "sorul_321"], + * }, + * { + * relations: ["shipping_option"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listAndCountShippingOptionRules( filters?: FilterableShippingOptionRuleProps, config?: FindConfig, sharedContext?: Context ): Promise<[ShippingOptionRuleDTO[], number]> + /** - * Create a new shipping option rules - * @param data - * @param sharedContext + * This method creates shipping option rules. + * + * @param {CreateShippingOptionRuleDTO[]} data - The shipping option rules to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created shipping option rules. + * + * @example + * const shippingOptionRules = + * await fulfillmentModuleService.createShippingOptionRules([ + * { + * attribute: "customer_group", + * operator: "in", + * value: "cg_vipgroup", + * shipping_option_id: "so_123", + * }, + * { + * attribute: "total_weight", + * operator: "lt", + * value: "2000", + * shipping_option_id: "so_321", + * }, + * ]) */ createShippingOptionRules( data: CreateShippingOptionRuleDTO[], sharedContext?: Context ): Promise + + /** + * This method creates a shipping option rule. + * + * @param {CreateShippingOptionRuleDTO} data - The shipping option rule to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created shipping option rule. + * + * @example + * const shippingOptionRule = + * await fulfillmentModuleService.createShippingOptionRules({ + * attribute: "customer_group", + * operator: "in", + * value: "cg_vipgroup", + * shipping_option_id: "so_123", + * }) + */ createShippingOptionRules( data: CreateShippingOptionRuleDTO, sharedContext?: Context ): Promise + /** - * Update a shipping option rule - * @param data - * @param sharedContext + * This method updates existing shipping option rules. + * + * @param {UpdateShippingOptionRuleDTO[]} data - The attributes to update in the shipping option rules. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated shipping option rules. + * + * @example + * const shippingOptionRules = + * await fulfillmentModuleService.updateShippingOptionRules([ + * { + * id: "sorul_123", + * operator: "in", + * }, + * { + * id: "sorul_321", + * attribute: "customer_group", + * value: "cp_vipgroup", + * }, + * ]) */ updateShippingOptionRules( data: UpdateShippingOptionRuleDTO[], sharedContext?: Context ): Promise + + /** + * This method updates an existing shipping option rule. + * + * @param {UpdateShippingOptionRuleDTO} data - The attributes to update in the shipping option rule. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated shipping option rule. + * + * @example + * const shippingOptionRule = + * await fulfillmentModuleService.updateShippingOptionRules({ + * id: "sorul_123", + * operator: "in", + * }) + */ updateShippingOptionRules( data: UpdateShippingOptionRuleDTO, sharedContext?: Context ): Promise + /** - * Delete a shipping option rule - * @param ids - * @param sharedContext + * This method deletes shipping option rules by their IDs. + * + * @param {string[]} ids - The IDs of the shipping option rules. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping option rules are deleted successfully. + * + * @example + * await fulfillmentModuleService.deleteShippingOptionRules([ + * "sorul_123", + * "sorul_321", + * ]) */ deleteShippingOptionRules( ids: string[], sharedContext?: Context ): Promise + + /** + * This method deletes a shipping option by its ID. + * + * @param {string} id - The ID of the shipping option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping option is deleted successfully. + * + * @example + * await fulfillmentModuleService.deleteShippingOptionRules( + * "sorul_123" + * ) + */ deleteShippingOptionRules(id: string, sharedContext?: Context): Promise /** - * Retrieve a shipping option type - * @param id - * @param config - * @param sharedContext + * This method retrieves a shipping option type by its ID. + * + * @param {string} id - The ID of the shipping option type. + * @param {FindConfig} config - The configurations determining how the shipping option type is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved shipping option type. + * + * @example + * A simple example that retrieves a shipping option type by its ID: + * + * ```ts + * const shippingOptionType = + * await fulfillmentModuleService.retrieveShippingOptionType( + * "sotype_123" + * ) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const shippingOptionType = + * await fulfillmentModuleService.retrieveShippingOptionType( + * "sotype_123", + * { + * relations: ["shipping_option"], + * } + * ) + * ``` */ retrieveShippingOptionType( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List shipping option types - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping option types based on optional filters and configuration. + * + * @param {FilterableShippingOptionTypeProps} filters - The filters to apply on the retrieved shipping option types. + * @param {FindConfig} config - The configurations determining how the shipping option type is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of shipping option types. + * + * @example + * To retrieve a list of shipping option types using their IDs: + * + * ```ts + * const shippingOptionTypes = + * await fulfillmentModuleService.listShippingOptionTypes({ + * id: ["sotype_123", "sotype_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the shipping option type: + * + * ```ts + * const shippingOptionTypes = + * await fulfillmentModuleService.listShippingOptionTypes( + * { + * id: ["sotype_123", "sotype_321"], + * }, + * { + * relations: ["shipping_option"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const shippingOptionTypes = + * await fulfillmentModuleService.listShippingOptionTypes( + * { + * id: ["sotype_123", "sotype_321"], + * }, + * { + * relations: ["shipping_option"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listShippingOptionTypes( filters?: FilterableShippingOptionTypeProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count shipping options types - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of shipping option types along with the total count of available shipping option types satisfying the provided filters. + * + * @param {FilterableShippingOptionTypeProps} filters - The filters to apply on the retrieved shipping option types. + * @param {FindConfig} config - The configurations determining how the shipping option type is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a shipping option type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ShippingOptionTypeDTO[], number]>} The list of shipping option types along with their total count. + * + * @example + * To retrieve a list of shipping option types using their IDs: + * + * ```ts + * const [shippingOptionTypes, count] = + * await fulfillmentModuleService.listAndCountShippingOptionTypes( + * { + * id: ["sotype_123", "sotype_321"], + * } + * ) + * ``` + * + * To specify relations that should be retrieved within the shipping option type: + * + * ```ts + * const [shippingOptionTypes, count] = + * await fulfillmentModuleService.listAndCountShippingOptionTypes( + * { + * id: ["sotype_123", "sotype_321"], + * }, + * { + * relations: ["shipping_option"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [shippingOptionTypes, count] = + * await fulfillmentModuleService.listAndCountShippingOptionTypes( + * { + * id: ["sotype_123", "sotype_321"], + * }, + * { + * relations: ["shipping_option"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listAndCountShippingOptionTypes( filters?: FilterableShippingOptionTypeProps, @@ -630,72 +2185,256 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise<[ShippingOptionTypeDTO[], number]> /** - * delete a shipping option type - * @param ids - * @param sharedContext + * This method deletes shipping option types by their IDs. + * + * @param {string[]} ids - The IDs of the shipping option types. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping option types are deleted successfully. + * + * @example + * await fulfillmentModuleService.deleteShippingOptionTypes([ + * "sotype_123", + * "sotype_321", + * ]) */ deleteShippingOptionTypes( ids: string[], sharedContext?: Context ): Promise + + /** + * This method deletes a shipping option type by its ID. + * + * @param {string} id - The ID of the shipping option type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the shipping option type is deleted. + * + * @example + * await fulfillmentModuleService.deleteShippingOptionTypes( + * "sotype_123" + * ) + */ deleteShippingOptionTypes(id: string, sharedContext?: Context): Promise /** - * Retrieve a fulfillment - * @param id - * @param config - * @param sharedContext + * This method retrieves a fulfillment by its ID. + * + * @param {string} id - The ID of the fulfillment. + * @param {FindConfig} config - The configurations determining how the fulfillment is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a fulfillment. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved fulfillment. + * + * @example + * A simple example that retrieves a fulfillment by its ID: + * + * ```ts + * const fulfillment = + * await fulfillmentModuleService.retrieveFulfillment( + * "ful_123" + * ) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * const fulfillment = + * await fulfillmentModuleService.retrieveFulfillment( + * "ful_123", + * { + * relations: ["shipping_option"], + * } + * ) + * ``` */ retrieveFulfillment( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List fulfillments - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of fulfillments based on optional filters and configuration. + * + * @param {FilterableFulfillmentSetProps} filters - The filters to apply on the retrieved fulfillments. + * @param {FindConfig} config - The configurations determining how the fulfillment is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a fulfillment. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of fulfillments. + * + * @example + * To retrieve a list of fulfillments using their IDs: + * + * ```ts + * const fulfillments = + * await fulfillmentModuleService.listFulfillments({ + * id: ["ful_123", "ful_321"], + * }) + * ``` + * + * To specify relations that should be retrieved within the fulfillment: + * + * ```ts + * const fulfillments = + * await fulfillmentModuleService.listFulfillments( + * { + * id: ["ful_123", "ful_321"], + * }, + * { + * relations: ["shipping_option"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const fulfillments = + * await fulfillmentModuleService.listFulfillments( + * { + * id: ["ful_123", "ful_321"], + * }, + * { + * relations: ["shipping_option"], + * take: 20, + * skip: 2, + * } + * ) + * ``` */ listFulfillments( filters?: FilterableFulfillmentProps, config?: FindConfig, sharedContext?: Context ): Promise + /** - * List and count fulfillments - * @param filters - * @param config - * @param sharedContext + * This method retrieves a paginated list of fulfillments along with the total count of available fulfillments satisfying the provided filters. + * + * @param {FilterableFulfillmentSetProps} filters - The filters to apply on the retrieved fulfillment sets. + * @param {FindConfig} config - The configurations determining how the fulfillment is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a fulfillment. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[FulfillmentDTO[], number]>} The list of fulfillments along with their total count. + * + * @example + * To retrieve a list of fulfillments using their IDs: + * + * ```ts + * const [fulfillments, count] = + * await fulfillmentModuleService.listAndCountFulfillments( + * { + * id: ["ful_123", "ful_321"], + * }, + * { + * relations: ["shipping_option"], + * take: 20, + * skip: 2, + * } + * ) + * ``` + * + * To specify relations that should be retrieved within the fulfillment: + * + * ```ts + * const [fulfillments, count] = + * await fulfillmentModuleService.listAndCountFulfillments( + * { + * id: ["ful_123", "ful_321"], + * }, + * { + * relations: ["shipping_option"], + * } + * ) + * ``` + * + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * + * ```ts + * const [fulfillments, count] = + * await fulfillmentModuleService.listAndCountFulfillments({ + * id: ["ful_123", "ful_321"], + * }) + * ``` */ listAndCountFulfillments( filters?: FilterableFulfillmentProps, config?: FindConfig, sharedContext?: Context ): Promise<[FulfillmentDTO[], number]> + /** - * Create a new fulfillment including into the third party provider - * @param data - * @param sharedContext + * This method creates a fulfillment. + * + * @param {CreateFulfillmentDTO} data - The fulfillment to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created fulfillment. + * + * @example + * const fulfillment = + * await fulfillmentModuleService.createFulfillment({ + * location_id: "loc_123", + * provider_id: "webshipper", + * delivery_address: { + * address_1: "4120 Auto Park Cir", + * country_code: "us", + * }, + * items: [ + * { + * title: "Shirt", + * sku: "SHIRT", + * quantity: 1, + * barcode: "ABCED", + * }, + * ], + * labels: [ + * { + * tracking_number: "1234567", + * tracking_url: "https://example.com/tracking", + * label_url: "https://example.com/label", + * }, + * ], + * order: {}, + * }) */ createFulfillment( data: CreateFulfillmentDTO, sharedContext?: Context ): Promise + /** - * Update a fulfillment - * @param data - * @param sharedContext + * This method updates an existing fulfillment. + * + * @param {string} id - The ID of the fulfillment. + * @param {UpdateFulfillmentDTO} data - The attributes to update in the fulfillment. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated fulfillment. + * + * @example + * const fulfillment = + * await fulfillmentModuleService.updateFulfillment( + * "ful_123", + * { + * location_id: "loc_123", + * } + * ) */ updateFulfillment( id: string, data: UpdateFulfillmentDTO, sharedContext?: Context ): Promise + /** - * Cancel the given fulfillment including into the third party provider - * @param id - * @param sharedContext + * This method cancels a fulfillment. + * + * @param {string} id - The ID of the fulfillment. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} cancels a fulfillment. + * + * @example + * const fulfillment = + * await fulfillmentModuleService.cancelFulfillment("ful_123") */ cancelFulfillment( id: string, @@ -703,14 +2442,36 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise /** - * Retrieve the available fulfillment options for the given data. + * This method retrieves the fulfillment options of a fulfillment provider. + * + * @param {string} providerId - The fulfillment provider's ID. + * @returns {Promise[]>} The fulfillment provider's options. + * + * @example + * const fulfillment = + * await fulfillmentModuleService.retrieveFulfillmentOptions( + * "ful_123" + * ) */ retrieveFulfillmentOptions( providerId: string ): Promise[]> /** - * Validate the given shipping option fulfillment option from the provided data + * This method validates a fulfillment option with the provider it belongs to. + * + * @param {string} providerId - The fulfillment provider's ID. + * @param {Record} data - The fulfillment option to validate. + * @returns {Promise} Whether the fulfillment option is valid with the specified provider. + * + * @example + * const isValid = + * await fulfillmentModuleService.validateFulfillmentOption( + * "webshipper", + * { + * code: "express", + * } + * ) */ validateFulfillmentOption( providerId: string, @@ -718,7 +2479,20 @@ export interface IFulfillmentModuleService extends IModuleService { ): Promise /** - * Validate if the given shipping option is valid for a given context + * This method checks whether a shipping option can be used for a specified context. + * + * @param {string} shippingOptionId - The shipping option's ID. + * @param {Record} context - The context to check. + * @returns {Promise} Whether the shipping option is valid for the specified context. + * + * @example + * const isValid = + * await fulfillmentModuleService.validateShippingOption( + * "so_123", + * { + * customer_group: "cg_vipgroup", + * } + * ) */ validateShippingOption( shippingOptionId: string,