@acmekit/utils 2.13.2 → 2.13.3

package/dist/fulfillment/provider.d.ts

@@ -1,394 +0,0 @@
-import { CalculatedShippingOptionPrice, CalculateShippingOptionPriceDTO, CreateFulfillmentResult, CreateShippingOptionDTO, FulfillmentDTO, FulfillmentItemDTO, FulfillmentOption, FulfillmentOrderDTO, IFulfillmentProvider, ValidateFulfillmentDataContext } from "@acmekit/types";
-/**
- * ### constructor
- *
- * The constructor allows you to access resources from the [module's container](https://docs.acmekit.com/learn/fundamentals/modules/container)
- * using the first parameter, and the module's options using the second parameter.
- *
- * :::note
- *
- * A module's options are passed when you register it in the AcmeKit application.
- *
- * :::
- *
- * If you're creating a client or establishing a connection with a third-party service, do it in the constructor.
- *
- * #### Example
- *
- * ```ts title="src/modules/my-fulfillment/service.ts"
- * import { AbstractFulfillmentProviderService } from "@acmekit/framework/utils"
- * import { Logger } from "@acmekit/framework/types"
- *
- * type InjectedDependencies = {
- *   logger: Logger
- * }
- *
- * type Options = {
- *   apiKey: string
- * }
- *
- * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
- * // other properties...
- *   protected logger_: Logger
- *   protected options_: Options
- *   // assuming you're initializing a client
- *   protected client
- *
- *   constructor(
- *     { logger }: InjectedDependencies,
- *     options: Options
- *   ) {
- *     super()
- *
- *     this.logger_ = logger
- *     this.options_ = options
- *
- *     // TODO initialize your client
- *   }
- * }
- *
- * export default MyFulfillmentProviderService
- * ```
- */
-export declare class AbstractFulfillmentProviderService implements IFulfillmentProvider {
-    /**
-     * Each fulfillment provider has a unique identifier defined in its class. The provider's ID
-     * will be stored as `fp_{identifier}_{id}`, where `{id}` is the provider's `id`
-     * property in the `acmekit-config.ts`.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   static identifier = "my-fulfillment"
-     *
-     *   // ...
-     * }
-     */
-    static identifier: string;
-    /**
-     * @ignore
-     */
-    static _isFulfillmentService: boolean;
-    /**
-     * @ignore
-     */
-    static isFulfillmentService(obj: any): any;
-    /**
-     * @ignore
-     */
-    getIdentifier(): any;
-    /**
-     * This method retrieves a list of fulfillment options that this provider supports. Admin users will then choose from these options when
-     * they're creating a shipping option. The chosen fulfillment option's object is then stored within the created shipping option's `data` property.
-     * The `data` property is useful to store data relevant for the third-party provider to later process the fulfillment.
-     *
-     * This method is useful if your third-party provider allows you to retrieve support options, carriers, or services from an API. You can then
-     * retrieve those and return then in the method, allowing the admin user to choose from the services provided by the third-party provider.
-     *
-     * @returns The list of fulfillment options. Each object in the array should have an `id` property unique to an item, and a `name` property
-     * that's used to display the option in the admin.
-     *
-     * @example
-     * // other imports...
-     * import { FulfillmentOption } from "@acmekit/framework/types"
-     *
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async getFulfillmentOptions(): Promise<FulfillmentOption[]> {
-     *     // assuming you have a client
-     *     const services = await this.client.getServices()
-     *
-     *     return services.map((service) => ({
-     *       id: service.service_id,
-     *       name: service.name,
-     *       service_code: service.code,
-     *       // can add other relevant data for the provider to later process the shipping option.
-     *     }))
-     *   }
-     * }
-     */
-    getFulfillmentOptions(): Promise<FulfillmentOption[]>;
-    /**
-     * This method validates the `data` property of a shipping method and returns it. The returned data
-     * is stored in the shipping method's `data` property.
-     *
-     * Your fulfillment provider can use the `data` property to store additional information useful for
-     * handling the fulfillment later. For example, you may store an ID from the third-party fulfillment
-     * system.
-     *
-     * @param optionData - The `data` property of the shipping option.
-     * @param data - The `data` property of the shipping method.
-     * @param context - Context details, such as context of the cart or customer.
-     * @returns the data to store in the `data` property of the shipping method.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async validateFulfillmentData(
-     *     optionData: any,
-     *     data: any,
-     *     context: any
-     *   ): Promise<any> {
-     *     // assuming your client retrieves an ID from the
-     *     // third-party service
-     *     const externalId = await this.client.getId()
-     *
-     *     return {
-     *       ...data,
-     *       externalId
-     *     }
-     *   }
-     * }
-     */
-    validateFulfillmentData(optionData: Record<string, unknown>, data: Record<string, unknown>, context: ValidateFulfillmentDataContext): Promise<any>;
-    /**
-     * This method validates the `data` property of a shipping option when it's created.
-     *
-     * The `data` property can hold useful information that's later added to the `data` attribute
-     * of shipping methods created from this option.
-     *
-     * @param data - The data to validate.
-     * @return Whether the data is valid.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async validateOption(data: any): Promise<boolean> {
-     *     return data.external_id !== undefined
-     *   }
-     * }
-     */
-    validateOption(data: Record<string, unknown>): Promise<boolean>;
-    /**
-     * This method validates whether a shippin option's price can be calculated during checkout. It's executed when the admin user creates a shipping
-     * option of type `calculated`. If this method returns `false`, an error is thrown as the shipping option's price can't be calculated.
-     *
-     * You can perform the checking using the third-party provider if applicable. The `data` parameter will hold the shipping option's `data` property, which
-     * includes the data of a fulfillment option returned by {@link getFulfillmentOptions}.
-     *
-     * @param data - The `data` property of the shipping option.
-     * @returns Whether the price can be calculated for the shipping option.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async canCalculate(data: CreateShippingOptionDTO): Promise<boolean> {
-     *     // assuming you have a client
-     *     return await this.client.hasRates(data.id)
-     *   }
-     * }
-     */
-    canCalculate(data: CreateShippingOptionDTO): Promise<boolean>;
-    /**
-     * This method calculates the price of a shipping method when it's created or its cart is refreshed.
-     *
-     * In this method, you can send a request to your third-party provider to retrieve the prices. The first
-     * parameters holds the `data` property of the shipping method's shipping option, which has fulfillment
-     * object data returned by {@link getFulfillmentOptions}.
-     *
-     * The second parameter holds the `data` property of the shipping method, which has data returned by {@link validateFulfillmentData}.
-     * It can also hold custom data passed from the frontend during checkout.
-     *
-     * So, using both of these data, assuming you're storing in them data related to the third-party service,
-     * you can retrieve the calculated price of the shipping method.
-     *
-     * @param optionData - The `data` property of a shipping option.
-     * @param data - The shipping method's `data` property with custom data passed from the frontend.
-     * @param context - The context details, such as the cart details.
-     * @returns The calculated price's details.
-     *
-     * @example
-     * import { CalculateShippingOptionPriceDTO } from "@acmekit/framework/types"
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async calculatePrice(
-     *     optionData: CalculateShippingOptionPriceDTO["optionData"],
-     *     data: CalculateShippingOptionPriceDTO["data"],
-     *     context: CalculateShippingOptionPriceDTO["context"]
-     *   ): Promise<CalculatedShippingOptionPrice> {
-     *     // assuming the client can calculate the price using
-     *     // the third-party service
-     *     const price = await this.client.calculate(data)
-     *     return {
-     *       calculated_amount: price,
-     *       // Update this boolean value based on your logic
-     *       is_calculated_price_tax_inclusive: true,
-     *     }
-     *   }
-     * }
-     */
-    calculatePrice(optionData: CalculateShippingOptionPriceDTO["optionData"], data: CalculateShippingOptionPriceDTO["data"], context: CalculateShippingOptionPriceDTO["context"]): Promise<CalculatedShippingOptionPrice>;
-    /**
-     * This method is used when a fulfillment is created. If the method returns in the object a
-     * `data` property, it's stored in the fulfillment's `data` property.
-     *
-     * The `data` property is useful when handling the fulfillment later,
-     * as you can access information useful for your integration, such as the ID in the
-     * third-party provider.
-     *
-     * You can also use this method to perform an action with the third-party fulfillment service
-     * since a fulfillment is created, such as purchase a label.
-     *
-     * @param data - The `data` property of the shipping method this fulfillment is created for.
-     * @param items - The items in the fulfillment.
-     * @param order - The order this fulfillment is created for.
-     * @param fulfillment - The fulfillment's details.
-     * @returns An object whose `data` property is stored in the fulfillment's `data` property.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async createFulfillment(
-     *     data: Record<string, unknown>,
-     *     items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
-     *     order: Partial<FulfillmentOrderDTO> | undefined,
-     *     fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
-     *   ): Promise<CreateFulfillmentResult> {
-     *     // assuming the client creates a fulfillment
-     *     // in the third-party service
-     *     const externalData = await this.client.create(
-     *       fulfillment,
-     *       items
-     *     )
-     *
-     *     return {
-     *       data: {
-     *         ...(fulfillment.data as object || {}),
-     *         ...externalData
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    createFulfillment(data: Record<string, unknown>, items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[], order: Partial<FulfillmentOrderDTO> | undefined, fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>): Promise<CreateFulfillmentResult>;
-    /**
-     * This method is used when a fulfillment is canceled. Use it to perform operations
-     * with the third-party fulfillment service.
-     *
-     * @param data - The fulfillment's `data` property.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async cancelFulfillment(data: Record<string, unknown>): Promise<any> {
-     *     // assuming the client cancels a fulfillment
-     *     // in the third-party service
-     *     const { external_id } = data as {
-     *       external_id: string
-     *     }
-     *     await this.client.cancel(external_id)
-     *   }
-     * }
-     */
-    cancelFulfillment(data: Record<string, unknown>): Promise<any>;
-    /**
-     * This method retrieves the documents of a fulfillment.
-     *
-     * @param data - The `data` property of the fulfillment.
-     * @returns The fulfillment's documents.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async getFulfillmentDocuments(data: any): Promise<never[]> {
-     *     // assuming the client retrieves documents
-     *     // from a third-party service
-     *     return await this.client.documents(data)
-     *   }
-     * }
-     */
-    getFulfillmentDocuments(data: Record<string, unknown>): Promise<never[]>;
-    /**
-     * This method is used when a fulfillment is created for a return. If the method returns in the object a
-     * `data` property, it's stored in the fulfillment's `data` property.
-     *
-     * The `data` property is useful when handling the fulfillment later,
-     * as you can access information useful for your integration. For example, you
-     * can store an ID for the fulfillment in the third-party service.
-     *
-     * Use this method to perform actions necessary in the third-party fulfillment service, such as
-     * purchasing a label for the return fulfillment.
-     *
-     * @param fulfillment - The fulfillment's details.
-     * @returns An object containing `data` which is stored in the fulfillment's `data` property and `labels` array which is used to create FulfillmentLabels.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async createReturnFulfillment(fulfillment: Record<string, unknown>): Promise<CreateFulfillmentResult> {
-     *     // assuming the client creates a fulfillment for a return
-     *     // in the third-party service
-     *     const externalData = await this.client.createReturn(
-     *       fulfillment
-     *     )
-     *
-     *     return {
-     *       data: {
-     *         ...(fulfillment.data as object || {}),
-     *         ...externalData
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    createReturnFulfillment(fulfillment: Record<string, unknown>): Promise<CreateFulfillmentResult>;
-    /**
-     * This method retrieves documents for a return's fulfillment.
-     *
-     * @param data - The `data` property of the fulfillment.
-     * @returns The fulfillment's documents.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async getReturnDocuments(data: any): Promise<never[]> {
-     *     // assuming the client retrieves documents
-     *     // from a third-party service
-     *     return await this.client.documents(data)
-     *   }
-     * }
-     */
-    getReturnDocuments(data: Record<string, unknown>): Promise<never[]>;
-    /**
-     * This method retrieves the documents for a shipment.
-     *
-     * @param data - The `data` property of the shipmnet.
-     * @returns The shipment's documents.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async getShipmentDocuments(data: any): Promise<never[]> {
-     *     // assuming the client retrieves documents
-     *     // from a third-party service
-     *     return await this.client.documents(data)
-     *   }
-     * }
-     *
-     */
-    getShipmentDocuments(data: Record<string, unknown>): Promise<never[]>;
-    /**
-     * This method retrieves the documents of a fulfillment of a certain type.
-     *
-     * @param fulfillmentData - The `data` property of the fulfillment.
-     * @param documentType - The document's type. For example, `invoice`.
-     * @returns The fulfillment's documents.
-     *
-     * @example
-     * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
-     *   // ...
-     *   async retrieveDocuments(
-     *     fulfillmentData: any,
-     *     documentType: any
-     *   ): Promise<void> {
-     *     // assuming the client retrieves documents
-     *     // from a third-party service
-     *     return await this.client.documents(
-     *       fulfillmentData,
-     *       documentType
-     *     )
-     *   }
-     * }
-     */
-    retrieveDocuments(fulfillmentData: Record<string, unknown>, documentType: string): Promise<void>;
-}
-//# sourceMappingURL=provider.d.ts.map

package/dist/fulfillment/provider.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/fulfillment/provider.ts"],"names":[],"mappings":"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"}