@deenruv/core 1.0.0

package/dist/config/entity/entity-id-strategy.d.ts

@@ -0,0 +1,55 @@
+import { InjectableStrategy } from "../../common/types/injectable-strategy";
+export type PrimaryKeyType<T> = T extends "uuid" ? string : T extends "increment" ? number : any;
+/**
+ * @description
+ * The EntityIdStrategy determines how entity IDs are generated and stored in the
+ * database, as well as how they are transformed when being passed from the API to the
+ * service layer and vice versa.
+ *
+ * Deenruv ships with two strategies: {@link AutoIncrementIdStrategy} and {@link UuidIdStrategy},
+ * but custom strategies can be used, e.g. to apply some custom encoding to the ID before exposing
+ * it in the GraphQL API.
+ *
+ * :::info
+ *
+ * This is configured via the `entityOptions.entityIdStrategy` property of
+ * your DeenruvConfig.
+ *
+ * :::
+ *
+ * :::caution
+ * Note: changing from an integer-based strategy to a uuid-based strategy
+ * on an existing Deenruv database will lead to problems with broken foreign-key
+ * references. To change primary key types like this, you'll need to start with
+ * a fresh database.
+ * :::
+ *
+ * @docsCategory configuration
+ * @docsPage EntityIdStrategy
+ * */
+export interface EntityIdStrategy<T extends "increment" | "uuid"> extends InjectableStrategy {
+    /**
+     * @description
+     * Defines how the primary key will be stored in the database - either
+     * `'increment'` for auto-increment integer IDs, or `'uuid'` for a unique
+     * string ID.
+     */
+    readonly primaryKeyType: T;
+    /**
+     * @description
+     * Allows the raw ID from the database to be transformed in some way before exposing
+     * it in the GraphQL API.
+     *
+     * For example, you may need to use auto-increment integer IDs due to some business
+     * constraint, but you may not want to expose this data publicly in your API. In this
+     * case, you can use the encode/decode methods to obfuscate the ID with some kind of
+     * encoding scheme, such as base64 (or something more sophisticated).
+     */
+    encodeId: (primaryKey: PrimaryKeyType<T>) => string;
+    /**
+     * @description
+     * Reverses the transformation performed by the `encodeId` method in order to get
+     * back to the raw ID value.
+     */
+    decodeId: (id: string) => PrimaryKeyType<T>;
+}

package/dist/config/entity/entity-id-strategy.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=entity-id-strategy.js.map

package/dist/config/entity/entity-id-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-id-strategy.js","sourceRoot":"","sources":["../../../src/config/entity/entity-id-strategy.ts"],"names":[],"mappings":""}

package/dist/config/entity/money-strategy.d.ts

