@amboras-dev/hive

Hive 3PL fulfillment integration for Amboras — shared wire types and a storefront shipment-tracking hook.

What lives where

Hive's API key is a bearer token that must stay server-side, and Hive rate-limits at 100 requests/minute per merchant. So nothing in this package talks to app.hive.app. All Hive HTTP, HMAC webhook verification, and order routing live in medusa-backend-orchestrator under /store/hive/*; this package ships the typed surface around those routes.

| Entrypoint | Contents | | --- | --- | | @amboras-dev/hive | every wire type; no React | | @amboras-dev/hive/client | useHiveTracking + shipment types |

The admin settings UI lives in the orchestrator admin app, not here — the same split meta-ads uses.

Hive Merchant API v1

Base URLs — production https://app.hive.app/merchant_api/v1, staging https://staging.app.hive.app/merchant_api/v1. Auth is Authorization: Bearer <api_key>; the key is issued by the merchant's Hive account manager, not self-serve.

| Resource | Endpoints | | --- | --- | | Orders | GET/POST /orders, GET/PATCH /orders/{id}, PUT /orders/{id}/cancel | | Shipments | GET /shipments?order_id= | | Warehouses | GET /warehouses (list only) |

List responses are { data, pagination } with page / limit (default 20, max 100). Errors are { success: false, errors: string[] } — no machine-readable codes, so branch on the HTTP status.

Webhooks

Four events: delivery_status_updated, shipment_status_updated, restocking_shipment_status_updated, return_status_updated. The destination URL is registered by the merchant's account manager — the settings form displays it read-only for them to hand over.

Two things the backend handler must get right:

• Signature. x-hive-signature is a hex HMAC-SHA256 of the raw body keyed by the API token. Verify with a constant-time compare and ignore any request without the header.
• Ordering. Hive guarantees neither ordering nor exactly-once delivery. Compare the payload's updated_at against the last stored value and drop anything older.

Usage

// Storefront
import { useHiveTracking } from '@amboras-dev/hive/client'

const { shipments, isPending, error } = useHiveTracking(order.id)

useHiveTracking accepts baseUrl / publishableKey overrides, falling back to NEXT_PUBLIC_MEDUSA_BACKEND_URL and NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY.

Types

src/types.ts mirrors Hive's snake_case field names exactly so a backend route can pass a Hive payload straight through. It must stay byte-compatible with the DTOs in medusa-backend-orchestrator.