feat(docs): Add documentation about FulfillmentHandler

docs/content/docs/developer-guide/shipping.md

@@ -133,7 +133,17 @@ If your ShippingEligibilityChecker or ShippingCalculator needs access to the dat
 
 ## Fulfillments
 
-Fulfillments represent the actual shipping status of items in an order. Like Orders, Fulfillments are governed by a [finite state machine]({{< relref "fsm" >}}) and by default, a Fulfillment can be in one of the [following states]({{< relref "fulfillment-state" >}}):
+Fulfillments represent the actual shipping status of items in an order. When an order is placed and payment has been settled, the order items are then delivered to the customer in one or more Fulfillments.
+
+### FulfillmentHandlers
+
+It is often required to integrate your fulfillment process, e.g. with an external shipping API which provides shipping labels or tracking codes. This is done by defining [FulfillmentHandlers]({{< relref "fulfillment-handler" >}}) (click the link for full documentation) and passing them in to the `shippingOptions.fulfillmentHandlers` array in your config.
+
+By default, Vendure uses a manual fulfillment handler, which requires the Administrator to manually enter the method and tracking code of the Fulfillment.
+
+### Fulfillment state machine
+
+Like Orders, Fulfillments are governed by a [finite state machine]({{< relref "fsm" >}}) and by default, a Fulfillment can be in one of the [following states]({{< relref "fulfillment-state" >}}):
 
 * `Pending` The Fulfillment has been created
 * `Shipped` The Fulfillment has been shipped

packages/core/src/config/fulfillment/fulfillment-handler.ts

@@ -17,6 +17,11 @@ import {
 } from '../../service/helpers/fulfillment-state-machine/fulfillment-state';
 import { CalculateShippingFnResult } from '../shipping-method/shipping-calculator';
 
+/**
+ * @docsCategory fulfillment
+ * @docsPage FulfillmentHandler
+ * @docsWeight 3
+ */
 export type CreateFulfillmentResult = Partial<Pick<Fulfillment, 'trackingCode' | 'method' | 'customFields'>>;
 
 /**
@@ -25,6 +30,7 @@ export type CreateFulfillmentResult = Partial<Pick<Fulfillment, 'trackingCode' |
  *
  * @docsCategory fulfillment
  * @docsPage FulfillmentHandler
+ * @docsWeight 2
  */
 export type CreateFulfillmentFn<T extends ConfigArgs> = (
     ctx: RequestContext,
@@ -39,9 +45,27 @@ export type CreateFulfillmentFn<T extends ConfigArgs> = (
  *
  * @docsCategory fulfillment
  * @docsPage FulfillmentHandler
+ * @docsWeight 1
  */
 export interface FulfillmentHandlerConfig<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {
+    /**
+     * @description
+     * Invoked when the `addFulfillmentToOrder` mutation is executed with this handler selected.
+     *
+     * If an Error is thrown from within this function, no Fulfillment is created and the `CreateFulfillmentError`
+     * result will be returned.
+     */
     createFulfillment: CreateFulfillmentFn<T>;
+    /**
+     * @description
+     * This allows the handler to intercept state transitions of the created Fulfillment. This works much in the
+     * same way as the {@link CustomFulfillmentProcess} `onTransitionStart` method (i.e. returning `false` or
+     * `string` will be interpreted as an error and prevent the state transition), except that it is only invoked
+     * on Fulfillments which were created with this particular FulfillmentHandler.
+     *
+     * It can be useful e.g. to intercept Fulfillment cancellations and relay that information to a 3rd-party
+     * shipping API.
+     */
     onFulfillmentTransition?: OnTransitionStartFn<FulfillmentState, FulfillmentTransitionData>;
 }
 
@@ -69,7 +93,8 @@ export interface FulfillmentHandlerConfig<T extends ConfigArgs> extends Configur
  *   args: {
  *     preferredService: {
  *       type: 'string',
- *       config: {
+ *       ui: {
+           component: 'select-form-input',
  *         options: [
  *           { value: 'first_class' },
  *           { value: 'priority'},
@@ -85,16 +110,22 @@ export interface FulfillmentHandlerConfig<T extends ConfigArgs> extends Configur
  *   },
  *
  *   createFulfillment: async (ctx, orders, orderItems, args) => {
+ *
  *      const shipment = getShipmentFromOrders(orders, orderItems);
+ *
  *      try {
  *        const transaction = await shipomatic.transaction.create({
  *          shipment,
  *          service_level: args.preferredService,
  *          label_file_type: 'png',
  *        })
+ *
  *        return {
- *          method: args.method,
- *          trackingCode: args.trackingCode,
+ *          method: `Ship-o-matic ${args.preferredService}`,
+ *          trackingCode: transaction.tracking_code,
+ *          customFields: {
+ *            shippingTransactionId: transaction.id,
+ *          }
  *        };
  *      } catch (e) {
  *        // Errors thrown from within this function will
@@ -106,7 +137,7 @@ export interface FulfillmentHandlerConfig<T extends ConfigArgs> extends Configur
  *   onFulfillmentTransition: async (fromState, toState, { fulfillment }) => {
  *     if (toState === 'Cancelled') {
  *       await shipomatic.transaction.cancel({
- *         tracking_code: fulfillment.trackingCode,
+ *         transaction_id: fulfillment.customFields.shippingTransactionId,
  *       });
  *     }
  *   }