@@ -0,0 +1,99 @@
+import { ColumnOptions } from "typeorm";
+import { InjectableStrategy } from "../../common/types/injectable-strategy";
+/**
+ * @description
+ * The MoneyStrategy defines how monetary values are stored and manipulated. The MoneyStrategy
+ * is defined in {@link EntityOptions}:
+ *
+ * @example
+ * ```ts
+ * const config: DeenruvConfig = {
+ *   entityOptions: {
+ *     moneyStrategy: new MyCustomMoneyStrategy(),
+ *   }
+ * };
+ * ```
+ *
+ * ## Range
+ *
+ * The {@link DefaultMoneyStrategy} uses an `int` field in the database, which puts an
+ * effective limit of ~21.4 million on any stored value. For certain use cases
+ * (e.g. business sales with very high amounts, or currencies with very large
+ * denominations), this may cause issues. In this case, you can use the
+ * {@link BigIntMoneyStrategy} which will use the `bigint` type to store monetary values,
+ * giving an effective upper limit of over 9 quadrillion.
+ *
+ * ## Precision
+ *
+ * Both the `DefaultMoneyStrategy` and `BigIntMoneyStrategy` store monetary values as integers, representing
+ * the price in the minor units of the currency (i.e. _cents_ in USD or _pennies_ in GBP).
+ *
+ * Since v2.2.0, you can configure the precision of the stored values via the `precision` property of the
+ * strategy. Changing the precision has **no effect** on the stored value. It is merely a hint to the
+ * UI as to how many decimal places to display.
+ *
+ * @example
+ * ```ts
+ * import { DefaultMoneyStrategy, DeenruvConfig } from '\@deenruv/core';
+ *
+ * export class ThreeDecimalPlacesMoneyStrategy extends DefaultMoneyStrategy {
+ *   readonly precision = 3;
+ * }
+ *
+ * export const config: DeenruvConfig = {
+ *   // ...
+ *   entityOptions: {
+ *     moneyStrategy: new ThreeDecimalPlacesMoneyStrategy(),
+ *   }
+ * };
+ * ```
+ *
+ * :::info
+ *
+ * This is configured via the `entityOptions.moneyStrategy` property of
+ * your DeenruvConfig.
+ *
+ * :::
+ *
+ * @docsCategory money
+ * @since 2.0.0
+ */
+export interface MoneyStrategy extends InjectableStrategy {
+    /**
+     * @description
+     * Defines the TypeORM column used to store monetary values.
+     */
+    readonly moneyColumnOptions: ColumnOptions;
+    /**
+     * @description
+     * Defines the precision (i.e. number of decimal places) represented by the monetary values.
+     * For example, consider a product variant with a price value of `12345`.
+     *
+     * - If the precision is `2`, then the price is `123.45`.
+     * - If the precision is `3`, then the price is `12.345`.
+     *
+     * Changing the precision has **no effect** on the stored value. It is merely a hint to the
+     * UI as to how many decimal places to display.
+     *
+     * @default 2
+     * @since 2.2.0
+     */
+    readonly precision?: number;
+    /**
+     * @description
+     * Defines the logic used to round monetary values. For instance, the default behavior
+     * in the {@link DefaultMoneyStrategy} is to round the value, then multiply.
+     *
+     * ```ts
+     * return Math.round(value) * quantity;
+     * ```
+     *
+     * However, it may be desirable to instead round only _after_ the unit amount has been
+     * multiplied. In this case you can define a custom strategy with logic like this:
+     *
+     * ```ts
+     * return Math.round(value * quantity);
+     * ```
+     */
+    round(value: number, quantity?: number): number;
+}

package/dist/config/entity/money-strategy.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=money-strategy.js.map

package/dist/config/entity/money-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money-strategy.js","sourceRoot":"","sources":["../../../src/config/entity/money-strategy.ts"],"names":[],"mappings":""}

package/dist/config/entity/uuid-id-strategy.d.ts

@@ -0,0 +1,28 @@
+import { EntityIdStrategy } from "./entity-id-strategy";
+/**
+ * @description
+ * An id strategy which uses string uuids as primary keys
+ * for all entities. This strategy can be configured with the
+ * `entityIdStrategy` property of the `entityOptions` property
+ * of {@link DeenruvConfig}.
+ *
+ * @example
+ * ```ts
+ * import { UuidIdStrategy, DeenruvConfig } from '\@deenruv/core';
+ *
+ * export const config: DeenruvConfig = {
+ *   entityOptions: {
+ *     entityIdStrategy: new UuidIdStrategy(),
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @docsCategory configuration
+ * @docsPage EntityIdStrategy
+ */
+export declare class UuidIdStrategy implements EntityIdStrategy<"uuid"> {
+    readonly primaryKeyType = "uuid";
+    decodeId(id: string): string;
+    encodeId(primaryKey: string): string;
+}

