@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/shipping/myparcel.d.ts

@@ -0,0 +1,668 @@
+import { type PlatformError, type Transport, type VendureErrorResult } from '@sixtyninecommerce/core';
+import { type FulfillmentLabelFormat } from '../fulfillments/index.js';
+import type { Call } from '../types.js';
+/**
+ * The store-wide default label format: `A4` or `A6` paper, or `BOTH`, which has MyParcel make
+ * both for every new fulfillment.
+ */
+export type MyparcelLabelFormat = 'A4' | 'A6' | 'BOTH';
+/**
+ * A store's MyParcel set-up, as every reader gets it: both secrets masked. The API key is never
+ * readable again once saved, and the webhook secret is only ever needed by the platform itself
+ * (it registers the callback URL at MyParcel), so neither is answered in clear here.
+ */
+export interface MyparcelConfig {
+    id: string;
+    channelId: string;
+    /** A key is stored. */
+    hasApiKey: boolean;
+    /**
+     * The key's preview, for display only: mask glyphs (`•`) and its last 4 characters. It is never
+     * the key: `update` refuses it (`SECRET_ARG_MASK_INVALID`).
+     */
+    maskedApiKey: string;
+    /** The webhook secret's preview, for display only: 8 mask glyphs and its last 4 characters. */
+    maskedWebhookSecret: string;
+    defaultLabelFormat: MyparcelLabelFormat;
+    /** MyParcel is on for the store. Independent of the key: switching off keeps it. */
+    enabled: boolean;
+}
+/** What `config.update` takes: the key alone. */
+export interface UpdateMyparcelConfigInput {
+    /** The MyParcel API key, from the store's MyParcel account. Trimmed; never empty. */
+    apiKey: string;
+}
+/** A carrier MyParcel offers. The list is the same for every store (`GET /carriers`). */
+export interface MyparcelCarrier {
+    /** MyParcel's carrier id, as a shipment names it. */
+    id: number;
+    /** The carrier's slug (`postnl`, `dhlforyou`, …). */
+    name: string;
+    /** Its name for people (`PostNL`). */
+    human: string;
+    /** MyParcel's logo links; `''` where MyParcel has none. */
+    meta: {
+        logoSvg: string;
+        logoPng: string;
+    };
+}
+/** A stock location's parcel sender address. */
+export interface MyparcelSenderAddress {
+    streetLine1: string;
+    streetLine2: string | null;
+    city: string;
+    postalCode: string;
+    province: string | null;
+    /** ISO 3166-1 alpha-2, upper case. */
+    countryCode: string;
+    phoneNumber: string | null;
+    contactName: string | null;
+    company: string | null;
+}
+/** One stock location of the store as a parcel sender. */
+export interface MyparcelSenderLocation {
+    /** The stock location's id. */
+    id: string;
+    name: string;
+    /** Its sender address, or `null` when none is stored or the stored one does not parse. */
+    address: MyparcelSenderAddress | null;
+    /** The store's default sender: a shipment that names no location ships from it. */
+    isDefaultSender: boolean;
+    /** The address has every field a shipment needs (street, city, postal code, country). */
+    isResolvable: boolean;
+}
+/** What `senders.set` writes. */
+export interface SetMyparcelSenderInput {
+    stockLocationId: string;
+    /** The whole address. `null` or a blank optional field is stored as absent. */
+    address: {
+        streetLine1: string;
+        streetLine2?: string | null;
+        city: string;
+        postalCode: string;
+        province?: string | null;
+        countryCode: string;
+        phoneNumber?: string | null;
+        contactName?: string | null;
+        company?: string | null;
+    };
+    /**
+     * Make this location the store's default sender (`true`) or not. Send the location's CURRENT
+     * flag to change the address alone: only a change of the flag is judged and written.
+     */
+    isDefault: boolean;
+}
+/**
+ * The MyParcel set-up of the store the client is scoped to (`admin.shipping.myparcel.config`).
+ * There is no channel argument: a SuperAdmin head configures ANOTHER store with
+ * `admin.withTenant({ scope: { kind: 'channel', code } })`, or a per-call `tenant`.
+ *
+ * Every method needs `UpdateSettings`. An app installation is refused all of them
+ * (`APP_CREDENTIAL_NOT_ALLOWED`), the read included: the engine still answers the webhook secret
+ * in clear on an older field of the same object. A store without the MyParcel plugin is refused
+ * `PLUGIN_ACCESS_DENIED` (`PermissionDeniedError`, 403) on every write, `remove` included, for an
+ * ordinary caller; the engine never refuses a SuperAdmin on that ground.
+ */
+export interface MyparcelConfigModule {
+    /**
+     * The store's set-up, or `null` when no key was ever saved (or it was removed). A stored key the
+     * engine can no longer decrypt (its encryption key was rotated) fails this read with the
+     * engine's internal error (code `INTERNAL_SERVER_ERROR`: a non-retryable 500, raised as
+     * `UpstreamError`), not a coded refusal: the read is not a union. Saving the key again with `update` repairs it; the writes answer the
+     * same condition as `MYPARCEL_DECRYPTION_FAILED_ERROR` (`BusinessRuleError`, 422).
+     *
+     * @effect read
+     * @permission UpdateSettings
+     */
+    get(options?: Call): Promise<MyparcelConfig | null>;
+    /**
+     * Save the store's API key; the first save also switches MyParcel on, with `A6` labels and a new
+     * webhook secret. A later save replaces the key alone (the on/off switch, the label format and
+     * the webhook secret stay). The key is trimmed and stored as given: the engine does not test it
+     * against MyParcel, so a wrong key fails at the first shipment or label.
+     *
+     * An empty key is refused here (`TypeError`), never sent: an empty key REMOVES the whole set-up
+     * on the wire, and that is `remove()`'s job. The message never quotes the argument.
+     *
+     * Refused, with nothing stored:
+     * - `SECRET_ARG_MASK_INVALID` (`ValidationError`, 400, `details[0].field: 'apiKey'`): a key
+     *   carrying the mask glyph (`•`), {@link MyparcelConfig.maskedApiKey} sent back included. The
+     *   preview is never the key; leave the key alone to keep it;
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` (`BusinessRuleError`, 422): an organization's workspace
+     *   ships nothing.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    update(input: UpdateMyparcelConfigInput, options?: Call): Promise<MyparcelConfig>;
+    /**
+     * Remove the store's MyParcel set-up: the API key, the label format, the on/off switch AND the
+     * webhook secret. MyParcel's status and label callbacks for the store are refused from then on,
+     * and every MyParcel shipment or label of the store is refused (`MYPARCEL_NOT_CONFIGURED_ERROR`)
+     * until a key is saved again, which mints a new webhook secret. Resolves when the store has no
+     * set-up any more, also when it had none. Allowed in an organization's workspace.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    remove(options?: Call): Promise<void>;
+    /**
+     * Set the store-wide default label format. A fulfillment's own format, when it has one, wins.
+     *
+     * Refused: `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`, 422) before a key is saved;
+     * `MYPARCEL_INVALID_LABEL_FORMAT_ERROR` (422) for any other value.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    setLabelFormat(format: MyparcelLabelFormat, options?: Call): Promise<MyparcelConfig>;
+    /**
+     * Switch MyParcel on or off for the store without touching the key or the webhook secret. Off,
+     * every new MyParcel shipment and label of the store is refused; what MyParcel already holds is
+     * left as it is.
+     *
+     * Refused: `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`, 422) before a key is saved;
+     * switching ON in an organization's workspace, `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422).
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    setEnabled(enabled: boolean, options?: Call): Promise<MyparcelConfig>;
+    /**
+     * Replace the store's webhook secret, answering the set-up with the NEW secret's preview (the
+     * secret itself is never answered). The old secret stops authenticating at once, and MyParcel
+     * keeps calling the old callback URL, refused, until the engine's worker registers the webhooks
+     * again, which it does when it starts. Status and label updates sent meanwhile are lost.
+     *
+     * The secret is answered in clear by the engine's older `webhookSecret` field and stored in
+     * clear; hashing it at rest is an open follow-up, after which only a preview can be read.
+     *
+     * Refused: `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`, 422) before a key is saved.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    regenerateWebhookSecret(options?: Call): Promise<MyparcelConfig>;
+}
+/**
+ * The stock locations of the store as MyParcel parcel senders (`admin.shipping.myparcel.senders`).
+ * A location's sender address and default flag are columns of its ONE row, so a location several
+ * stores hold has one sender for all of them.
+ */
+export interface MyparcelSendersModule {
+    /**
+     * Every stock location of the store with its sender address, default flag and whether a
+     * shipment can ship from it. Needs `ReadStockLocation`; answered whether or not MyParcel is set
+     * up.
+     *
+     * @effect read
+     * @permission ReadStockLocation
+     */
+    list(options?: Call): Promise<MyparcelSenderLocation[]>;
+    /**
+     * Set a stock location's sender address, and whether it is the store's default sender. Making it
+     * the default clears the flag on the store's other locations in the same transaction, so the
+     * store keeps exactly one. This is the one door that writes either column: core's stock-location
+     * create and update refuse a change to them (`STOCK_LOCATION_SENDER_READ_ONLY`).
+     *
+     * Refused, with nothing written:
+     * - `MYPARCEL_INVALID_SENDER_ERROR` (`BusinessRuleError`, 422): a mandatory field missing or a
+     *   country code that is not 2 letters; `details[]` names each field (`streetLine1`, `city`,
+     *   `postalCode`, `countryCode`);
+     * - `MYPARCEL_STOCK_LOCATION_NOT_FOUND_ERROR` (`NotFoundError`, 404): no such location in the
+     *   store (another store's, a missing and a malformed id alike);
+     * - `SHARED_STOCK_LOCATION_NOT_ALLOWED` (403): the location, or a default it would clear, is
+     *   also another store's, and the caller may not update stock locations there;
+     * - `LOCATION_NOT_ALLOWED` (403): a credential restricted to some locations names, or would
+     *   clear the default of, one it does not hold;
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` / `DEFAULT_SENDER_NOT_A_STORE` (422): changing the
+     *   default flag in an organization's workspace or on the platform root. Sending the current
+     *   flag there saves the address alone.
+     *
+     * @effect write
+     * @permission UpdateStockLocation
+     */
+    set(input: SetMyparcelSenderInput, options?: Call): Promise<MyparcelSenderLocation>;
+}
+/**
+ * One MyParcel shipment (one parcel) as MyParcel holds it, read live: the engine stores none of
+ * these fields itself.
+ */
+export interface MyparcelShipment {
+    /** MyParcel's shipment id. */
+    id: number;
+    /** What MyParcel knows the shipment by (`F-12`, `F-12#2`, a transfer's code); null when none. */
+    referenceIdentifier: string | null;
+    /** The carrier's barcode; null until MyParcel has registered the shipment. */
+    barcode: string | null;
+    /** MyParcel's status number: 1 is a concept, 2 registered, 3 and up on its way or done. */
+    status: number;
+    /** MyParcel's carrier id (`carriers()` names it). */
+    carrierId: number;
+    /**
+     * When MyParcel created the shipment, as MyParcel writes it, passed through untouched. MyParcel
+     * sends no offset: never read it as UTC.
+     */
+    created: string;
+    /** When MyParcel last changed the shipment, as `created` is written. */
+    modified: string;
+    /** The recipient's track-and-trace page at MyParcel; null when MyParcel has none. */
+    linkConsumerPortal: string | null;
+}
+/** Whether MyParcel has made a shipment's label in one format: `pending` until it has. */
+export interface MyparcelLabelReadiness {
+    status: 'pending' | 'ready';
+}
+/** One shipment's label as a PDF, fetched live from MyParcel. */
+export interface MyparcelShipmentLabel {
+    format: FulfillmentLabelFormat;
+    contentType: string;
+    /** A download filename, from the order code when there is one. */
+    filename: string;
+    bytes: Uint8Array;
+}
+/** What `labels.request` asks for: one parcel's label, in one format. */
+export interface RequestMyparcelLabelInput {
+    /** The fulfillment holding the shipment. */
+    fulfillmentId: string;
+    /** The shipment (one parcel) of that fulfillment. */
+    shipmentId: number;
+    format: FulfillmentLabelFormat;
+}
+/**
+ * What one carrier can ship, from the engine's static carrier table (the same for every store).
+ * Join it with `carriers()` on `carrierId` for the carrier's name for people and its logo.
+ */
+export interface MyparcelCarrierCapability {
+    /** MyParcel's carrier id. */
+    carrierId: number;
+    /** The carrier's slug (`postnl`, …). */
+    name: string;
+    /** MyParcel package-type numbers the carrier takes (1 package, 2 mailbox, 3 letter, …). */
+    packageTypes: number[];
+    /** MyParcel delivery-type numbers it offers (1 morning, 2 standard, 3 evening, 4 pickup, …). */
+    deliveryTypes: number[];
+    /** ISO 3166-1 alpha-2 codes, or a scope token (`NL`, `BE`, `EU`, `GLOBAL`). */
+    countries: string[];
+    /** The shipment option keys it accepts, as MyParcel writes them (`signature`, `only_recipient`, …). */
+    supportedOptions: string[];
+    supportsPickup: boolean;
+    /** Rules across options a form should enforce, in words. */
+    constraints: string[];
+}
+/** What `deliveryOptions` asks MyParcel about: one destination and, optionally, the parcel. */
+export interface MyparcelDeliveryOptionsInput {
+    /** The destination's postal code. Required: a blank one is refused before any request. */
+    postalCode: string;
+    /** ISO 3166-1 alpha-2; the engine assumes `NL` when absent. */
+    countryCode?: string | null;
+    houseNumber?: string | null;
+    /** MyParcel's carrier id; a carrier the engine cannot name to MyParcel is left out of the ask. */
+    carrierId?: number | null;
+    /** The parcel's weight in grams. */
+    weight?: number | null;
+    /** MyParcel's package-type number. */
+    packageType?: number | null;
+    /** As MyParcel takes it (`YYYY-MM-DD`). */
+    deliveryDate?: string | null;
+    /** The store's cut-off time (`HH:MM`). */
+    cutoffTime?: string | null;
+    mondayDelivery?: boolean | null;
+    saturdayDelivery?: boolean | null;
+    /** MyParcel's drop-off days list (`1;2;3;4;5`). */
+    dropoffDays?: string | null;
+}
+/** An amount in MINOR units (cents) with its currency, as MyParcel answers it. */
+export interface MyparcelMoney {
+    amount: number;
+    currency: string;
+}
+/** One priced delivery window, one row per window of a day. */
+export interface MyparcelDeliveryOption {
+    /** MyParcel's delivery-type number of this window. */
+    deliveryType: number;
+    /** The delivery day as MyParcel writes it; never read it as a UTC instant. */
+    date: string;
+    startTime: string | null;
+    endTime: string | null;
+    /**
+     * MyParcel's base rate for the window, or `null` when MyParcel named none. Carrier surcharges
+     * are settled when the shipment is created, so this is a quote, not the bill.
+     */
+    price: MyparcelMoney | null;
+}
+/** A pickup point MyParcel offers near the destination. */
+export interface MyparcelPickupOption {
+    locationCode: string;
+    locationName: string;
+    street: string;
+    number: string;
+    numberSuffix: string | null;
+    postalCode: string;
+    city: string;
+    countryCode: string;
+    /** The carrier asked for, or `null` when the ask named none. */
+    carrierId: number | null;
+    /** Metres from the destination, when MyParcel says. */
+    distance: number | null;
+}
+/** MyParcel's answer for a destination: delivery windows and pickup points. */
+export interface MyparcelDeliveryOptions {
+    deliveryOptions: MyparcelDeliveryOption[];
+    pickupOptions: MyparcelPickupOption[];
+}
+/**
+ * One MyParcel handler argument as the create-shipment form writes it (`carrier`, `packageType`,
+ * `parcelCount`, `deliveryType`, `pickupLocation`, the shipment options, …). The engine reads the
+ * same names as `admin.fulfillments.create`'s `handlerArgs` for the `myparcel` handler.
+ */
+export interface MyparcelHandlerArgument {
+    name: string;
+    value: string;
+}
+/** What `shipments.recreate` books again. */
+export interface RecreateMyparcelShipmentInput {
+    /** The fulfillment whose MyParcel shipment(s) are replaced. */
+    fulfillmentId: string;
+    /**
+     * The new shipment's choices. A `parcelCount` left out keeps the fulfillment's recorded parcel
+     * count (never "one"); an empty list books the same parcels with the engine's defaults.
+     */
+    handlerArguments: readonly MyparcelHandlerArgument[];
+}
+/** What `shipments.import` attaches. */
+export interface ImportMyparcelShipmentInput {
+    /** A fulfillment of the store that holds no MyParcel shipment yet. */
+    fulfillmentId: string;
+    /** The numeric id the MyParcel backoffice shows for the shipment. */
+    shipmentId: number;
+}
+/** The shipment now on the fulfillment, and the label format it prints in. */
+export interface MyparcelShipmentAttached {
+    /** The first parcel's MyParcel shipment id. */
+    shipmentId: number;
+    labelFormat: MyparcelLabelFormat;
+}
+/** What `returns.create` asks MyParcel for: a return label linked to a shipment of the store. */
+export interface CreateMyparcelReturnInput {
+    /** The outbound shipment (one parcel) the customer sends back. */
+    parentShipmentId: number;
+    /** MyParcel's carrier id for the return. */
+    carrier: number;
+    /** The customer's name, as the return label carries it. Trimmed; never blank. */
+    name: string;
+    /** Where MyParcel sends the customer the return label. Trimmed; never blank. */
+    email: string;
+}
+/** The return shipment MyParcel made. */
+export interface MyparcelReturnShipment {
+    shipmentId: number;
+}
+/**
+ * The store's MyParcel shipments (`admin.shipping.myparcel.shipments`). A shipment is named by
+ * MyParcel's id, and only one a fulfillment or a stock transfer of the store holds is answered:
+ * two stores may share one MyParcel account, whose ids are small and sequential.
+ */
+export interface MyparcelShipmentsModule {
+    /**
+     * The shipment as MyParcel answers it now (one call to MyParcel), or `null` when MyParcel no
+     * longer holds a shipment the store still records. Needs `ReadOrder`.
+     *
+     * Refused: a shipment no fulfillment or stock transfer of the store holds (another store's, a
+     * missing id) is `ENTITY_NOT_FOUND` (`NotFoundError`), before MyParcel is asked. A credential
+     * restricted to stock locations (an API token or app installation with `locationIds`) reads only
+     * a shipment of a fulfillment that ships from one of them (`LOCATION_OUT_OF_SCOPE`, 422). A store
+     * without the MyParcel plugin still reads a shipment one of its fulfillments holds; any other is
+     * `PLUGIN_ACCESS_DENIED` (403) for an ordinary caller. An id that is not a positive integer is
+     * refused before any request (`INVALID_INPUT`, `ValidationError`).
+     *
+     * A store whose MyParcel set-up was removed after the shipment was booked is refused
+     * `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`, 422): set MyParcel up again in the
+     * store's shipping settings. An engine older than this answer failed it uncoded (`GRAPHQL_ERROR`,
+     * 500). `labels.status` and `labels.download` answer that case the same way.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    get(shipmentId: number, options?: Call): Promise<MyparcelShipment | null>;
+    /**
+     * Replace the MyParcel shipment(s) of a fulfillment with new ones booked from
+     * `handlerArguments`: the order's recipient, the fulfillment's lines and parcels. Used to
+     * recover a failed booking or to change a concept's choices (MyParcel cannot edit a shipment
+     * in place). The new shipments are attached to the SAME fulfillment, and only then are the old
+     * concepts retracted (queued; one MyParcel keeps is recorded on the fulfillment). Needs
+     * `UpdateOrder`.
+     *
+     * `@effect money`: the new shipments are booked at MyParcel and their labels asked for, which
+     * registers and bills them. Takes no idempotency key: a repeat books another set while the
+     * first is still a concept, retracting the first; once it is registered a repeat is refused
+     * (below).
+     *
+     * Refused with nothing booked, each with its code and, where the engine names fields, one
+     * `details[]` entry per field (`details[].field`), so a form can mark each:
+     * - `MYPARCEL_INVALID_RECIPIENT_ERROR` (`BusinessRuleError`): the order's shipping address
+     *   lacks what a label needs (`fullName`, `countryCode`, `city`, `postalCode`, `streetLine1`,
+     *   or `shippingAddress` for none at all). `streetLine1` alone means no house number could be
+     *   read from it. Fix the address on the order, then recreate;
+     * - `MYPARCEL_INVALID_SENDER_ERROR`: the shipping stock location's sender address is
+     *   incomplete (`details[].field` names each field); set it with `senders.set`;
+     * - `MYPARCEL_VALIDATION_ERROR`: a choice MyParcel or the engine refuses, with the fields it
+     *   names (`parcelCount` below the packed parcels: re-pack first; `shipmentId` for a parcel
+     *   already past concept: MyParcel keeps and bills it, so cancel the fulfillment instead;
+     *   `fulfillmentId` when another recreate or booking changed it meanwhile: reload and retry,
+     *   or for a fulfillment that does not ship with MyParcel, such as a manual one: create a
+     *   MyParcel fulfillment instead);
+     * - `MYPARCEL_PICKUP_LOCATION_REQUIRED_ERROR` / `_DEACTIVATED_ERROR` / `_NOT_FOUND_ERROR` /
+     *   `_INVALID_ERROR` (fields named): pick another pickup point;
+     * - `MYPARCEL_INVALID_CUSTOMS_ERROR`, `MYPARCEL_MISSING_PHYSICAL_PROPERTIES_ERROR`: a parcel
+     *   outside the EU needs customs data and weights on its products;
+     * - `MYPARCEL_NOT_CONFIGURED_ERROR` (no set-up, or switched off: turn it on in the store's
+     *   shipping settings), `MYPARCEL_DECRYPTION_FAILED_ERROR` (save the key again),
+     *   `MYPARCEL_STOCK_LOCATION_NOT_FOUND_ERROR`, `MYPARCEL_ORDER_NOT_FOUND_ERROR`
+     *   (`NotFoundError`), `MYPARCEL_API_ERROR` (MyParcel's own refusal or outage);
+     * - a fulfillment of another store or a credential restricted to other stock locations is
+     *   refused by the engine's door before anything is read (`ENTITY_NOT_FOUND`,
+     *   `LOCATION_OUT_OF_SCOPE`).
+     *
+     * A blank fulfillment id or an argument that is not `{ name, value }` strings is refused
+     * before any request (`INVALID_INPUT`, `ValidationError`).
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    recreate(input: RecreateMyparcelShipmentInput, options?: Call): Promise<MyparcelShipmentAttached>;
+    /**
+     * Attach a shipment made by hand in the MyParcel backoffice to a fulfillment that holds none,
+     * by its numeric id, and ask MyParcel for its label (queued). Needs `UpdateOrder`.
+     *
+     * `@effect money`: the label request registers a shipment MyParcel still holds as a concept,
+     * and bills it. No idempotency key: a repeat is refused, since the fulfillment then holds a
+     * shipment.
+     *
+     * Refused with nothing attached:
+     * - `MYPARCEL_VALIDATION_ERROR` (`details[].field: 'shipmentId'`): the fulfillment already
+     *   holds a shipment (recreate it instead), or the store's MyParcel account has no such
+     *   shipment (check the id in the backoffice);
+     * - `MYPARCEL_VALIDATION_ERROR` (`details[].field: 'fulfillmentId'`): the fulfillment does not
+     *   ship with MyParcel (a manual one, say), so it takes no MyParcel shipment; refused before
+     *   MyParcel is asked;
+     * - `MYPARCEL_SHIPMENT_ALREADY_ATTACHED_ERROR`: another fulfillment or stock transfer holds it;
+     * - `MYPARCEL_NOT_CONFIGURED_ERROR` (no set-up, or switched off),
+     *   `MYPARCEL_DECRYPTION_FAILED_ERROR`, `MYPARCEL_ORDER_NOT_FOUND_ERROR` (`NotFoundError`),
+     *   `MYPARCEL_API_ERROR`;
+     * - another store's fulfillment, or a credential restricted to other stock locations, by the
+     *   engine's door first (`ENTITY_NOT_FOUND`, `LOCATION_OUT_OF_SCOPE`).
+     *
+     * A blank fulfillment id or a shipment id that is not a positive integer is refused before any
+     * request (`INVALID_INPUT`, `ValidationError`).
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    import(input: ImportMyparcelShipmentInput, options?: Call): Promise<MyparcelShipmentAttached>;
+}
+/** MyParcel return labels for the store's shipments (`admin.shipping.myparcel.returns`). */
+export interface MyparcelReturnsModule {
+    /**
+     * Ask MyParcel for a return shipment linked to an outbound shipment of the store. MyParcel
+     * e-mails the customer the return label at `email`. Needs `UpdateOrder`.
+     *
+     * `@effect money`: MyParcel bills the return shipment to the store's account. No idempotency
+     * key: every call makes ANOTHER return shipment and e-mail.
+     *
+     * Refused:
+     * - a shipment no fulfillment or stock transfer of the store holds (another store's on a
+     *   shared MyParcel account, a missing id) is `ENTITY_NOT_FOUND` (`NotFoundError`), before
+     *   MyParcel is asked;
+     * - `MYPARCEL_NOT_CONFIGURED_ERROR` (no set-up, or switched off: turn it on in the store's
+     *   shipping settings), before MyParcel is asked; `MYPARCEL_DECRYPTION_FAILED_ERROR` (save the
+     *   key again), `MYPARCEL_VALIDATION_ERROR` (fields named in `details[]`),
+     *   `MYPARCEL_API_ERROR` (MyParcel's own refusal: a carrier that takes no returns, …).
+     *
+     * A shipment or carrier id that is not a positive integer, or a blank name or e-mail, is
+     * refused before any request (`INVALID_INPUT`, `ValidationError`, the field in `details[]`).
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    create(input: CreateMyparcelReturnInput, options?: Call): Promise<MyparcelReturnShipment>;
+}
+/**
+ * The labels of the store's MyParcel shipments (`admin.shipping.myparcel.labels`).
+ *
+ * MyParcel registers a shipment it still holds as a concept on the FIRST call that asks for its
+ * label, in any format and by any of the three methods here, and bills the store for it from then
+ * on; a registered shipment is not registered again. So each of the three is `@effect money`. A
+ * registered label cannot be deleted through MyParcel's API.
+ *
+ * A store without the MyParcel plugin is refused `PLUGIN_ACCESS_DENIED` (`PermissionDeniedError`,
+ * 403) on all three, for an ordinary caller; the engine never refuses a SuperAdmin on that ground.
+ */
+export interface MyparcelLabelsModule {
+    /**
+     * Whether MyParcel has made the label of these shipments in `format`: `ready` once every one of
+     * them has it, `pending` until then. A readiness signal only: the label itself is `download`
+     * (or `admin.fulfillments.myparcelLabel` for every parcel of a fulfillment). Each call is one
+     * request to MyParcel, so poll it with a back-off. Allowed up to 55s, like `download`: the
+     * engine retries a slow MyParcel within a budget the default timeout does not cover. Needs
+     * `ReadOrder`.
+     *
+     * Refused before MyParcel is asked: a shipment the store does not hold (`ENTITY_NOT_FOUND`,
+     * `NotFoundError`) refuses the whole call. A store whose set-up was removed is refused
+     * `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`, 422; see `shipments.get`); a set-up
+     * switched off is still answered. An
+     * empty list, an id that is not a positive integer or a format other than `A4`/`A6` is refused
+     * before any request (`MYPARCEL_LABEL_INPUT_INVALID`, `ValidationError`).
+     *
+     * @effect money
+     * @permission ReadOrder
+     */
+    status(shipmentIds: readonly number[], format: FulfillmentLabelFormat, options?: Call): Promise<MyparcelLabelReadiness>;
+    /**
+     * One shipment's label as a PDF, fetched live from MyParcel and never cached: a link MyParcel
+     * mints expires within hours, so none is answered. For a fulfillment of several parcels,
+     * `admin.fulfillments.myparcelLabel` merges every parcel's label into one PDF; this answers only
+     * the parcel it names. Allowed up to 55s (`MYPARCEL_LABEL_TIMEOUT_MS`): the engine retries a
+     * slow MyParcel up to three times. Needs `ReadOrder`.
+     *
+     * Refused as `status` is. A MyParcel failure (a prepaid account's `402`, an outage) arrives as
+     * the engine's error.
+     *
+     * @effect money
+     * @permission ReadOrder
+     */
+    download(shipmentId: number, format: FulfillmentLabelFormat, options?: Call): Promise<MyparcelShipmentLabel>;
+    /**
+     * Ask MyParcel for one parcel's label in one format: the operator's request, made again even
+     * when the label is ready. It QUEUES the request and answers `pending`; the label lands when the
+     * job has run (the fulfillment's label fields, `status`, and the label webhook say so), and a
+     * refusal MyParcel answers then is recorded on the fulfillment, not thrown here. Needs
+     * `UpdateOrder`. For every parcel of a fulfillment at once, `admin.fulfillments.labelMyparcelParcels`.
+     *
+     * Takes no idempotency key: a repeat queues another request for the same parcel.
+     *
+     * Refused, with nothing queued: `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`) while the
+     * store has no set-up or has MyParcel switched off; `ENTITY_NOT_FOUND` (`NotFoundError`) for
+     * another store's or a missing fulfillment, before anything is read; `MYPARCEL_VALIDATION_ERROR`
+     * (`BusinessRuleError`, `details[].field` naming what to fix) for a cancelled fulfillment or a
+     * shipment it does not hold (reload: its parcels may have been replaced);
+     * `MYPARCEL_DECRYPTION_FAILED_ERROR` when the stored key no longer decrypts (save it again);
+     * `LOCATION_OUT_OF_SCOPE` (422) for a credential restricted to other stock locations. A blank fulfillment id, a shipment id
+     * that is not a positive integer or a format other than `A4`/`A6` is refused before any request
+     * (`MYPARCEL_LABEL_INPUT_INVALID`, `ValidationError`).
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    request(input: RequestMyparcelLabelInput, options?: Call): Promise<MyparcelLabelReadiness>;
+}
+/** `admin.shipping.myparcel`: the MyParcel integration of the store. */
+export interface MyparcelModule {
+    config: MyparcelConfigModule;
+    /**
+     * The carriers MyParcel offers, the same list for every store (cached by the engine for an
+     * hour). What a carrier can do for one address is not in it. Needs `ReadSettings`; a store
+     * without the MyParcel plugin is refused `PLUGIN_ACCESS_DENIED` (403).
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    carriers(options?: Call): Promise<MyparcelCarrier[]>;
+    /**
+     * What each carrier can ship (package types, delivery types, countries, options, pickup), from
+     * the engine's static table: no call to MyParcel, the same for every store. Needs
+     * `ReadSettings`.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    carrierCapabilities(options?: Call): Promise<MyparcelCarrierCapability[]>;
+    /**
+     * MyParcel's delivery windows, with its base rate, and pickup points for one destination: one
+     * live call to MyParcel with the store's key. A quote: nothing is booked or billed. Needs
+     * `ReadOrder`.
+     *
+     * Refused: `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`) when the store has no set-up
+     * (a set-up switched off is still answered); `MYPARCEL_DECRYPTION_FAILED_ERROR` (save the key
+     * again); `MYPARCEL_API_ERROR` for MyParcel's own refusal or outage. A blank postal code is
+     * refused before any request (`INVALID_INPUT`, `ValidationError`, `details[0].field:
+     * 'postalCode'`).
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    deliveryOptions(input: MyparcelDeliveryOptionsInput, options?: Call): Promise<MyparcelDeliveryOptions>;
+    senders: MyparcelSendersModule;
+    /** The store's MyParcel shipments: read live, booked again, or imported from the backoffice. */
+    shipments: MyparcelShipmentsModule;
+    /** Whether a shipment's label is made, the label itself, and asking for it again. */
+    labels: MyparcelLabelsModule;
+    /** Return labels for the store's shipments. */
+    returns: MyparcelReturnsModule;
+}
+export declare const MYPARCEL_CONFIG_QUERY = "\n  query MyparcelConfig {\n    myparcelConfig { \n  id\n  channelId\n  hasApiKey\n  maskedApiKey\n  maskedWebhookSecret\n  defaultLabelFormat\n  enabled\n }\n  }\n";
+export declare const UPDATE_MYPARCEL_CONFIG_MUTATION = "\n  mutation UpdateMyparcelConfig($input: MyparcelConfigInput!) {\n    updateMyparcelConfig(input: $input) {\n      \n  __typename\n  ... on MyparcelConfig { \n  id\n  channelId\n  hasApiKey\n  maskedApiKey\n  maskedWebhookSecret\n  defaultLabelFormat\n  enabled\n }\n  ... on ErrorResult { errorCode message }\n\n      ... on MyparcelValidationError { errors }\n    }\n  }\n";
+export declare const UPDATE_MYPARCEL_LABEL_FORMAT_MUTATION = "\n  mutation UpdateMyparcelLabelFormat($input: MyparcelLabelFormatInput!) {\n    updateMyparcelLabelFormat(input: $input) { \n  __typename\n  ... on MyparcelConfig { \n  id\n  channelId\n  hasApiKey\n  maskedApiKey\n  maskedWebhookSecret\n  defaultLabelFormat\n  enabled\n }\n  ... on ErrorResult { errorCode message }\n }\n  }\n";
+export declare const SET_MYPARCEL_ENABLED_MUTATION = "\n  mutation SetMyparcelEnabled($enabled: Boolean!) {\n    setMyparcelEnabled(enabled: $enabled) {\n      \n  __typename\n  ... on MyparcelConfig { \n  id\n  channelId\n  hasApiKey\n  maskedApiKey\n  maskedWebhookSecret\n  defaultLabelFormat\n  enabled\n }\n  ... on ErrorResult { errorCode message }\n\n      ... on MyparcelValidationError { errors }\n    }\n  }\n";
+export declare const REGENERATE_MYPARCEL_WEBHOOK_SECRET_MUTATION = "\n  mutation RegenerateMyparcelWebhookSecret {\n    regenerateMyparcelWebhookSecret { \n  __typename\n  ... on MyparcelConfig { \n  id\n  channelId\n  hasApiKey\n  maskedApiKey\n  maskedWebhookSecret\n  defaultLabelFormat\n  enabled\n }\n  ... on ErrorResult { errorCode message }\n }\n  }\n";
+export declare const MYPARCEL_CARRIERS_QUERY = "\n  query MyparcelCarriers {\n    myparcelCarriers {\n      id\n      name\n      human\n      meta { logoSvg logoPng }\n    }\n  }\n";
+export declare const MYPARCEL_SENDERS_QUERY = "\n  query MyparcelSenderStockLocations {\n    myparcelSenderStockLocations { \n  id\n  name\n  address {\n    streetLine1\n    streetLine2\n    city\n    postalCode\n    province\n    countryCode\n    phoneNumber\n    contactName\n    company\n  }\n  isDefaultSender\n  isResolvable\n }\n  }\n";
+export declare const SET_MYPARCEL_SENDER_MUTATION = "\n  mutation SetStockLocationSender($input: MyparcelSetStockLocationSenderInput!) {\n    setStockLocationSender(input: $input) {\n      __typename\n      ... on MyparcelSenderStockLocationSummary { \n  id\n  name\n  address {\n    streetLine1\n    streetLine2\n    city\n    postalCode\n    province\n    countryCode\n    phoneNumber\n    contactName\n    company\n  }\n  isDefaultSender\n  isResolvable\n }\n      ... on ErrorResult { errorCode message }\n      ... on MyparcelInvalidSenderError { fields }\n    }\n  }\n";
+export declare const MYPARCEL_SHIPMENT_QUERY = "\n  query MyparcelShipment($shipmentId: Int!) {\n    myparcelShipment(shipmentId: $shipmentId) {\n      id\n      referenceIdentifier\n      barcode\n      status\n      carrierId\n      created\n      modified\n      linkConsumerPortal\n    }\n  }\n";
+/** Readiness only: the engine answers no link (it would outlive every check made on it). */
+export declare const MYPARCEL_LABEL_STATUS_QUERY = "\n  query MyparcelLabelStatus($shipmentIds: [Int!]!, $format: MyparcelLabelFormatEnum!) {\n    myparcelShipmentLabelUrl(shipmentIds: $shipmentIds, format: $format) {\n      status\n    }\n  }\n";
+export declare const MYPARCEL_SHIPMENT_LABEL_MUTATION = "\n  mutation MyparcelShipmentLabel($shipmentId: Int!, $format: MyparcelLabelFormatEnum!) {\n    getMyparcelLabel(shipmentId: $shipmentId, format: $format) {\n      format\n      base64\n      contentType\n      filename\n    }\n  }\n";
+export declare const REQUEST_MYPARCEL_LABEL_MUTATION = "\n  mutation RequestMyparcelLabel($input: MyparcelRequestLabelInput!) {\n    requestMyparcelLabel(input: $input) {\n      __typename\n      ... on MyparcelLabelResult { status }\n      ... on ErrorResult { errorCode message }\n      ... on MyparcelValidationError { errors }\n    }\n  }\n";
+export declare const MYPARCEL_CARRIER_CAPABILITIES_QUERY = "\n  query MyparcelCarrierCapabilities {\n    myparcelCarrierCapabilities {\n      carrierId\n      name\n      packageTypes\n      deliveryTypes\n      countries\n      supportedOptions\n      supportsPickup\n      constraints\n    }\n  }\n";
+export declare const MYPARCEL_DELIVERY_OPTIONS_QUERY = "\n  query MyparcelAdminDeliveryOptions($input: MyparcelAdminDeliveryOptionsInput!) {\n    myparcelAdminDeliveryOptions(input: $input) {\n      __typename\n      ... on MyparcelAdminDeliveryOptions {\n        deliveryOptions {\n          deliveryType\n          date\n          startTime\n          endTime\n          price { amount currency }\n        }\n        pickupOptions {\n          locationCode\n          locationName\n          street\n          number\n          numberSuffix\n          postalCode\n          city\n          countryCode\n          carrierId\n          distance\n        }\n      }\n      ... on ErrorResult { errorCode message }\n      ... on MyparcelValidationError { errors }\n    }\n  }\n";
+export declare const RECREATE_MYPARCEL_SHIPMENT_MUTATION = "\n  mutation RecreateMyparcelShipment($input: MyparcelRecreateShipmentInput!) {\n    recreateMyparcelShipment(input: $input) {\n      __typename\n      ... on MyparcelShipmentMutationResult { shipmentId labelFormat }\n      \n  ... on ErrorResult { errorCode message }\n  ... on MyparcelValidationError { errors }\n  ... on MyparcelInvalidRecipientError { missingFields }\n  ... on MyparcelInvalidSenderError { fields }\n  ... on MyparcelPickupLocationInvalidError { fields }\n\n    }\n  }\n";
+export declare const IMPORT_MYPARCEL_SHIPMENT_MUTATION = "\n  mutation ImportMyparcelShipment($input: MyparcelImportShipmentInput!) {\n    importMyparcelShipment(input: $input) {\n      __typename\n      ... on MyparcelShipmentMutationResult { shipmentId labelFormat }\n      ... on ErrorResult { errorCode message }\n      ... on MyparcelValidationError { errors }\n    }\n  }\n";
+export declare const CREATE_MYPARCEL_RETURN_MUTATION = "\n  mutation CreateMyparcelReturnShipment($input: MyparcelReturnShipmentInput!) {\n    createMyparcelReturnShipment(input: $input) {\n      __typename\n      ... on MyparcelReturnShipmentResult { shipmentId }\n      ... on ErrorResult { errorCode message }\n      ... on MyparcelValidationError { errors }\n    }\n  }\n";
+/**
+ * A refusal member as its error class, by core's `errorFromErrorResult`. The field names a member
+ * carries (`MyparcelInvalidSenderError.fields`, `MyparcelPickupLocationInvalidError.fields`,
+ * `MyparcelValidationError.errors`, `MyparcelInvalidRecipientError.missingFields`) ride
+ * `details[]`, one per field, so a form can mark each without matching the sentence.
+ */
+export declare function myparcelRefusal(result: VendureErrorResult): PlatformError;
+export declare function createMyparcelModule(transport: Transport): MyparcelModule;