includio-cms 0.15.2 → 0.15.4

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

@@ -0,0 +1,16 @@
+import type { CarrierEvent } from '../../types.js';
+export declare class WebhookSecretMismatchError extends Error {
+    constructor();
+}
+export interface ParseWebhookOptions {
+    /** Expected secret. When provided, the URL must carry `?secret=...` matching it. */
+    secret?: string;
+    /** Override query parameter name (default `secret`). */
+    secretParam?: string;
+}
+/**
+ * Parse a ShipX webhook request into a `CarrierEvent`. When `secret` is set the
+ * URL is checked first — mismatch throws `WebhookSecretMismatchError` so the
+ * caller can return 401 without parsing the body.
+ */
+export declare function parseShipxWebhook(req: Request, opts?: ParseWebhookOptions): Promise<CarrierEvent>;

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

@@ -0,0 +1,55 @@
+import { mapShipxStatus } from './status-map.js';
+/** Constant-time string compare, returns false on length mismatch. */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let mismatch = 0;
+    for (let i = 0; i < a.length; i++) {
+        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return mismatch === 0;
+}
+export class WebhookSecretMismatchError extends Error {
+    constructor() {
+        super('Webhook secret mismatch.');
+        this.name = 'WebhookSecretMismatchError';
+    }
+}
+/**
+ * Parse a ShipX webhook request into a `CarrierEvent`. When `secret` is set the
+ * URL is checked first — mismatch throws `WebhookSecretMismatchError` so the
+ * caller can return 401 without parsing the body.
+ */
+export async function parseShipxWebhook(req, opts = {}) {
+    if (opts.secret) {
+        const url = new URL(req.url);
+        const provided = url.searchParams.get(opts.secretParam ?? 'secret') ?? '';
+        if (!safeEqual(provided, opts.secret)) {
+            throw new WebhookSecretMismatchError();
+        }
+    }
+    const text = await req.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new Error('Webhook body is not valid JSON.');
+    }
+    const payload = body.payload ?? {
+        shipment_id: body.shipment_id,
+        status: body.status,
+        tracking_number: body.tracking_number ?? null
+    };
+    const shipmentId = payload.shipment_id;
+    const status = payload.status ?? '';
+    if (shipmentId === undefined || shipmentId === null) {
+        throw new Error('Webhook payload missing shipment_id.');
+    }
+    return {
+        shipmentId: String(shipmentId),
+        trackingNumber: payload.tracking_number ?? undefined,
+        status: mapShipxStatus(status),
+        raw: body
+    };
+}

package/dist/shop/client/index.d.ts