package/dist/config/entity/uuid-id-strategy.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UuidIdStrategy = void 0;
+/**
+ * @description
+ * An id strategy which uses string uuids as primary keys
+ * for all entities. This strategy can be configured with the
+ * `entityIdStrategy` property of the `entityOptions` property
+ * of {@link DeenruvConfig}.
+ *
+ * @example
+ * ```ts
+ * import { UuidIdStrategy, DeenruvConfig } from '\@deenruv/core';
+ *
+ * export const config: DeenruvConfig = {
+ *   entityOptions: {
+ *     entityIdStrategy: new UuidIdStrategy(),
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @docsCategory configuration
+ * @docsPage EntityIdStrategy
+ */
+class UuidIdStrategy {
+    constructor() {
+        this.primaryKeyType = "uuid";
+    }
+    decodeId(id) {
+        return id;
+    }
+    encodeId(primaryKey) {
+        return primaryKey;
+    }
+}
+exports.UuidIdStrategy = UuidIdStrategy;
+//# sourceMappingURL=uuid-id-strategy.js.map

package/dist/config/entity/uuid-id-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-id-strategy.js","sourceRoot":"","sources":["../../../src/config/entity/uuid-id-strategy.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,cAAc;IAA3B;QACW,mBAAc,GAAG,MAAM,CAAC;IAOnC,CAAC;IANC,QAAQ,CAAC,EAAU;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,QAAQ,CAAC,UAAkB;QACzB,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AARD,wCAQC"}

package/dist/config/entity-metadata/entity-metadata-modifier.d.ts

@@ -0,0 +1,55 @@
+import { MetadataArgsStorage } from "typeorm/metadata-args/MetadataArgsStorage";
+/**
+ * @description
+ * A function which allows TypeORM entity metadata to be manipulated prior to the DB schema being generated
+ * during bootstrap.
+ *
+ * :::caution
+ * Certain DB schema modifications will result in auto-generated migrations which will lead to data loss. For instance,
+ * changing the data type of a column will drop the column & data and then re-create it. To avoid loss of important data,
+ * always check and modify your migration scripts as needed.
+ * :::
+ *
+ * @example
+ * ```ts
+ * import { Index } from 'typeorm';
+ * import { EntityMetadataModifier, ProductVariant } from '\@deenruv/core';
+ *
+ * // Adds a unique index to the ProductVariant.sku column
+ * export const addSkuUniqueIndex: EntityMetadataModifier = metadata => {
+ *   const instance = new ProductVariant();
+ *   Index({ unique: true })(instance, 'sku');
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { Column } from 'typeorm';
+ * import { EntityMetadataModifier, ProductTranslation } from '\@deenruv/core';
+ *
+ * // Use the "mediumtext" datatype for the Product's description rather than
+ * // the default "text" type.
+ * export const makeProductDescriptionMediumText: EntityMetadataModifier = metadata => {
+ *     const descriptionColumnIndex = metadata.columns.findIndex(
+ *         col => col.propertyName === 'description' && col.target === ProductTranslation,
+ *     );
+ *     if (-1 < descriptionColumnIndex) {
+ *         // First we need to remove the existing column definition
+ *         // from the metadata.
+ *         metadata.columns.splice(descriptionColumnIndex, 1);
+ *         // Then we add a new column definition with our custom
+ *         // data type "mediumtext"
+ *         // DANGER: this particular modification will generate a DB migration
+ *         // which will result in data loss of existing descriptions. Make sure
+ *         // to manually check & modify your migration scripts.
+ *         const instance = new ProductTranslation();
+ *         Column({ type: 'mediumtext' })(instance, 'description');
+ *     }
+ * };
+ * ```
+ *
+ * @docsCategory configuration
+ * @docsPage EntityOptions
+ * @since 1.6.0
+ */
+export type EntityMetadataModifier = (metadata: MetadataArgsStorage) => void | Promise<void>;

package/dist/config/entity-metadata/entity-metadata-modifier.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=entity-metadata-modifier.js.map

package/dist/config/entity-metadata/entity-metadata-modifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-metadata-modifier.js","sourceRoot":"","sources":["../../../src/config/entity-metadata/entity-metadata-modifier.ts"],"names":[],"mappings":""}

package/dist/config/fulfillment/default-fulfillment-process.d.ts

