includio-cms 0.15.2 → 0.15.4

package/dist/shop/adapters/inpost/geowidget.js

@@ -0,0 +1,31 @@
+/**
+ * Geowidget v5 (Web Component) config used by `<InpostPicker>` on the frontend.
+ * The token is a public read-only "geowidget v5" token from your InPost account
+ * (https://manager.paczkomaty.pl). It must be delivered to the browser — do not
+ * pass private ShipX tokens here.
+ *
+ * Docs: https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/50069505/Geowidget+v5
+ */
+const GEOWIDGET_URLS = {
+    production: {
+        script: 'https://geowidget.inpost.pl/inpost-geowidget.js',
+        stylesheet: 'https://geowidget.inpost.pl/inpost-geowidget.css'
+    },
+    sandbox: {
+        script: 'https://sandbox-easy-geowidget-sdk.easypack24.net/inpost-geowidget.js',
+        stylesheet: 'https://sandbox-easy-geowidget-sdk.easypack24.net/inpost-geowidget.css'
+    }
+};
+export function buildGeowidgetDescriptor(opts) {
+    const env = opts.environment ?? 'production';
+    const urls = GEOWIDGET_URLS[env];
+    return {
+        scriptUrl: urls.script,
+        stylesheetUrl: urls.stylesheet,
+        config: {
+            token: opts.token,
+            language: opts.language ?? 'pl',
+            config: opts.config ?? 'parcelcollect'
+        }
+    };
+}

package/dist/shop/adapters/inpost/index.d.ts

@@ -0,0 +1,89 @@
+import type { CarrierAdapter, I18nText } from '../../types.js';
+import { type GeowidgetConfigPreset } from './geowidget.js';
+import { type InpostEnvironment } from './points-api.js';
+export interface InpostSenderAddress {
+    name: string;
+    company?: string;
+    street: string;
+    buildingNumber?: string;
+    city: string;
+    postCode: string;
+    countryCode?: string;
+    email: string;
+    phone: string;
+}
+export interface InpostAdapterOptions {
+    /**
+     * Public Geowidget v5 token (read-only). Delivered to the browser via
+     * `GET /api/shop/carriers/inpost`.
+     */
+    geowidgetToken: string;
+    /**
+     * Private ShipX organization-scoped token (`Bearer`). Used server-side for
+     * shipment creation, label fetching, cancellation. Optional in geowidget-only
+     * setups (Etap 2). Required for ShipX shipment operations (Etap 3).
+     */
+    shipxToken?: string;
+    /** ShipX organization ID, e.g. `123456`. Required when shipxToken is set. */
+    organizationId?: string;
+    /** `production` (default) or `sandbox`. Controls all ShipX endpoints. */
+    environment?: InpostEnvironment;
+    /**
+     * Shared secret used to authenticate webhook calls. Pass it as `?secret=`
+     * query in the `notifyUrl` you configure in the ShipX panel.
+     */
+    webhookSecret?: string;
+    /** Absolute URL ShipX should POST shipment events to. */
+    notifyUrl?: string;
+    /** Sender pickup address used for ShipX shipment creation. */
+    senderAddress?: InpostSenderAddress;
+    /**
+     * Tracking link template. `{trackingNumber}` is replaced. Default:
+     * `https://inpost.pl/sledzenie-przesylek?number={trackingNumber}`.
+     */
+    trackingUrlTemplate?: string;
+    /** Default geowidget preset. Default: `parcelCollect`. */
+    geowidgetPreset?: GeowidgetConfigPreset;
+    /** Default geowidget language. Default: `pl`. */
+    geowidgetLanguage?: string;
+    /** Cache TTL for Points API validation (ms). Default 5 min. */
+    pointsCacheTtlMs?: number;
+    /** Default ShipX label format (PDF). */
+    labelFormat?: 'Pdf' | 'ZebraLP';
+    /** Default ShipX label paper size. */
+    labelSize?: 'A4' | 'A6';
+    /** Additional ShipX services attached to every shipment (e.g. ['email', 'sms']). */
+    additionalServices?: string[];
+    /**
+     * After POST /shipments, automatically call POST /shipments/:id/buy to
+     * confirm the auto-selected offer. Required for accounts (esp. sandbox)
+     * where ShipX leaves shipments in `offer_selected` instead of paying
+     * automatically. Default `true`. Set `false` if your org is configured
+     * for full auto-pay or you handle confirmation yourself.
+     */
+    autoConfirm?: boolean;
+    /**
+     * Delay between POST /shipments and POST /shipments/:id/buy (ms). ShipX
+     * needs a brief moment to prepare the offer. Default 1500ms.
+     */
+    autoConfirmDelayMs?: number;
+    /**
+     * After POST /shipments/:id/buy, poll GET /shipments/:id every second
+     * until the status leaves `offer_selected` (becomes `confirmed` or further).
+     * ShipX buying is asynchronous — production is fast (~1s), sandbox can
+     * take minutes. Default 8000ms. Set 0 to disable polling and rely on
+     * the webhook to reconcile.
+     */
+    autoConfirmPollTimeoutMs?: number;
+    /**
+     * Verbose adapter logging — payload dumps, every poll tick, offer details.
+     * Off by default. Turn on when troubleshooting sandbox stalls or unexpected
+     * ShipX responses. Errors and the post-timeout stall warning always log.
+     */
+    debug?: boolean;
+    fetch?: typeof fetch;
+    id?: string;
+    label?: I18nText;
+}
+export declare function inpostAdapter(opts: InpostAdapterOptions): CarrierAdapter;
+export type { GeowidgetConfigPreset, InpostEnvironment };

