Add a shipping adapter

The shipping dispatcher supports two modes:

• a local module such as shippo, shipengine or manual in features/integrations/shipping;
• an external HTTP app chosen by URLs stored in the operation fields of a ShippingProvider record.

Adapter operations

The fields are:

• getRatesFunction
• validateAddressFunction
• createLabelFunction
• trackShipmentFunction
• cancelLabelFunction

features/keystone/utils/shippingProviderAdapter.ts reads the field. If it starts with http, Openfront sends a JSON POST with the provider record and the arguments. Otherwise it imports features/integrations/shipping/<value>.ts and calls the export named after the field.

Arguments by operation:

• rates: order, dimensions;
• address validation: address;
• label: order, rateId, dimensions, lineItems, idempotencyKey;
• tracking: trackingNumber;
• cancellation: labelId.

Configure a provider

1. Deploy HTTPS endpoints for the operations you support, or add a local module.
2. Create a ShippingProvider with a name, isActive, an access token, a from-address, regions, and the five operation fields. Use the generic /dashboard/shipping-providers editor for URL fields.
3. Test each operation with test addresses and sandbox credentials.
4. Retry a label purchase with the same idempotency key and confirm one label.

The bridge sends the provider record, including its access token, plus order, address and parcel data to the configured URL. Only trusted operators should be able to change these fields. Use HTTPS endpoints you control and authenticate requests inside the adapter app.

Current source limits

• The order-level "new provider" form stores an API URL in metadata.apiUrl and sets no operation field.
• The "Custom Provider" option in the provider drawer sets every field to custom, but no custom.ts module exists.
• The bridge has no timeout, destination allowlist, request signature or response schema.
• The POST body does not include the operation name.

Required checks

• Unauthorized users cannot read the access token or change the fields.
• Address, order and line-item relationships are checked before carrier calls.
• Label purchase is idempotent.
• Malformed, slow or partial replies fail without writing records.
• Tokens and addresses do not appear in logs or browser errors.

See Shipping providers.