@@ -0,0 +1,24 @@
+import { FulfillmentState } from "../../service/helpers/fulfillment-state-machine/fulfillment-state";
+import { FulfillmentProcess } from "./fulfillment-process";
+declare module "../../service/helpers/fulfillment-state-machine/fulfillment-state" {
+    interface FulfillmentStates {
+        Shipped: never;
+        Delivered: never;
+    }
+}
+/**
+ * @description
+ * The default {@link FulfillmentProcess}. This process includes the following actions:
+ *
+ * - Executes the configured `FulfillmentHandler.onFulfillmentTransition()` before any state
+ *   transition.
+ * - On cancellation of a Fulfillment, creates the necessary {@link Cancellation} & {@link Allocation}
+ *   stock movement records.
+ * - When a Fulfillment transitions from the `Created` to `Pending` state, the necessary
+ *   {@link Sale} stock movements are created.
+ *
+ * @docsCategory fulfillment
+ * @docsPage FulfillmentProcess
+ * @since 2.0.0
+ */
+export declare const defaultFulfillmentProcess: FulfillmentProcess<FulfillmentState>;

package/dist/config/fulfillment/default-fulfillment-process.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultFulfillmentProcess = void 0;
+const generated_types_1 = require("@deenruv/common/lib/generated-types");
+const error_result_1 = require("../../common/error/error-result");
+const errors_1 = require("../../common/error/errors");
+const utils_1 = require("../../common/utils");
+const order_entity_1 = require("../../entity/order/order.entity");
+const order_utils_1 = require("../../service/helpers/utils/order-utils");
+let connection;
+let configService;
+let orderService;
+let historyService;
+let stockMovementService;
+let stockLevelService;
+/**
+ * @description
+ * The default {@link FulfillmentProcess}. This process includes the following actions:
+ *
+ * - Executes the configured `FulfillmentHandler.onFulfillmentTransition()` before any state
+ *   transition.
+ * - On cancellation of a Fulfillment, creates the necessary {@link Cancellation} & {@link Allocation}
+ *   stock movement records.
+ * - When a Fulfillment transitions from the `Created` to `Pending` state, the necessary
+ *   {@link Sale} stock movements are created.
+ *
+ * @docsCategory fulfillment
+ * @docsPage FulfillmentProcess
+ * @since 2.0.0
+ */
+exports.defaultFulfillmentProcess = {
+    transitions: {
+        Created: {
+            to: ["Pending"],
+        },
+        Pending: {
+            to: ["Shipped", "Delivered", "Cancelled"],
+        },
+        Shipped: {
+            to: ["Delivered", "Cancelled"],
+        },
+        Delivered: {
+            to: ["Cancelled"],
+        },
+        Cancelled: {
+            to: [],
+        },
+    },
+    async init(injector) {
+        // Lazily import these services to avoid a circular dependency error
+        // due to this being used as part of the DefaultConfig
+        const TransactionalConnection = await import("../../connection/transactional-connection.js").then((m) => m.TransactionalConnection);
+        const ConfigService = await import("../config.service.js").then((m) => m.ConfigService);
+        const HistoryService = await import("../../service/index.js").then((m) => m.HistoryService);
+        const OrderService = await import("../../service/index.js").then((m) => m.OrderService);
+        const StockMovementService = await import("../../service/index.js").then((m) => m.StockMovementService);
+        const StockLevelService = await import("../../service/index.js").then((m) => m.StockLevelService);
+        connection = injector.get(TransactionalConnection);
+        configService = injector.get(ConfigService);
+        orderService = injector.get(OrderService);
+        historyService = injector.get(HistoryService);
+        stockMovementService = injector.get(StockMovementService);
+        stockLevelService = injector.get(StockLevelService);
+    },
+    async onTransitionStart(fromState, toState, data) {
+        const { fulfillmentHandlers } = configService.shippingOptions;
+        const fulfillmentHandler = fulfillmentHandlers.find((h) => h.code === data.fulfillment.handlerCode);
+        if (fulfillmentHandler) {
+            const result = await (0, utils_1.awaitPromiseOrObservable)(fulfillmentHandler.onFulfillmentTransition(fromState, toState, data));
+            if (result === false || typeof result === "string") {
+                return result;
+            }
+        }
+    },
+    async onTransitionEnd(fromState, toState, { ctx, fulfillment, orders }) {
+        if (toState === "Cancelled") {
+            const orderLineInput = fulfillment.lines.map((l) => ({
+                orderLineId: l.orderLineId,
+                quantity: l.quantity,
+            }));
+            await stockMovementService.createCancellationsForOrderLines(ctx, orderLineInput);
+            await stockMovementService.createAllocationsForOrderLines(ctx, orderLineInput);
+        }
+        if (fromState === "Created" && toState === "Pending") {
+            await stockMovementService.createSalesForOrder(ctx, fulfillment.lines);
+        }
+        const historyEntryPromises = orders.map((order) => historyService.createHistoryEntryForOrder({
+            orderId: order.id,
+            type: generated_types_1.HistoryEntryType.ORDER_FULFILLMENT_TRANSITION,
+            ctx,
+            data: {
+                fulfillmentId: fulfillment.id,
+                from: fromState,
+                to: toState,
+            },
+        }));
+        await Promise.all(historyEntryPromises);
+        await Promise.all(orders.map((order) => handleFulfillmentStateTransitByOrder(ctx, order, fulfillment, fromState, toState)));
+    },
+};
+async function handleFulfillmentStateTransitByOrder(ctx, order, fulfillment, fromState, toState) {
+    const nextOrderStates = orderService.getNextOrderStates(order);
+    const transitionOrderIfStateAvailable = async (state) => {
+        if (nextOrderStates.includes(state)) {
+            const result = await orderService.transitionToState(ctx, order.id, state);
+            if ((0, error_result_1.isGraphQlErrorResult)(result)) {
+                throw new errors_1.InternalServerError(result.message);
+            }
+        }
+    };
+    if (toState === "Shipped") {
+        const orderWithFulfillment = await getOrderWithFulfillments(ctx, order.id);
+        if ((0, order_utils_1.orderItemsAreShipped)(orderWithFulfillment)) {
+            await transitionOrderIfStateAvailable("Shipped");
+        }
+        else {
+            await transitionOrderIfStateAvailable("PartiallyShipped");
+        }
+    }
+    if (toState === "Delivered") {
+        const orderWithFulfillment = await getOrderWithFulfillments(ctx, order.id);
+        if ((0, order_utils_1.orderItemsAreDelivered)(orderWithFulfillment)) {
+            await transitionOrderIfStateAvailable("Delivered");
+        }
+        else {
+            await transitionOrderIfStateAvailable("PartiallyDelivered");
+        }
+    }
+}
+async function getOrderWithFulfillments(ctx, orderId) {
+    return await connection.getEntityOrThrow(ctx, order_entity_1.Order, orderId, {
+        relations: [
+            "lines",
+            "fulfillments",
+            "fulfillments.lines",
+            "fulfillments.lines.fulfillment",
+        ],
+    });
+}
+//# sourceMappingURL=default-fulfillment-process.js.map