package/dist/shop/adapters/inpost/index.js

@@ -0,0 +1,156 @@
+import { buildGeowidgetDescriptor } from './geowidget.js';
+import { buildShipmentPayload } from './payload.js';
+import { createPointsValidator } from './points-api.js';
+import { ShipxClient } from './shipx-client.js';
+import { parseShipxWebhook } from './webhook.js';
+const DEFAULT_LABEL = { pl: 'InPost', en: 'InPost' };
+const DEFAULT_TRACKING_TEMPLATE = 'https://inpost.pl/sledzenie-przesylek?number={trackingNumber}';
+export function inpostAdapter(opts) {
+    if (!opts.geowidgetToken) {
+        throw new Error('inpostAdapter: `geowidgetToken` is required.');
+    }
+    const id = opts.id ?? 'inpost';
+    const env = opts.environment ?? 'production';
+    const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const points = createPointsValidator({
+        environment: env,
+        fetch: fetchFn,
+        cacheTtlMs: opts.pointsCacheTtlMs
+    });
+    const widgetDesc = buildGeowidgetDescriptor({
+        token: opts.geowidgetToken,
+        environment: env,
+        language: opts.geowidgetLanguage,
+        config: opts.geowidgetPreset
+    });
+    const trackingTemplate = opts.trackingUrlTemplate ?? DEFAULT_TRACKING_TEMPLATE;
+    function requireShipx() {
+        if (!opts.shipxToken) {
+            throw new Error('inpostAdapter: `shipxToken` is required for ShipX shipment operations.');
+        }
+        if (!opts.organizationId) {
+            throw new Error('inpostAdapter: `organizationId` is required for ShipX shipment operations.');
+        }
+        return new ShipxClient({
+            token: opts.shipxToken,
+            organizationId: opts.organizationId,
+            environment: env,
+            fetch: fetchFn
+        });
+    }
+    return {
+        id,
+        label: opts.label ?? DEFAULT_LABEL,
+        widget: {
+            scriptUrl: widgetDesc.scriptUrl,
+            stylesheetUrl: widgetDesc.stylesheetUrl,
+            config: { ...widgetDesc.config }
+        },
+        async validateSelection(ref, ctx) {
+            const serviceType = ctx?.serviceType;
+            // Courier service ships to a street address — no parcel locker code expected.
+            if (!serviceType || serviceType.startsWith('inpost_courier_'))
+                return true;
+            if (!ref)
+                return false;
+            return points.validate(ref);
+        },
+        async createShipment(input) {
+            const client = requireShipx();
+            const debug = opts.debug === true;
+            const log = (msg) => {
+                if (debug)
+                    console.log(msg);
+            };
+            const payload = buildShipmentPayload({
+                input,
+                sender: opts.senderAddress,
+                additionalServices: opts.additionalServices
+            });
+            log(`[inpost] createShipment: order=${input.order.number} service=${input.serviceType} carrierRef=${input.carrierRef ?? '—'}`);
+            if (debug)
+                console.log('[inpost] payload →', JSON.stringify(payload, null, 2));
+            let shipment = await client.createShipment(payload);
+            log(`[inpost] POST /shipments → id=${shipment.id} status=${shipment.status} tracking=${shipment.tracking_number ?? 'null'}`);
+            if (opts.autoConfirm !== false) {
+                const delay = opts.autoConfirmDelayMs ?? 1500;
+                if (delay > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                try {
+                    const fresh = await client.getShipment(shipment.id);
+                    log(`[inpost] shipment now: status=${fresh.status} selected_offer=${fresh.selected_offer?.id ?? 'null'} offers=${fresh.offers?.length ?? 0}`);
+                    const offerId = fresh.selected_offer?.id ??
+                        (Array.isArray(fresh.offers) && fresh.offers.length > 0
+                            ? fresh.offers[0].id
+                            : undefined);
+                    if (offerId == null) {
+                        throw new Error(`Shipment ${shipment.id} has no selected_offer / offers yet (status=${fresh.status})`);
+                    }
+                    log(`[inpost] POST /shipments/${shipment.id}/buy {offer_id: ${offerId}}`);
+                    const buyResult = await client.buyShipment(shipment.id, offerId);
+                    // Polling: ShipX buy is asynchronous. Wait until we leave the
+                    // offer_selected/created state, or give up and let the webhook reconcile.
+                    const pollTimeout = opts.autoConfirmPollTimeoutMs ?? 8000;
+                    const pollIntervalMs = 1000;
+                    const deadline = Date.now() + pollTimeout;
+                    shipment = buyResult;
+                    while (pollTimeout > 0 &&
+                        Date.now() < deadline &&
+                        (shipment.status === 'offer_selected' || shipment.status === 'created')) {
+                        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+                        shipment = await client.getShipment(shipment.id);
+                        log(`[inpost] poll → status=${shipment.status} tracking=${shipment.tracking_number ?? 'null'}`);
+                    }
+                    log(`[inpost] final shipment: status=${shipment.status} tracking=${shipment.tracking_number ?? 'null'}`);
+                    if (shipment.status === 'offer_selected' || shipment.status === 'created') {
+                        console.warn(`[inpost] shipment ${shipment.id} still in '${shipment.status}' after ${pollTimeout}ms — sandbox often stalls here without a wallet/payment configured. Webhook will reconcile if/when ShipX completes the purchase.`);
+                    }
+                }
+                catch (err) {
+                    // Auto-confirm is best-effort. If the offer isn't ready, the
+                    // account is configured for full auto-pay, or the offer was
+                    // already bought, the webhook will reconcile the final status.
+                    console.warn(`[inpost] auto-confirm failed for shipment ${shipment.id} — webhook will reconcile.`);
+                    if (err instanceof Error) {
+                        console.warn(`[inpost] ${err.name}: ${err.message}`);
+                        const body = err.body;
+                        if (body !== undefined) {
+                            console.warn('[inpost] error body:', typeof body === 'string' ? body : JSON.stringify(body));
+                        }
+                    }
+                    else {
+                        console.warn('[inpost] auto-confirm error:', err);
+                    }
+                }
+            }
+            return {
+                shipmentId: String(shipment.id),
+                trackingNumber: shipment.tracking_number ?? '',
+                raw: shipment
+            };
+        },
+        async getShipmentLabel(shipmentId, labelOpts) {
+            const client = requireShipx();
+            const { contentType, body } = await client.getLabel(shipmentId, {
+                format: opts.labelFormat ?? 'Pdf',
+                type: labelOpts?.size ?? opts.labelSize ?? 'A6'
+            });
+            return {
+                contentType,
+                body,
+                filename: `inpost-${shipmentId}.pdf`
+            };
+        },
+        async cancelShipment(shipmentId) {
+            const client = requireShipx();
+            await client.cancelShipment(shipmentId);
+        },
+        async handleWebhook(req) {
+            return parseShipxWebhook(req, { secret: opts.webhookSecret });
+        },
+        trackingUrl(trackingNumber) {
+            return trackingTemplate.replace('{trackingNumber}', encodeURIComponent(trackingNumber));
+        }
+    };
+}

package/dist/shop/adapters/inpost/payload.d.ts

@@ -0,0 +1,18 @@
+import type { ShipmentCreateInput } from '../../types.js';
+import type { InpostSenderAddress } from './index.js';
+export declare function mapParcelSize(size: string | undefined): string;
+export declare function splitFullName(full: string | null | undefined): {
+    firstName?: string;
+    lastName?: string;
+};
+export interface BuildShipmentPayloadOptions {
+    input: ShipmentCreateInput;
+    sender?: InpostSenderAddress;
+    additionalServices?: string[];
+}
+/**
+ * Build a ShipX `POST /shipments` body for a given order. Locker services attach
+ * `custom_attributes.target_point` (paczkomat code from `carrierRef`); courier
+ * services use the receiver address from the order's shipping_address instead.
+ */
+export declare function buildShipmentPayload(opts: BuildShipmentPayloadOptions): Record<string, unknown>;

package/dist/shop/adapters/inpost/payload.js

@@ -0,0 +1,85 @@
+const SIZE_TO_TEMPLATE = {
+    A: 'small',
+    B: 'medium',
+    C: 'large',
+    small: 'small',
+    medium: 'medium',
+    large: 'large'
+};
+export function mapParcelSize(size) {
+    if (!size)
+        return 'small';
+    return SIZE_TO_TEMPLATE[size] ?? 'small';
+}
+export function splitFullName(full) {
+    if (!full)
+        return {};
+    const trimmed = full.trim();
+    if (!trimmed)
+        return {};
+    const parts = trimmed.split(/\s+/);
+    if (parts.length === 1)
+        return { firstName: parts[0] };
+    return { firstName: parts[0], lastName: parts.slice(1).join(' ') };
+}
+/**
+ * Build a ShipX `POST /shipments` body for a given order. Locker services attach
+ * `custom_attributes.target_point` (paczkomat code from `carrierRef`); courier
+ * services use the receiver address from the order's shipping_address instead.
+ */
+export function buildShipmentPayload(opts) {
+    const { input, sender, additionalServices } = opts;
+    const isLocker = input.serviceType.startsWith('inpost_locker_');
+    const isCourier = input.serviceType.startsWith('inpost_courier_');
+    const names = splitFullName(input.order.customerName);
+    const receiver = {
+        first_name: names.firstName ?? input.order.customerEmail,
+        last_name: names.lastName ?? '—',
+        email: input.order.customerEmail,
+        phone: input.order.customerPhone ?? undefined
+    };
+    if (isCourier) {
+        const addr = input.shippingAddress ?? {};
+        receiver.address = {
+            street: addr.street ?? addr.line1 ?? '',
+            building_number: addr.buildingNumber ?? addr.building_number ?? '',
+            city: addr.city ?? '',
+            post_code: addr.postCode ?? addr.post_code ?? addr.zip ?? '',
+            country_code: addr.countryCode ?? addr.country_code ?? 'PL'
+        };
+    }
+    const payload = {
+        receiver,
+        parcels: [{ template: mapParcelSize(input.parcelSize) }],
+        service: input.serviceType,
+        reference: input.order.number
+    };
+    if (isLocker && input.carrierRef) {
+        payload.custom_attributes = { target_point: input.carrierRef };
+    }
+    if (sender) {
+        payload.sender = {
+            name: sender.name,
+            company_name: sender.company,
+            email: sender.email,
+            phone: sender.phone,
+            address: {
+                street: sender.street,
+                building_number: sender.buildingNumber,
+                city: sender.city,
+                post_code: sender.postCode,
+                country_code: sender.countryCode ?? 'PL'
+            }
+        };
+    }
+    if (input.insuranceAmount && input.insuranceAmount > 0) {
+        payload.insurance = { amount: input.insuranceAmount, currency: 'PLN' };
+    }
+    if (input.cod && input.cod > 0) {
+        payload.cod = { amount: input.cod, currency: 'PLN' };
+    }
+    if (additionalServices && additionalServices.length > 0) {
+        payload.additional_services = additionalServices;
+    }
+    return payload;
+}

package/dist/shop/adapters/inpost/points-api.d.ts

@@ -0,0 +1,17 @@
+/**
+ * InPost Points API — public, no auth required. Used to validate that a parcel
+ * locker code (e.g. "KRA01M") refers to a real, currently operating point.
+ *
+ * https://api-shipx-pl.easypack24.net/v1/points/{name}
+ */
+export type InpostEnvironment = 'production' | 'sandbox';
+export interface PointsApiOptions {
+    environment?: InpostEnvironment;
+    fetch?: typeof fetch;
+    cacheTtlMs?: number;
+}
+export interface PointsValidator {
+    validate(code: string): Promise<boolean>;
+    clearCache(): void;
+}
+export declare function createPointsValidator(opts?: PointsApiOptions): PointsValidator;

package/dist/shop/adapters/inpost/points-api.js

@@ -0,0 +1,55 @@
+/**
+ * InPost Points API — public, no auth required. Used to validate that a parcel
+ * locker code (e.g. "KRA01M") refers to a real, currently operating point.
+ *
+ * https://api-shipx-pl.easypack24.net/v1/points/{name}
+ */
+const POINTS_BASE_URL = {
+    production: 'https://api-shipx-pl.easypack24.net',
+    sandbox: 'https://sandbox-api-shipx-pl.easypack24.net'
+};
+export function createPointsValidator(opts = {}) {
+    const env = opts.environment ?? 'production';
+    const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const cacheTtl = opts.cacheTtlMs ?? 5 * 60 * 1000;
+    const cache = new Map();
+    async function validate(code) {
+        const trimmed = code.trim();
+        if (!trimmed)
+            return false;
+        const now = Date.now();
+        const cached = cache.get(trimmed);
+        if (cached && cached.expiresAt > now)
+            return cached.value;
+        const url = `${POINTS_BASE_URL[env]}/v1/points/${encodeURIComponent(trimmed)}`;
+        let ok = false;
+        try {
+            const res = await fetchFn(url, {
+                method: 'GET',
+                headers: { Accept: 'application/json' }
+            });
+            if (res.status === 404) {
+                ok = false;
+            }
+            else if (res.ok) {
+                const data = (await res.json());
+                ok = data.status === 'Operating';
+            }
+            else {
+                // Transient/server error — fail open to avoid blocking checkout.
+                // Skip caching so a retry can succeed.
+                return true;
+            }
+        }
+        catch {
+            // Network failure — fail open. Don't cache.
+            return true;
+        }
+        cache.set(trimmed, { value: ok, expiresAt: now + cacheTtl });
+        return ok;
+    }
+    function clearCache() {
+        cache.clear();
+    }
+    return { validate, clearCache };
+}

package/dist/shop/adapters/inpost/shipx-client.d.ts

@@ -0,0 +1,56 @@
+import type { InpostEnvironment } from './points-api.js';
+export interface ShipxClientOptions {
+    token: string;
+    organizationId: string;
+    environment?: InpostEnvironment;
+    fetch?: typeof fetch;
+}
+export interface ShipxOffer {
+    id: number | string;
+    carrier_id?: string;
+    service_id?: string;
+    status?: string;
+    rate?: number;
+    [key: string]: unknown;
+}
+export interface ShipxShipment {
+    id: number | string;
+    status: string;
+    tracking_number?: string | null;
+    created_at?: string;
+    selected_offer?: ShipxOffer | null;
+    offers?: ShipxOffer[];
+    [key: string]: unknown;
+}
+export declare class ShipxApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+export declare class ShipxClient {
+    private readonly base;
+    private readonly orgPath;
+    private readonly headers;
+    private readonly fetchFn;
+    constructor(opts: ShipxClientOptions);
+    createShipment(payload: Record<string, unknown>): Promise<ShipxShipment>;
+    getShipment(id: string | number): Promise<ShipxShipment>;
+    cancelShipment(id: string | number): Promise<void>;
+    /**
+     * Confirm/buy a specific offer for the shipment. Required when the account
+     * is not configured for fully-automatic offer payment (typical on sandbox).
+     * After this, status moves from `offer_selected` → `confirmed`.
+     *
+     * `offerId` is taken from `shipment.selected_offer.id` (or `offers[0].id`).
+     */
+    buyShipment(id: string | number, offerId: string | number): Promise<ShipxShipment>;
+    getLabel(id: string | number, opts?: {
+        format?: 'Pdf' | 'ZebraLP';
+        type?: 'A4' | 'A6';
+    }): Promise<{
+        contentType: string;
+        body: Uint8Array;
+    }>;
+    private request;
+    private requestRaw;
+}

package/dist/shop/adapters/inpost/shipx-client.js

@@ -0,0 +1,95 @@
+const SHIPX_BASE_URL = {
+    production: 'https://api-shipx-pl.easypack24.net',
+    sandbox: 'https://sandbox-api-shipx-pl.easypack24.net'
+};
+export class ShipxApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ShipxApiError';
+    }
+}
+export class ShipxClient {
+    base;
+    orgPath;
+    headers;
+    fetchFn;
+    constructor(opts) {
+        if (!opts.token)
+            throw new Error('ShipxClient: token required.');
+        if (!opts.organizationId)
+            throw new Error('ShipxClient: organizationId required.');
+        const env = opts.environment ?? 'production';
+        this.base = SHIPX_BASE_URL[env];
+        this.orgPath = `/v1/organizations/${encodeURIComponent(opts.organizationId)}`;
+        this.headers = {
+            Authorization: `Bearer ${opts.token}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json'
+        };
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async createShipment(payload) {
+        return this.request('POST', `${this.orgPath}/shipments`, payload);
+    }
+    async getShipment(id) {
+        return this.request('GET', `/v1/shipments/${encodeURIComponent(String(id))}`);
+    }
+    async cancelShipment(id) {
+        await this.requestRaw('DELETE', `/v1/shipments/${encodeURIComponent(String(id))}`);
+    }
+    /**
+     * Confirm/buy a specific offer for the shipment. Required when the account
+     * is not configured for fully-automatic offer payment (typical on sandbox).
+     * After this, status moves from `offer_selected` → `confirmed`.
+     *
+     * `offerId` is taken from `shipment.selected_offer.id` (or `offers[0].id`).
+     */
+    async buyShipment(id, offerId) {
+        return this.request('POST', `/v1/shipments/${encodeURIComponent(String(id))}/buy`, { offer_id: typeof offerId === 'string' ? Number(offerId) : offerId });
+    }
+    async getLabel(id, opts = {}) {
+        const format = opts.format ?? 'Pdf';
+        const type = opts.type ?? 'A6';
+        const url = `${this.base}/v1/shipments/${encodeURIComponent(String(id))}/label?format=${format}&type=${type}`;
+        const res = await this.fetchFn(url, {
+            method: 'GET',
+            headers: { Authorization: this.headers.Authorization, Accept: 'application/pdf' }
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new ShipxApiError(`ShipX label fetch failed (${res.status}): ${text || res.statusText}`, res.status, text);
+        }
+        const buf = new Uint8Array(await res.arrayBuffer());
+        return { contentType: res.headers.get('content-type') ?? 'application/pdf', body: buf };
+    }
+    async request(method, path, body) {
+        const res = await this.requestRaw(method, path, body);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new ShipxApiError(`ShipX returned non-JSON response (${res.status})`, res.status, text);
+        }
+    }
+    async requestRaw(method, path, body) {
+        const res = await this.fetchFn(`${this.base}${path}`, {
+            method,
+            headers: this.headers,
+            body: body ? JSON.stringify(body) : undefined
+        });
+        if (!res.ok) {
+            const errBody = await res.text().catch(() => '');
+            throw new ShipxApiError(`ShipX ${method} ${path} failed (${res.status}): ${errBody || res.statusText}`, res.status, errBody);
+        }
+        return res;
+    }
+}

package/dist/shop/adapters/inpost/status-map.d.ts

@@ -0,0 +1,9 @@
+import type { CarrierEvent } from '../../types.js';
+/**
+ * Map a ShipX shipment status (from webhook payload or polling) to our domain
+ * OrderStatus. Returns `unknown` for transient/intermediate states the order
+ * lifecycle doesn't track — caller can ignore those.
+ *
+ * Reference: https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/28639231
+ */
+export declare function mapShipxStatus(status: string): CarrierEvent['status'];

package/dist/shop/adapters/inpost/status-map.js

@@ -0,0 +1,46 @@
+/**
+ * Map a ShipX shipment status (from webhook payload or polling) to our domain
+ * OrderStatus. Returns `unknown` for transient/intermediate states the order
+ * lifecycle doesn't track — caller can ignore those.
+ *
+ * Reference: https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/28639231
+ */
+export function mapShipxStatus(status) {
+    switch (status) {
+        case 'created':
+        case 'offers_prepared':
+        case 'offer_selected':
+        case 'confirmed':
+        case 'dispatched_by_sender_to_pok':
+        case 'dispatched_by_sender':
+        case 'collected_from_sender':
+        case 'taken_by_courier_from_pok':
+            return 'preparing';
+        case 'taken_by_courier':
+        case 'adopted_at_source_branch':
+        case 'sent_from_source_branch':
+        case 'adopted_at_sorting_center':
+        case 'sent_from_sorting_center':
+        case 'adopted_at_target_branch':
+        case 'out_for_delivery':
+        case 'ready_to_pickup':
+        case 'pickup_reminder_sent':
+        case 'pickup_time_expired':
+        case 'oversized':
+        case 'redirect_to_box':
+            return 'sent';
+        case 'delivered':
+            return 'done';
+        case 'canceled':
+        case 'cancelled':
+        case 'returned_to_sender':
+        case 'rejected':
+        case 'avizo':
+        case 'undelivered':
+        case 'unstored':
+        case 'claimed':
+            return 'cancelled';
+        default:
+            return 'unknown';
+    }
+}