@@ -12,6 +12,9 @@ export interface ShippingMethodPublic {
     price: number;
     vatRate: number;
     carrierType: string;
+    carrierConfig: {
+        serviceType: string | null;
+    } | null;
     conditions: {
         freeAbove?: number;
     } | null;
@@ -61,6 +64,8 @@ export interface OrderDetailResponse {
         paymentMethod: string | null;
         carrierType: string | null;
         carrierRef: string | null;
+        trackingNumber: string | null;
+        trackingUrl: string | null;
         language: string | null;
         createdAt: string;
     };

package/dist/shop/http/carrier-handler.d.ts

@@ -0,0 +1,12 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * Public endpoint that returns front-end facing carrier widget descriptor for
+ * a given carrier id (e.g. `inpost`). The descriptor never contains private
+ * credentials — only what the browser needs to render the picker (e.g. public
+ * geowidget token + script URL).
+ *
+ * Mounted at `/api/shop/carriers/[id]`.
+ */
+export declare function createCarrierConfigHandler(): {
+    GET: RequestHandler;
+};

package/dist/shop/http/carrier-handler.js

@@ -0,0 +1,45 @@
+import { json } from '@sveltejs/kit';
+import { getCMS } from '../../core/cms.js';
+function shopEnabled() {
+    try {
+        return getCMS().shopConfig !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Public endpoint that returns front-end facing carrier widget descriptor for
+ * a given carrier id (e.g. `inpost`). The descriptor never contains private
+ * credentials — only what the browser needs to render the picker (e.g. public
+ * geowidget token + script URL).
+ *
+ * Mounted at `/api/shop/carriers/[id]`.
+ */
+export function createCarrierConfigHandler() {
+    return {
+        GET: async ({ params }) => {
+            if (!shopEnabled())
+                return json({ error: 'Shop not enabled' }, { status: 404 });
+            const id = params.id;
+            if (!id)
+                return json({ error: 'Carrier id required' }, { status: 400 });
+            const shop = getCMS().shopConfig;
+            const carrier = shop?.carriers.find((c) => c.id === id);
+            if (!carrier)
+                return json({ error: 'Carrier not found' }, { status: 404 });
+            if (!carrier.widget) {
+                return json({ id: carrier.id, label: carrier.label ?? null, widget: null });
+            }
+            return json({
+                id: carrier.id,
+                label: carrier.label ?? null,
+                widget: {
+                    scriptUrl: carrier.widget.scriptUrl ?? null,
+                    stylesheetUrl: carrier.widget.stylesheetUrl ?? null,
+                    config: carrier.widget.config
+                }
+            });
+        }
+    };
+}

package/dist/shop/http/carrier-webhook-handler.d.ts

@@ -0,0 +1,13 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * Public webhook receiver for carrier events (e.g. ShipX `shipment_status_changed`).
+ * Carrier id (`inpost`, ...) is taken from the route param, looked up in
+ * `shop.carriers`, and the adapter's `handleWebhook` parses + verifies the
+ * request. Successful events are applied to the matching order (tracking +
+ * status). Unknown shipments still return 200 to avoid retry storms.
+ *
+ * Mounted at `POST /api/shop/carriers/[id]/webhook`.
+ */
+export declare function createCarrierWebhookHandler(): {
+    POST: RequestHandler;
+};

package/dist/shop/http/carrier-webhook-handler.js

@@ -0,0 +1,66 @@
+import { json } from '@sveltejs/kit';
+import { getCMS } from '../../core/cms.js';
+import { checkRateLimit, clientKey } from '../rate-limit.js';
+import { applyCarrierEvent } from '../server/shipments.js';
+function shopEnabled() {
+    try {
+        return getCMS().shopConfig !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Public webhook receiver for carrier events (e.g. ShipX `shipment_status_changed`).
+ * Carrier id (`inpost`, ...) is taken from the route param, looked up in
+ * `shop.carriers`, and the adapter's `handleWebhook` parses + verifies the
+ * request. Successful events are applied to the matching order (tracking +
+ * status). Unknown shipments still return 200 to avoid retry storms.
+ *
+ * Mounted at `POST /api/shop/carriers/[id]/webhook`.
+ */
+export function createCarrierWebhookHandler() {
+    return {
+        POST: async ({ request, params }) => {
+            if (!shopEnabled())
+                return json({ error: 'Shop not enabled' }, { status: 404 });
+            const id = params.id;
+            if (!id)
+                return json({ error: 'Carrier id required' }, { status: 400 });
+            const shop = getCMS().shopConfig;
+            const adapter = shop?.carriers.find((c) => c.id === id);
+            if (!adapter)
+                return json({ error: 'Carrier not found' }, { status: 404 });
+            if (!adapter.handleWebhook) {
+                return json({ error: 'Carrier does not support webhooks' }, { status: 400 });
+            }
+            const rule = shop?.rateLimit.webhook ?? { limit: 60, windowSec: 60 };
+            const rl = checkRateLimit(clientKey(request, `webhook:${id}`), rule);
+            if (!rl.allowed) {
+                return json({ error: 'Rate limit exceeded' }, { status: 429 });
+            }
+            let event;
+            try {
+                event = await adapter.handleWebhook(request);
+            }
+            catch (err) {
+                const name = err instanceof Error ? err.name : '';
+                if (name === 'WebhookSecretMismatchError') {
+                    return json({ error: 'Unauthorized' }, { status: 401 });
+                }
+                const message = err instanceof Error ? err.message : 'Webhook parse error';
+                console.error(`[shop/carrier:${id}] webhook parse failed:`, err);
+                return json({ error: message }, { status: 400 });
+            }
+            try {
+                const result = await applyCarrierEvent(event);
+                return json({ ok: true, ...result });
+            }
+            catch (err) {
+                console.error(`[shop/carrier:${id}] applyCarrierEvent failed:`, err);
+                const message = err instanceof Error ? err.message : 'Apply event failed';
+                return json({ error: message }, { status: 500 });
+            }
+        }
+    };
+}

package/dist/shop/http/checkout-handler.js

@@ -3,6 +3,7 @@ import { getCMS } from '../../core/cms.js';
 import { readCartCookie, writeCartCookie } from '../cart/cookie.js';
 import { writeOrderTokenCookie } from '../cart/order-token-cookie.js';
 import { createOrderFromCart, setPaymentProviderRef } from '../server/orders.js';
+import { getShippingMethod } from '../server/shipping.js';
 import { checkRateLimit, clientKey } from '../rate-limit.js';
 import { requireShopConfig } from '../server/db.js';
 function shopEnabled() {
@@ -67,6 +68,27 @@ export function createCheckoutHandler() {
             if (cartItems.length === 0) {
                 return json({ error: 'Cart is empty' }, { status: 400 });
             }
+            const carrierRef = asString(body.carrierRef, 200);
+            // Carrier-side validation (e.g. paczkomat code → InPost Points API)
+            try {
+                const shippingMethod = await getShippingMethod(shippingMethodId);
+                if (shippingMethod && shippingMethod.carrierType !== 'none') {
+                    const shop = requireShopConfig();
+                    const carrier = shop.carriers.find((c) => c.id === shippingMethod.carrierType);
+                    if (carrier?.validateSelection) {
+                        const ok = await carrier.validateSelection(carrierRef ?? '', {
+                            serviceType: shippingMethod.carrierConfig?.serviceType
+                        });
+                        if (!ok) {
+                            return json({ error: 'Invalid carrier selection (e.g. paczkomat unavailable).' }, { status: 400 });
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                console.error('[shop] carrier validateSelection failed:', err);
+                return json({ error: 'Carrier validation failed.' }, { status: 400 });
+            }
             try {
                 const result = await createOrderFromCart({
                     cartItems,
@@ -75,7 +97,7 @@ export function createCheckoutHandler() {
                     customerPhone: asString(body.customerPhone, 40),
                     shippingAddress: asStringRecord(body.shippingAddress),
                     shippingMethodId,
-                    carrierRef: asString(body.carrierRef, 200),
+                    carrierRef,
                     paymentMethod,
                     consents: asConsents(body.consents),
                     notes: asString(body.notes, 2000),

package/dist/shop/http/index.d.ts

@@ -5,3 +5,6 @@ export { createOrderHandler } from './order-handler.js';
 export { createPaymentWebhookHandler } from './webhook-handler.js';
 export { createRefreshPaymentHandler } from './refresh-payment-handler.js';
 export { createRetryPaymentHandler } from './retry-payment-handler.js';
+export { createCarrierConfigHandler } from './carrier-handler.js';
+export { createCarrierWebhookHandler } from './carrier-webhook-handler.js';
+export { createShipmentLabelHandler } from './shipment-label-handler.js';

package/dist/shop/http/index.js

@@ -5,3 +5,6 @@ export { createOrderHandler } from './order-handler.js';
 export { createPaymentWebhookHandler } from './webhook-handler.js';
 export { createRefreshPaymentHandler } from './refresh-payment-handler.js';
 export { createRetryPaymentHandler } from './retry-payment-handler.js';
+export { createCarrierConfigHandler } from './carrier-handler.js';
+export { createCarrierWebhookHandler } from './carrier-webhook-handler.js';
+export { createShipmentLabelHandler } from './shipment-label-handler.js';

package/dist/shop/http/order-handler.js

@@ -43,6 +43,18 @@ export function createOrderHandler() {
                 getOrderItems(order.id),
                 getOrderStatusHistory(order.id)
             ]);
+            let trackingUrl = null;
+            if (order.carrierType && order.trackingNumber) {
+                const adapter = getCMS().shopConfig?.carriers.find((c) => c.id === order.carrierType);
+                if (adapter?.trackingUrl) {
+                    try {
+                        trackingUrl = adapter.trackingUrl(order.trackingNumber);
+                    }
+                    catch {
+                        trackingUrl = null;
+                    }
+                }
+            }
             return json({
                 order: {
                     id: order.id,
@@ -61,6 +73,8 @@ export function createOrderHandler() {
                     paymentMethod: order.paymentMethod,
                     carrierType: order.carrierType,
                     carrierRef: order.carrierRef,
+                    trackingNumber: order.trackingNumber,
+                    trackingUrl,
                     language: order.language,
                     createdAt: order.createdAt
                 },

package/dist/shop/http/shipment-label-handler.d.ts

@@ -0,0 +1,10 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * Admin-only PDF proxy that streams the carrier label without exposing the
+ * carrier's signed link or token to the browser.
+ *
+ * Mounted at `/api/shop/admin/orders/[id]/label`.
+ */
+export declare function createShipmentLabelHandler(): {
+    GET: RequestHandler;
+};

package/dist/shop/http/shipment-label-handler.js

@@ -0,0 +1,53 @@
+import { error } from '@sveltejs/kit';
+import { getCMS } from '../../core/cms.js';
+import { requireAuth } from '../../admin/remote/middleware/auth.js';
+import { getShipmentLabelForOrder } from '../server/shipments.js';
+function shopEnabled() {
+    try {
+        return getCMS().shopConfig !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Admin-only PDF proxy that streams the carrier label without exposing the
+ * carrier's signed link or token to the browser.
+ *
+ * Mounted at `/api/shop/admin/orders/[id]/label`.
+ */
+export function createShipmentLabelHandler() {
+    return {
+        GET: async ({ params, url }) => {
+            if (!shopEnabled())
+                error(404, 'Shop not enabled');
+            try {
+                requireAuth();
+            }
+            catch {
+                error(401, 'Unauthorized');
+            }
+            const orderId = params.id;
+            if (!orderId)
+                error(400, 'Order id required');
+            const sizeParam = url.searchParams.get('size');
+            const size = sizeParam === 'A4' || sizeParam === 'A6' ? sizeParam : undefined;
+            let label;
+            try {
+                label = await getShipmentLabelForOrder(orderId, { size });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'Label fetch failed';
+                error(400, message);
+            }
+            return new Response(new Uint8Array(label.body), {
+                status: 200,
+                headers: {
+                    'Content-Type': label.contentType,
+                    'Content-Disposition': `inline; filename="${label.filename ?? 'label.pdf'}"`,
+                    'Cache-Control': 'no-store'
+                }
+            });
+        }
+    };
+}

package/dist/shop/http/shipping-handler.js

@@ -23,6 +23,9 @@ export function createShippingMethodsHandler() {
                     price: m.price,
                     vatRate: m.vatRate,
                     carrierType: m.carrierType,
+                    carrierConfig: m.carrierConfig
+                        ? { serviceType: m.carrierConfig.serviceType ?? null }
+                        : null,
                     conditions: m.conditions,
                     allowedPaymentMethods: m.allowedPaymentMethods ?? null
                 }))

package/dist/shop/index.d.ts

@@ -3,4 +3,6 @@ export declare function defineShop(config: ShopConfig): ResolvedShopConfig;
 export { manualAdapter } from './adapters/manual/index.js';
 export { payuAdapter } from './adapters/payu/index.js';
 export type { PayuAdapterOptions } from './adapters/payu/index.js';
-export type { ShopConfig, ResolvedShopConfig, Currency, OrderStatus, PaymentAdapter, PaymentCreateContext, CarrierAdapter, ConsentConfig, ShopFeatures, PaymentCreateResult, PaymentEvent, OrderRef, I18nText } from './types.js';
+export { inpostAdapter } from './adapters/inpost/index.js';
+export type { InpostAdapterOptions, InpostSenderAddress, GeowidgetConfigPreset, InpostEnvironment } from './adapters/inpost/index.js';
+export type { ShopConfig, ResolvedShopConfig, Currency, OrderStatus, PaymentAdapter, PaymentCreateContext, CarrierAdapter, CarrierEvent, ShipmentCreateInput, ShipmentCreateResult, ShipmentLabel, ConsentConfig, ShopFeatures, PaymentCreateResult, PaymentEvent, OrderRef, I18nText } from './types.js';

package/dist/shop/index.js

@@ -17,3 +17,4 @@ export function defineShop(config) {
 }
 export { manualAdapter } from './adapters/manual/index.js';
 export { payuAdapter } from './adapters/payu/index.js';
+export { inpostAdapter } from './adapters/inpost/index.js';

package/dist/shop/server/email.js

@@ -3,6 +3,10 @@ import { resolveI18n } from '../pricing.js';
 import { getOrderById, getOrderItems } from './orders.js';
 import { requireShopConfig } from './db.js';
 import { buildOrderViewUrl } from './order-access-url.js';
+const TRACKING_LABEL = {
+    pl: { label: 'Numer śledzenia', linkLabel: 'Sprawdź status przesyłki ↗' },
+    en: { label: 'Tracking number', linkLabel: 'Track your shipment ↗' }
+};
 function formatPrice(cents, currency) {
     return new Intl.NumberFormat('pl-PL', {
         style: 'currency',
@@ -77,6 +81,15 @@ function renderHtml(ctx, intro) {
       <div style="font-size:16px;">Razem (brutto): <strong style="color:#5B4A9E;">${ctx.order.totalGross}</strong></div>
       <div style="color:#8888A0;font-size:12px;">netto ${ctx.order.totalNet} · VAT ${ctx.order.vatAmount}</div>
     </div>
+    ${ctx.tracking
+        ? `<div style="margin-top:20px;padding:16px;background:#F4F2FA;border-radius:10px;font-size:14px;">
+    <div style="color:#555566;margin-bottom:4px;">${escapeHtml(ctx.tracking.label)}</div>
+    <div style="font-family:ui-monospace,monospace;font-weight:700;word-break:break-all;">${escapeHtml(ctx.tracking.number)}</div>
+    ${ctx.tracking.url
+            ? `<a href="${escapeHtml(ctx.tracking.url)}" style="display:inline-block;margin-top:8px;color:#5B4A9E;font-weight:600;text-decoration:none;">${escapeHtml(ctx.tracking.linkLabel)}</a>`
+            : ''}
+  </div>`
+        : ''}
     ${ctx.viewUrl
         ? `<div style="margin-top:24px;text-align:center;"><a href="${escapeHtml(ctx.viewUrl)}" style="display:inline-block;background:#5B4A9E;color:#fff;text-decoration:none;padding:10px 18px;border-radius:8px;font-weight:600;">${escapeHtml(ctx.viewLinkLabel)}</a></div>`
         : ''}
@@ -115,9 +128,33 @@ export async function sendOrderStatusEmail(orderId, status) {
             language: order.language
         })
         : null;
+    let tracking;
+    if (order.trackingNumber &&
+        (status === 'sent' || status === 'done' || status === 'preparing')) {
+        const carrier = order.carrierType
+            ? shop.carriers.find((c) => c.id === order.carrierType)
+            : undefined;
+        const url = carrier?.trackingUrl
+            ? (() => {
+                try {
+                    return carrier.trackingUrl(order.trackingNumber);
+                }
+                catch {
+                    return null;
+                }
+            })()
+            : null;
+        tracking = {
+            number: order.trackingNumber,
+            url,
+            label: TRACKING_LABEL[subjectKey].label,
+            linkLabel: TRACKING_LABEL[subjectKey].linkLabel
+        };
+    }
     const ctx = {
         viewUrl,
         viewLinkLabel: VIEW_LINK_LABEL[subjectKey],
+        tracking,
         order: {
             number: order.number,
             status: order.status,

package/dist/shop/server/orders.d.ts

@@ -33,6 +33,15 @@ export declare function updateOrderStatus(orderId: string, status: OrderStatus,
     changedBy?: string;
 }): Promise<OrderRow>;
 export declare function setPaymentProviderRef(orderId: string, ref: string | null): Promise<void>;
+export interface ShipmentInfoInput {
+    shipmentId: string;
+    trackingNumber?: string | null;
+    labelUrl?: string | null;
+}
+export declare function setShipmentInfo(orderId: string, info: ShipmentInfoInput): Promise<OrderRow>;
+export declare function updateTrackingNumber(orderId: string, trackingNumber: string): Promise<void>;
+export declare function clearShipmentInfo(orderId: string): Promise<void>;
+export declare function getOrderByShipmentId(shipmentId: string): Promise<OrderRow | null>;
 export declare function getOrderById(id: string): Promise<OrderRow | null>;
 export declare function getOrderByNumber(number: string): Promise<OrderRow | null>;
 export declare function getOrderItems(orderId: string): Promise<OrderItemRow[]>;

package/dist/shop/server/orders.js

@@ -256,6 +256,54 @@ export async function setPaymentProviderRef(orderId, ref) {
         .set({ paymentProviderRef: ref, updatedAt: new Date() })
         .where(eq(shopOrdersTable.id, orderId));
 }
+export async function setShipmentInfo(orderId, info) {
+    const db = getShopDb();
+    await db
+        .update(shopOrdersTable)
+        .set({
+        shipmentId: info.shipmentId,
+        trackingNumber: info.trackingNumber ?? null,
+        labelUrl: info.labelUrl ?? null,
+        shipmentCreatedAt: new Date(),
+        updatedAt: new Date()
+    })
+        .where(eq(shopOrdersTable.id, orderId));
+    const [row] = await db
+        .select()
+        .from(shopOrdersTable)
+        .where(eq(shopOrdersTable.id, orderId));
+    if (!row)
+        throw new Error('Order not found after shipment update.');
+    return row;
+}
+export async function updateTrackingNumber(orderId, trackingNumber) {
+    const db = getShopDb();
+    await db
+        .update(shopOrdersTable)
+        .set({ trackingNumber, updatedAt: new Date() })
+        .where(eq(shopOrdersTable.id, orderId));
+}
+export async function clearShipmentInfo(orderId) {
+    const db = getShopDb();
+    await db
+        .update(shopOrdersTable)
+        .set({
+        shipmentId: null,
+        trackingNumber: null,
+        labelUrl: null,
+        shipmentCreatedAt: null,
+        updatedAt: new Date()
+    })
+        .where(eq(shopOrdersTable.id, orderId));
+}
+export async function getOrderByShipmentId(shipmentId) {
+    const db = getShopDb();
+    const [row] = await db
+        .select()
+        .from(shopOrdersTable)
+        .where(eq(shopOrdersTable.shipmentId, shipmentId));
+    return row ?? null;
+}
 export async function getOrderById(id) {
     const db = getShopDb();
     const [row] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, id));

package/dist/shop/server/shipments.d.ts

@@ -0,0 +1,33 @@
+import type { CarrierEvent, ShipmentLabel } from '../types.js';
+import { type OrderRow } from './orders.js';
+/**
+ * Create a shipment for the order with the carrier configured on the order.
+ * Saves shipmentId/trackingNumber on the order and bumps status to `preparing`.
+ * Idempotent guard: throws if a shipment already exists (use `cancelShipmentForOrder` first).
+ */
+export declare function createShipmentForOrder(orderId: string): Promise<OrderRow>;
+/**
+ * Cancel an existing shipment with the carrier and clear shipment data on the order.
+ * Order status is left untouched (admin decides whether to drop back to `paid`).
+ */
+export declare function cancelShipmentForOrder(orderId: string): Promise<OrderRow>;
+/**
+ * Fetch the shipping label PDF (or other format) from the carrier. Used by the
+ * admin label proxy endpoint.
+ */
+export declare function getShipmentLabelForOrder(orderId: string, opts?: {
+    size?: 'A4' | 'A6';
+}): Promise<ShipmentLabel>;
+export interface ApplyCarrierEventResult {
+    matched: boolean;
+    orderId?: string;
+    statusChanged?: boolean;
+    trackingChanged?: boolean;
+}
+/**
+ * Apply an incoming carrier event (e.g. from a webhook) to the matching order:
+ * update the tracking number when supplied and bump the order status when the
+ * mapped status differs from the current one. Unknown carrier statuses are
+ * skipped — caller still gets `matched=true` so the webhook can return 200.
+ */
+export declare function applyCarrierEvent(event: CarrierEvent): Promise<ApplyCarrierEventResult>;