package/dist/config/fulfillment/default-fulfillment-process.js.map

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

package/dist/config/fulfillment/fulfillment-handler.d.ts

@@ -0,0 +1,143 @@
+import { ConfigArg, OrderLineInput } from "@deenruv/common/lib/generated-types";
+import { RequestContext } from "../../api/common/request-context";
+import { ConfigArgs, ConfigArgValues, ConfigurableOperationDef, ConfigurableOperationDefOptions } from "../../common/configurable-operation";
+import { OnTransitionStartFn } from "../../common/finite-state-machine/types";
+import { Fulfillment } from "../../entity/fulfillment/fulfillment.entity";
+import { Order } from "../../entity/order/order.entity";
+import { FulfillmentState, FulfillmentTransitionData } from "../../service/helpers/fulfillment-state-machine/fulfillment-state";
+/**
+ * @docsCategory fulfillment
+ * @docsPage FulfillmentHandler
+ * @docsWeight 3
+ */
+export type CreateFulfillmentResult = Partial<Pick<Fulfillment, "trackingCode" | "method" | "customFields">>;
+/**
+ * @description
+ * The function called when creating a new Fulfillment
+ *
+ * @docsCategory fulfillment
+ * @docsPage FulfillmentHandler
+ * @docsWeight 2
+ */
+export type CreateFulfillmentFn<T extends ConfigArgs> = (ctx: RequestContext, orders: Order[], lines: OrderLineInput[], args: ConfigArgValues<T>) => CreateFulfillmentResult | Promise<CreateFulfillmentResult>;
+/**
+ * @description
+ * The configuration object used to instantiate a {@link FulfillmentHandler}.
+ *
+ * @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 FulfillmentProcess} `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>;
+}
+/**
+ * @description
+ * A FulfillmentHandler is used when creating a new {@link Fulfillment}. When the `addFulfillmentToOrder` mutation
+ * is executed, the specified handler will be used and it's `createFulfillment` method is called. This method
+ * may perform async tasks such as calling a 3rd-party shipping API to register a new shipment and receive
+ * a tracking code. This data can then be returned and will be incorporated into the created Fulfillment.
+ *
+ * If the `args` property is defined, this means that arguments passed to the `addFulfillmentToOrder` mutation
+ * will be passed through to the `createFulfillment` method as the last argument.
+ *
+ * @example
+ * ```ts
+ * let shipomatic;
+ *
+ * export const shipomaticFulfillmentHandler = new FulfillmentHandler({
+ *   code: 'ship-o-matic',
+ *   description: [{
+ *     languageCode: LanguageCode.en,
+ *     value: 'Generate tracking codes via the Ship-o-matic API'
+ *   }],
+ *
+ *   args: {
+ *     preferredService: {
+ *       type: 'string',
+ *       ui: {
+           component: 'select-form-input',
+ *         options: [
+ *           { value: 'first_class' },
+ *           { value: 'priority'},
+ *           { value: 'standard' },
+ *         ],
+ *       },
+ *     }
+ *   },
+ *
+ *   init: () => {
+ *     // some imaginary shipping service
+ *     shipomatic = new ShipomaticClient(API_KEY);
+ *   },
+ *
+ *   createFulfillment: async (ctx, orders, lines, args) => {
+ *
+ *      const shipment = getShipmentFromOrders(orders, lines);
+ *
+ *      try {
+ *        const transaction = await shipomatic.transaction.create({
+ *          shipment,
+ *          service_level: args.preferredService,
+ *          label_file_type: 'png',
+ *        })
+ *
+ *        return {
+ *          method: `Ship-o-matic ${args.preferredService}`,
+ *          trackingCode: transaction.tracking_code,
+ *          customFields: {
+ *            shippingTransactionId: transaction.id,
+ *          }
+ *        };
+ *      } catch (e: any) {
+ *        // Errors thrown from within this function will
+ *        // result in a CreateFulfillmentError being returned
+ *        throw e;
+ *      }
+ *   },
+ *
+ *   onFulfillmentTransition: async (fromState, toState, { fulfillment }) => {
+ *     if (toState === 'Cancelled') {
+ *       await shipomatic.transaction.cancel({
+ *         transaction_id: fulfillment.customFields.shippingTransactionId,
+ *       });
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @docsCategory fulfillment
+ * @docsPage FulfillmentHandler
+ * @docsWeight 0
+ */
+export declare class FulfillmentHandler<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
+    private readonly createFulfillmentFn;
+    private readonly onFulfillmentTransitionFn;
+    constructor(config: FulfillmentHandlerConfig<T>);
+    /**
+     * @internal
+     */
+    createFulfillment(ctx: RequestContext, orders: Order[], lines: OrderLineInput[], args: ConfigArg[]): Partial<Fulfillment> | Promise<Partial<Fulfillment>>;
+    /**
+     * @internal
+     */
+    onFulfillmentTransition(fromState: FulfillmentState, toState: FulfillmentState, data: FulfillmentTransitionData): string | boolean | void | Promise<string | boolean | void> | import("rxjs").Observable<string | boolean | void>;
+}