@amboras-dev/hive 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @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
+
+```tsx
+// 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`.

package/dist/chunk-BADYBNR7.mjs

@@ -0,0 +1,61 @@
+// src/types.ts
+var SECRET_SET_SENTINEL = "__SECRET_SET__";
+var HIVE_BASE_URLS = {
+  production: "https://app.hive.app/merchant_api/v1",
+  staging: "https://staging.app.hive.app/merchant_api/v1"
+};
+var HIVE_RATE_LIMIT_PER_MINUTE = 100;
+var HiveOrderStatus = /* @__PURE__ */ ((HiveOrderStatus2) => {
+  HiveOrderStatus2["Fulfillable"] = "fulfillable";
+  HiveOrderStatus2["Unfulfillable"] = "unfulfillable";
+  HiveOrderStatus2["Fulfilled"] = "fulfilled";
+  return HiveOrderStatus2;
+})(HiveOrderStatus || {});
+var HiveFinancialStatus = /* @__PURE__ */ ((HiveFinancialStatus2) => {
+  HiveFinancialStatus2["Paid"] = "paid";
+  HiveFinancialStatus2["Refunded"] = "refunded";
+  HiveFinancialStatus2["Pending"] = "pending";
+  HiveFinancialStatus2["Failed"] = "failed";
+  return HiveFinancialStatus2;
+})(HiveFinancialStatus || {});
+var HiveShipmentStatus = /* @__PURE__ */ ((HiveShipmentStatus2) => {
+  HiveShipmentStatus2["WaitingForPicking"] = "waiting_for_picking";
+  HiveShipmentStatus2["OnHold"] = "on_hold";
+  HiveShipmentStatus2["PickingAssigned"] = "picking_assigned";
+  HiveShipmentStatus2["InPicking"] = "in_picking";
+  HiveShipmentStatus2["Picked"] = "picked";
+  HiveShipmentStatus2["InPacking"] = "in_packing";
+  HiveShipmentStatus2["Packed"] = "packed";
+  HiveShipmentStatus2["InShipping"] = "in_shipping";
+  HiveShipmentStatus2["Shipped"] = "shipped";
+  HiveShipmentStatus2["Cancelled"] = "cancelled";
+  return HiveShipmentStatus2;
+})(HiveShipmentStatus || {});
+var HiveWebhookEvent = /* @__PURE__ */ ((HiveWebhookEvent2) => {
+  HiveWebhookEvent2["DeliveryStatusUpdated"] = "delivery_status_updated";
+  HiveWebhookEvent2["ShipmentStatusUpdated"] = "shipment_status_updated";
+  HiveWebhookEvent2["RestockingShipmentStatusUpdated"] = "restocking_shipment_status_updated";
+  HiveWebhookEvent2["ReturnStatusUpdated"] = "return_status_updated";
+  return HiveWebhookEvent2;
+})(HiveWebhookEvent || {});
+var HIVE_SIGNATURE_HEADER = "x-hive-signature";
+var HiveConnectionError = /* @__PURE__ */ ((HiveConnectionError2) => {
+  HiveConnectionError2["MissingApiKey"] = "missing_api_key";
+  HiveConnectionError2["Unauthorized"] = "unauthorized";
+  HiveConnectionError2["RateLimited"] = "rate_limited";
+  HiveConnectionError2["Unreachable"] = "unreachable";
+  return HiveConnectionError2;
+})(HiveConnectionError || {});
+
+export {
+  SECRET_SET_SENTINEL,
+  HIVE_BASE_URLS,
+  HIVE_RATE_LIMIT_PER_MINUTE,
+  HiveOrderStatus,
+  HiveFinancialStatus,
+  HiveShipmentStatus,
+  HiveWebhookEvent,
+  HIVE_SIGNATURE_HEADER,
+  HiveConnectionError
+};
+//# sourceMappingURL=chunk-BADYBNR7.mjs.map

package/dist/chunk-BADYBNR7.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Public types for @amboras-dev/hive.\n *\n * Single source of truth for the wire shape between the Amboras admin /\n * storefront and the medusa-backend-orchestrator Store API routes under\n * `/store/hive/*`. The DTO files on the Medusa side must stay\n * byte-compatible with these.\n *\n * Field names mirror the Hive Merchant API v1\n * (https://developers.hive.app/reference/api-reference) exactly, including\n * its snake_case, so a backend route can pass a Hive payload straight\n * through without a rename layer.\n *\n * The Hive API key is a server-side secret and Hive enforces a\n * 100 req/min per-merchant rate limit, so nothing in this package ever\n * calls app.hive.app directly - every hook here talks to our own Medusa\n * routes, which own the Hive HTTP client.\n */\n\n/**\n * Sentinel returned in place of a stored secret when the settings form\n * reads back current config. Matches the pattern used by meta-ads,\n * pinterest and aliexpress-dropshipping so the admin never sees the\n * plaintext API key after write.\n */\nexport const SECRET_SET_SENTINEL = '__SECRET_SET__' as const\nexport type SecretSetSentinel = typeof SECRET_SET_SENTINEL\n\n/** Hive base URLs, keyed by the environment chosen in the settings form. */\nexport const HIVE_BASE_URLS = {\n  production: 'https://app.hive.app/merchant_api/v1',\n  staging: 'https://staging.app.hive.app/merchant_api/v1',\n} as const\n\nexport type HiveEnvironment = keyof typeof HIVE_BASE_URLS\n\n/** Hive allows 100 requests per minute per merchant. */\nexport const HIVE_RATE_LIMIT_PER_MINUTE = 100\n\n/* -------------------------------------------------------------------------\n * Envelope\n * ---------------------------------------------------------------------- */\n\n/**\n * Pagination block attached to every Hive list response.\n * Requests page through with `page` (default 1) and `limit`\n * (default 20, max 100).\n */\nexport interface HivePagination {\n  current_page: number\n  item_count: number\n  page_count: number\n  items_per_page: number\n}\n\n/** Shape of every Hive list endpoint: `{ data, pagination }`. */\nexport interface HiveListResponse<T> {\n  data: T[]\n  pagination: HivePagination\n}\n\n/**\n * Hive error body. Every failure carries `success: false` and an array of\n * human-readable messages; there are no machine-readable error codes, so\n * the HTTP status is the only thing worth branching on.\n */\nexport interface HiveErrorResponse {\n  success: false\n  errors: string[]\n}\n\n/* -------------------------------------------------------------------------\n * Warehouses\n * ---------------------------------------------------------------------- */\n\n/** `GET /warehouses` is list-only and every field is read-only. */\nexport interface HiveWarehouseDto {\n  id: number\n  name: string\n  /** 2-letter ISO 3166-1 country code. */\n  country: string\n  city: string\n}\n\n/* -------------------------------------------------------------------------\n * Orders\n * ---------------------------------------------------------------------- */\n\n/** Whether Hive can pick the order with the stock it currently holds. */\nexport enum HiveOrderStatus {\n  Fulfillable = 'fulfillable',\n  Unfulfillable = 'unfulfillable',\n  Fulfilled = 'fulfilled',\n}\n\nexport enum HiveFinancialStatus {\n  Paid = 'paid',\n  Refunded = 'refunded',\n  Pending = 'pending',\n  Failed = 'failed',\n}\n\nexport interface HiveAddressDto {\n  first_name: string | null\n  last_name: string | null\n  company: string | null\n  address_1: string\n  address_2: string | null\n  city: string\n  province: string | null\n  zip: string\n  /** 2-letter ISO 3166-1 country code. */\n  country_code: string\n  phone: string | null\n  email: string | null\n}\n\nexport interface HiveOrderItemDto {\n  id: number\n  merchant_item_id: string | null\n  merchant_sku_id: string\n  quantity: number\n}\n\n/** Body item for `POST /orders` - references a SKU the merchant already created. */\nexport interface HiveOrderItemInput {\n  merchant_sku_id: string\n  quantity: number\n  merchant_item_id?: string\n}\n\nexport interface HiveOrderDto {\n  id: number\n  merchant_order_id: string\n  status: HiveOrderStatus\n  financial_status: HiveFinancialStatus | null\n  shipping_address: HiveAddressDto\n  billing_address: HiveAddressDto | null\n  items: HiveOrderItemDto[]\n  created_at: string\n  updated_at: string\n}\n\n/** Body for `POST /orders`. */\nexport interface HiveOrderInput {\n  merchant_order_id: string\n  shipping_address: HiveAddressDto\n  items: HiveOrderItemInput[]\n  billing_address?: HiveAddressDto\n  financial_status?: HiveFinancialStatus\n}\n\n/* -------------------------------------------------------------------------\n * Shipments\n * ---------------------------------------------------------------------- */\n\n/** Warehouse-side progress of a shipment. */\nexport enum HiveShipmentStatus {\n  WaitingForPicking = 'waiting_for_picking',\n  OnHold = 'on_hold',\n  PickingAssigned = 'picking_assigned',\n  InPicking = 'in_picking',\n  Picked = 'picked',\n  InPacking = 'in_packing',\n  Packed = 'packed',\n  InShipping = 'in_shipping',\n  Shipped = 'shipped',\n  Cancelled = 'cancelled',\n}\n\n/**\n * Carrier-side progress. Hive sends these as human-readable strings\n * rather than slugs, so they are typed as a literal union of the exact\n * values the API returns.\n */\nexport type HiveDeliveryStatus =\n  | 'Information transmitted to the carrier'\n  | 'In transit'\n  | 'Out for delivery'\n  | 'Delivered'\n  | 'Returned to sender'\n  | 'Action required'\n\nexport interface HiveShipmentItemSkuDto {\n  id: number\n  merchant_sku_id: string\n}\n\nexport interface HiveShipmentItemDto {\n  id: number\n  merchant_item_id: string | null\n  quantity: number\n  sku: HiveShipmentItemSkuDto\n}\n\nexport interface HiveShipmentDto {\n  id: number\n  order_id: number\n  merchant_order_id: string\n  status: HiveShipmentStatus\n  delivery_status: HiveDeliveryStatus | null\n  shipment_provider: string | null\n  tracking_number: string | null\n  tracking_url: string | null\n  items: HiveShipmentItemDto[]\n  shipped_at: string | null\n  delivered_at: string | null\n  created_at: string\n  updated_at: string\n}\n\n/* -------------------------------------------------------------------------\n * Webhooks\n * ---------------------------------------------------------------------- */\n\n/**\n * The four events Hive can push. Registration is not self-serve - the\n * merchant's Hive account manager configures the destination URL.\n */\nexport enum HiveWebhookEvent {\n  DeliveryStatusUpdated = 'delivery_status_updated',\n  ShipmentStatusUpdated = 'shipment_status_updated',\n  RestockingShipmentStatusUpdated = 'restocking_shipment_status_updated',\n  ReturnStatusUpdated = 'return_status_updated',\n}\n\n/**\n * HTTP header carrying the hex-encoded HMAC-SHA256 digest of the raw\n * request body, keyed by the merchant's API token. Requests without it\n * must be ignored, and the comparison must be constant-time.\n */\nexport const HIVE_SIGNATURE_HEADER = 'x-hive-signature'\n\n/**\n * Hive does not guarantee ordering or exactly-once delivery, so a\n * consumer must compare the payload's `updated_at` against the last\n * value it stored and drop anything older.\n */\nexport interface HiveWebhookPayload<T = unknown> {\n  event: HiveWebhookEvent\n  data: T\n}\n\nexport type HiveShipmentWebhookPayload = HiveWebhookPayload<HiveShipmentDto>\n\n/* -------------------------------------------------------------------------\n * Plugin config + admin surface\n * ---------------------------------------------------------------------- */\n\n/**\n * Per-store Hive plugin configuration.\n *\n * - `apiKey` is issued by the merchant's Hive account manager. The admin\n *   form receives `SECRET_SET_SENTINEL` on read and only sends a real\n *   value when the merchant types a new one.\n * - `environment` selects between the production and staging domains.\n * - `defaultWarehouseId` is the warehouse orders route to when the\n *   multi-3PL rules do not name one.\n * - `lastSuccessfulCallAt` is an ISO-8601 timestamp for the status card.\n */\nexport interface HivePluginConfig {\n  enabled: boolean\n  apiKey: string | SecretSetSentinel | null\n  environment: HiveEnvironment\n  defaultWarehouseId: number | null\n  lastSuccessfulCallAt: string | null\n}\n\n/** Why the backend considers the stored credential unusable. */\nexport enum HiveConnectionError {\n  MissingApiKey = 'missing_api_key',\n  Unauthorized = 'unauthorized',\n  RateLimited = 'rate_limited',\n  Unreachable = 'unreachable',\n}\n\n/** `GET /store/hive/status`. */\nexport interface HiveConnectionStatusDto {\n  connected: boolean\n  environment: HiveEnvironment\n  /** Populated from `GET /warehouses` on the last successful call. */\n  warehouses: HiveWarehouseDto[]\n  lastSuccessfulCallAt: string | null\n  error: HiveConnectionError | null\n  /**\n   * Where the merchant's Hive account manager should point webhooks.\n   * Rendered read-only in the settings form.\n   */\n  webhookUrl: string | null\n}\n\n/** `POST /store/hive/test-connection`. */\nexport type HiveTestConnectionResult =\n  | { ok: true; warehouses: HiveWarehouseDto[] }\n  | { ok: false; code: HiveConnectionError | 'UNKNOWN'; msg: string }\n"],"mappings":";AAyBO,IAAM,sBAAsB;AAI5B,IAAM,iBAAiB;AAAA,EAC5B,YAAY;AAAA,EACZ,SAAS;AACX;AAKO,IAAM,6BAA6B;AAoDnC,IAAK,kBAAL,kBAAKA,qBAAL;AACL,EAAAA,iBAAA,iBAAc;AACd,EAAAA,iBAAA,mBAAgB;AAChB,EAAAA,iBAAA,eAAY;AAHF,SAAAA;AAAA,GAAA;AAML,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,UAAO;AACP,EAAAA,qBAAA,cAAW;AACX,EAAAA,qBAAA,aAAU;AACV,EAAAA,qBAAA,YAAS;AAJC,SAAAA;AAAA,GAAA;AA8DL,IAAK,qBAAL,kBAAKC,wBAAL;AACL,EAAAA,oBAAA,uBAAoB;AACpB,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,qBAAkB;AAClB,EAAAA,oBAAA,eAAY;AACZ,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,eAAY;AACZ,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,gBAAa;AACb,EAAAA,oBAAA,aAAU;AACV,EAAAA,oBAAA,eAAY;AAVF,SAAAA;AAAA,GAAA;AA8DL,IAAK,mBAAL,kBAAKC,sBAAL;AACL,EAAAA,kBAAA,2BAAwB;AACxB,EAAAA,kBAAA,2BAAwB;AACxB,EAAAA,kBAAA,qCAAkC;AAClC,EAAAA,kBAAA,yBAAsB;AAJZ,SAAAA;AAAA,GAAA;AAYL,IAAM,wBAAwB;AAsC9B,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,mBAAgB;AAChB,EAAAA,qBAAA,kBAAe;AACf,EAAAA,qBAAA,iBAAc;AACd,EAAAA,qBAAA,iBAAc;AAJJ,SAAAA;AAAA,GAAA;","names":["HiveOrderStatus","HiveFinancialStatus","HiveShipmentStatus","HiveWebhookEvent","HiveConnectionError"]}

package/dist/client/index.d.mts

@@ -0,0 +1,28 @@
+import { HiveShipmentDto } from '../index.mjs';
+export { HiveDeliveryStatus, HiveShipmentItemDto, HiveShipmentStatus } from '../index.mjs';
+
+interface UseHiveTrackingOptions {
+    baseUrl?: string;
+    publishableKey?: string;
+    /** Skip the initial fetch - useful while the order id is still loading. */
+    enabled?: boolean;
+}
+interface UseHiveTrackingResult {
+    shipments: HiveShipmentDto[];
+    isPending: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Reads the Hive shipments for one Medusa order.
+ *
+ * Hits our own `/store/hive/shipments` route rather than Hive directly:
+ * the API key is server-side only and Hive rate-limits at 100 req/min per
+ * merchant, so the backend owns the call and the caching.
+ *
+ * `orderId` is the Medusa order id; the backend maps it to Hive's
+ * `merchant_order_id`.
+ */
+declare function useHiveTracking(orderId: string, options?: UseHiveTrackingOptions): UseHiveTrackingResult;
+
+export { HiveShipmentDto, type UseHiveTrackingOptions, type UseHiveTrackingResult, useHiveTracking };

package/dist/client/index.d.ts

@@ -0,0 +1,28 @@
+import { HiveShipmentDto } from '../index.js';
+export { HiveDeliveryStatus, HiveShipmentItemDto, HiveShipmentStatus } from '../index.js';
+
+interface UseHiveTrackingOptions {
+    baseUrl?: string;
+    publishableKey?: string;
+    /** Skip the initial fetch - useful while the order id is still loading. */
+    enabled?: boolean;
+}
+interface UseHiveTrackingResult {
+    shipments: HiveShipmentDto[];
+    isPending: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Reads the Hive shipments for one Medusa order.
+ *
+ * Hits our own `/store/hive/shipments` route rather than Hive directly:
+ * the API key is server-side only and Hive rate-limits at 100 req/min per
+ * merchant, so the backend owns the call and the caching.
+ *
+ * `orderId` is the Medusa order id; the backend maps it to Hive's
+ * `merchant_order_id`.
+ */
+declare function useHiveTracking(orderId: string, options?: UseHiveTrackingOptions): UseHiveTrackingResult;
+
+export { HiveShipmentDto, type UseHiveTrackingOptions, type UseHiveTrackingResult, useHiveTracking };

package/dist/client/index.js

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  HiveShipmentStatus: () => HiveShipmentStatus,
+  useHiveTracking: () => useHiveTracking
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/client/use-hive-tracking.ts
+var import_react = require("react");
+function useHiveTracking(orderId, options = {}) {
+  const { baseUrl, publishableKey, enabled = true } = options;
+  const [shipments, setShipments] = (0, import_react.useState)([]);
+  const [isPending, setIsPending] = (0, import_react.useState)(false);
+  const [error, setError] = (0, import_react.useState)(null);
+  const refetch = (0, import_react.useCallback)(async () => {
+    if (!orderId) return;
+    setIsPending(true);
+    setError(null);
+    try {
+      const resolvedBaseUrl = baseUrl ?? process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL ?? "";
+      const resolvedKey = publishableKey ?? process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY ?? "";
+      const url = `${resolvedBaseUrl.replace(/\/$/, "")}/store/hive/shipments?order_id=${encodeURIComponent(orderId)}`;
+      const response = await fetch(url, {
+        headers: {
+          "Content-Type": "application/json",
+          ...resolvedKey ? { "x-publishable-api-key": resolvedKey } : {}
+        }
+      });
+      if (!response.ok) {
+        throw new Error(`Hive shipment lookup failed: ${response.status}`);
+      }
+      const body = await response.json();
+      setShipments(body.shipments ?? []);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Hive shipment lookup failed"));
+    } finally {
+      setIsPending(false);
+    }
+  }, [orderId, baseUrl, publishableKey]);
+  (0, import_react.useEffect)(() => {
+    if (!enabled) return;
+    void refetch();
+  }, [enabled, refetch]);
+  return { shipments, isPending, error, refetch };
+}
+
+// src/types.ts
+var HiveShipmentStatus = /* @__PURE__ */ ((HiveShipmentStatus2) => {
+  HiveShipmentStatus2["WaitingForPicking"] = "waiting_for_picking";
+  HiveShipmentStatus2["OnHold"] = "on_hold";
+  HiveShipmentStatus2["PickingAssigned"] = "picking_assigned";
+  HiveShipmentStatus2["InPicking"] = "in_picking";
+  HiveShipmentStatus2["Picked"] = "picked";
+  HiveShipmentStatus2["InPacking"] = "in_packing";
+  HiveShipmentStatus2["Packed"] = "packed";
+  HiveShipmentStatus2["InShipping"] = "in_shipping";
+  HiveShipmentStatus2["Shipped"] = "shipped";
+  HiveShipmentStatus2["Cancelled"] = "cancelled";
+  return HiveShipmentStatus2;
+})(HiveShipmentStatus || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HiveShipmentStatus,
+  useHiveTracking
+});
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts","../../src/client/use-hive-tracking.ts","../../src/types.ts"],"sourcesContent":["export {\n  useHiveTracking,\n  type UseHiveTrackingOptions,\n  type UseHiveTrackingResult,\n} from './use-hive-tracking'\nexport type {\n  HiveShipmentDto,\n  HiveShipmentItemDto,\n  HiveDeliveryStatus,\n} from '../types'\nexport { HiveShipmentStatus } from '../types'\n","'use client'\n\nimport { useCallback, useEffect, useState } from 'react'\nimport type { HiveShipmentDto } from '../types'\n\nexport interface UseHiveTrackingOptions {\n  baseUrl?: string\n  publishableKey?: string\n  /** Skip the initial fetch - useful while the order id is still loading. */\n  enabled?: boolean\n}\n\nexport interface UseHiveTrackingResult {\n  shipments: HiveShipmentDto[]\n  isPending: boolean\n  error: Error | null\n  refetch: () => Promise<void>\n}\n\n/**\n * Reads the Hive shipments for one Medusa order.\n *\n * Hits our own `/store/hive/shipments` route rather than Hive directly:\n * the API key is server-side only and Hive rate-limits at 100 req/min per\n * merchant, so the backend owns the call and the caching.\n *\n * `orderId` is the Medusa order id; the backend maps it to Hive's\n * `merchant_order_id`.\n */\nexport function useHiveTracking(\n  orderId: string,\n  options: UseHiveTrackingOptions = {},\n): UseHiveTrackingResult {\n  const { baseUrl, publishableKey, enabled = true } = options\n\n  const [shipments, setShipments] = useState<HiveShipmentDto[]>([])\n  const [isPending, setIsPending] = useState<boolean>(false)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refetch = useCallback(async (): Promise<void> => {\n    if (!orderId) return\n    setIsPending(true)\n    setError(null)\n    try {\n      const resolvedBaseUrl =\n        baseUrl ?? process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL ?? ''\n      const resolvedKey =\n        publishableKey ?? process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY ?? ''\n      const url = `${resolvedBaseUrl.replace(/\\/$/, '')}/store/hive/shipments?order_id=${encodeURIComponent(orderId)}`\n      const response = await fetch(url, {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(resolvedKey ? { 'x-publishable-api-key': resolvedKey } : {}),\n        },\n      })\n      if (!response.ok) {\n        throw new Error(`Hive shipment lookup failed: ${response.status}`)\n      }\n      const body = (await response.json()) as { shipments?: HiveShipmentDto[] }\n      setShipments(body.shipments ?? [])\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Hive shipment lookup failed'))\n    } finally {\n      setIsPending(false)\n    }\n  }, [orderId, baseUrl, publishableKey])\n\n  useEffect(() => {\n    if (!enabled) return\n    void refetch()\n  }, [enabled, refetch])\n\n  return { shipments, isPending, error, refetch }\n}\n","/**\n * Public types for @amboras-dev/hive.\n *\n * Single source of truth for the wire shape between the Amboras admin /\n * storefront and the medusa-backend-orchestrator Store API routes under\n * `/store/hive/*`. The DTO files on the Medusa side must stay\n * byte-compatible with these.\n *\n * Field names mirror the Hive Merchant API v1\n * (https://developers.hive.app/reference/api-reference) exactly, including\n * its snake_case, so a backend route can pass a Hive payload straight\n * through without a rename layer.\n *\n * The Hive API key is a server-side secret and Hive enforces a\n * 100 req/min per-merchant rate limit, so nothing in this package ever\n * calls app.hive.app directly - every hook here talks to our own Medusa\n * routes, which own the Hive HTTP client.\n */\n\n/**\n * Sentinel returned in place of a stored secret when the settings form\n * reads back current config. Matches the pattern used by meta-ads,\n * pinterest and aliexpress-dropshipping so the admin never sees the\n * plaintext API key after write.\n */\nexport const SECRET_SET_SENTINEL = '__SECRET_SET__' as const\nexport type SecretSetSentinel = typeof SECRET_SET_SENTINEL\n\n/** Hive base URLs, keyed by the environment chosen in the settings form. */\nexport const HIVE_BASE_URLS = {\n  production: 'https://app.hive.app/merchant_api/v1',\n  staging: 'https://staging.app.hive.app/merchant_api/v1',\n} as const\n\nexport type HiveEnvironment = keyof typeof HIVE_BASE_URLS\n\n/** Hive allows 100 requests per minute per merchant. */\nexport const HIVE_RATE_LIMIT_PER_MINUTE = 100\n\n/* -------------------------------------------------------------------------\n * Envelope\n * ---------------------------------------------------------------------- */\n\n/**\n * Pagination block attached to every Hive list response.\n * Requests page through with `page` (default 1) and `limit`\n * (default 20, max 100).\n */\nexport interface HivePagination {\n  current_page: number\n  item_count: number\n  page_count: number\n  items_per_page: number\n}\n\n/** Shape of every Hive list endpoint: `{ data, pagination }`. */\nexport interface HiveListResponse<T> {\n  data: T[]\n  pagination: HivePagination\n}\n\n/**\n * Hive error body. Every failure carries `success: false` and an array of\n * human-readable messages; there are no machine-readable error codes, so\n * the HTTP status is the only thing worth branching on.\n */\nexport interface HiveErrorResponse {\n  success: false\n  errors: string[]\n}\n\n/* -------------------------------------------------------------------------\n * Warehouses\n * ---------------------------------------------------------------------- */\n\n/** `GET /warehouses` is list-only and every field is read-only. */\nexport interface HiveWarehouseDto {\n  id: number\n  name: string\n  /** 2-letter ISO 3166-1 country code. */\n  country: string\n  city: string\n}\n\n/* -------------------------------------------------------------------------\n * Orders\n * ---------------------------------------------------------------------- */\n\n/** Whether Hive can pick the order with the stock it currently holds. */\nexport enum HiveOrderStatus {\n  Fulfillable = 'fulfillable',\n  Unfulfillable = 'unfulfillable',\n  Fulfilled = 'fulfilled',\n}\n\nexport enum HiveFinancialStatus {\n  Paid = 'paid',\n  Refunded = 'refunded',\n  Pending = 'pending',\n  Failed = 'failed',\n}\n\nexport interface HiveAddressDto {\n  first_name: string | null\n  last_name: string | null\n  company: string | null\n  address_1: string\n  address_2: string | null\n  city: string\n  province: string | null\n  zip: string\n  /** 2-letter ISO 3166-1 country code. */\n  country_code: string\n  phone: string | null\n  email: string | null\n}\n\nexport interface HiveOrderItemDto {\n  id: number\n  merchant_item_id: string | null\n  merchant_sku_id: string\n  quantity: number\n}\n\n/** Body item for `POST /orders` - references a SKU the merchant already created. */\nexport interface HiveOrderItemInput {\n  merchant_sku_id: string\n  quantity: number\n  merchant_item_id?: string\n}\n\nexport interface HiveOrderDto {\n  id: number\n  merchant_order_id: string\n  status: HiveOrderStatus\n  financial_status: HiveFinancialStatus | null\n  shipping_address: HiveAddressDto\n  billing_address: HiveAddressDto | null\n  items: HiveOrderItemDto[]\n  created_at: string\n  updated_at: string\n}\n\n/** Body for `POST /orders`. */\nexport interface HiveOrderInput {\n  merchant_order_id: string\n  shipping_address: HiveAddressDto\n  items: HiveOrderItemInput[]\n  billing_address?: HiveAddressDto\n  financial_status?: HiveFinancialStatus\n}\n\n/* -------------------------------------------------------------------------\n * Shipments\n * ---------------------------------------------------------------------- */\n\n/** Warehouse-side progress of a shipment. */\nexport enum HiveShipmentStatus {\n  WaitingForPicking = 'waiting_for_picking',\n  OnHold = 'on_hold',\n  PickingAssigned = 'picking_assigned',\n  InPicking = 'in_picking',\n  Picked = 'picked',\n  InPacking = 'in_packing',\n  Packed = 'packed',\n  InShipping = 'in_shipping',\n  Shipped = 'shipped',\n  Cancelled = 'cancelled',\n}\n\n/**\n * Carrier-side progress. Hive sends these as human-readable strings\n * rather than slugs, so they are typed as a literal union of the exact\n * values the API returns.\n */\nexport type HiveDeliveryStatus =\n  | 'Information transmitted to the carrier'\n  | 'In transit'\n  | 'Out for delivery'\n  | 'Delivered'\n  | 'Returned to sender'\n  | 'Action required'\n\nexport interface HiveShipmentItemSkuDto {\n  id: number\n  merchant_sku_id: string\n}\n\nexport interface HiveShipmentItemDto {\n  id: number\n  merchant_item_id: string | null\n  quantity: number\n  sku: HiveShipmentItemSkuDto\n}\n\nexport interface HiveShipmentDto {\n  id: number\n  order_id: number\n  merchant_order_id: string\n  status: HiveShipmentStatus\n  delivery_status: HiveDeliveryStatus | null\n  shipment_provider: string | null\n  tracking_number: string | null\n  tracking_url: string | null\n  items: HiveShipmentItemDto[]\n  shipped_at: string | null\n  delivered_at: string | null\n  created_at: string\n  updated_at: string\n}\n\n/* -------------------------------------------------------------------------\n * Webhooks\n * ---------------------------------------------------------------------- */\n\n/**\n * The four events Hive can push. Registration is not self-serve - the\n * merchant's Hive account manager configures the destination URL.\n */\nexport enum HiveWebhookEvent {\n  DeliveryStatusUpdated = 'delivery_status_updated',\n  ShipmentStatusUpdated = 'shipment_status_updated',\n  RestockingShipmentStatusUpdated = 'restocking_shipment_status_updated',\n  ReturnStatusUpdated = 'return_status_updated',\n}\n\n/**\n * HTTP header carrying the hex-encoded HMAC-SHA256 digest of the raw\n * request body, keyed by the merchant's API token. Requests without it\n * must be ignored, and the comparison must be constant-time.\n */\nexport const HIVE_SIGNATURE_HEADER = 'x-hive-signature'\n\n/**\n * Hive does not guarantee ordering or exactly-once delivery, so a\n * consumer must compare the payload's `updated_at` against the last\n * value it stored and drop anything older.\n */\nexport interface HiveWebhookPayload<T = unknown> {\n  event: HiveWebhookEvent\n  data: T\n}\n\nexport type HiveShipmentWebhookPayload = HiveWebhookPayload<HiveShipmentDto>\n\n/* -------------------------------------------------------------------------\n * Plugin config + admin surface\n * ---------------------------------------------------------------------- */\n\n/**\n * Per-store Hive plugin configuration.\n *\n * - `apiKey` is issued by the merchant's Hive account manager. The admin\n *   form receives `SECRET_SET_SENTINEL` on read and only sends a real\n *   value when the merchant types a new one.\n * - `environment` selects between the production and staging domains.\n * - `defaultWarehouseId` is the warehouse orders route to when the\n *   multi-3PL rules do not name one.\n * - `lastSuccessfulCallAt` is an ISO-8601 timestamp for the status card.\n */\nexport interface HivePluginConfig {\n  enabled: boolean\n  apiKey: string | SecretSetSentinel | null\n  environment: HiveEnvironment\n  defaultWarehouseId: number | null\n  lastSuccessfulCallAt: string | null\n}\n\n/** Why the backend considers the stored credential unusable. */\nexport enum HiveConnectionError {\n  MissingApiKey = 'missing_api_key',\n  Unauthorized = 'unauthorized',\n  RateLimited = 'rate_limited',\n  Unreachable = 'unreachable',\n}\n\n/** `GET /store/hive/status`. */\nexport interface HiveConnectionStatusDto {\n  connected: boolean\n  environment: HiveEnvironment\n  /** Populated from `GET /warehouses` on the last successful call. */\n  warehouses: HiveWarehouseDto[]\n  lastSuccessfulCallAt: string | null\n  error: HiveConnectionError | null\n  /**\n   * Where the merchant's Hive account manager should point webhooks.\n   * Rendered read-only in the settings form.\n   */\n  webhookUrl: string | null\n}\n\n/** `POST /store/hive/test-connection`. */\nexport type HiveTestConnectionResult =\n  | { ok: true; warehouses: HiveWarehouseDto[] }\n  | { ok: false; code: HiveConnectionError | 'UNKNOWN'; msg: string }\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,mBAAiD;AA2B1C,SAAS,gBACd,SACA,UAAkC,CAAC,GACZ;AACvB,QAAM,EAAE,SAAS,gBAAgB,UAAU,KAAK,IAAI;AAEpD,QAAM,CAAC,WAAW,YAAY,QAAI,uBAA4B,CAAC,CAAC;AAChE,QAAM,CAAC,WAAW,YAAY,QAAI,uBAAkB,KAAK;AACzD,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAAuB,IAAI;AAErD,QAAM,cAAU,0BAAY,YAA2B;AACrD,QAAI,CAAC,QAAS;AACd,iBAAa,IAAI;AACjB,aAAS,IAAI;AACb,QAAI;AACF,YAAM,kBACJ,WAAW,QAAQ,IAAI,kCAAkC;AAC3D,YAAM,cACJ,kBAAkB,QAAQ,IAAI,sCAAsC;AACtE,YAAM,MAAM,GAAG,gBAAgB,QAAQ,OAAO,EAAE,CAAC,kCAAkC,mBAAmB,OAAO,CAAC;AAC9G,YAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,GAAI,cAAc,EAAE,yBAAyB,YAAY,IAAI,CAAC;AAAA,QAChE;AAAA,MACF,CAAC;AACD,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,IAAI,MAAM,gCAAgC,SAAS,MAAM,EAAE;AAAA,MACnE;AACA,YAAM,OAAQ,MAAM,SAAS,KAAK;AAClC,mBAAa,KAAK,aAAa,CAAC,CAAC;AAAA,IACnC,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,6BAA6B,CAAC;AAAA,IAChF,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,SAAS,SAAS,cAAc,CAAC;AAErC,8BAAU,MAAM;AACd,QAAI,CAAC,QAAS;AACd,SAAK,QAAQ;AAAA,EACf,GAAG,CAAC,SAAS,OAAO,CAAC;AAErB,SAAO,EAAE,WAAW,WAAW,OAAO,QAAQ;AAChD;;;ACoFO,IAAK,qBAAL,kBAAKA,wBAAL;AACL,EAAAA,oBAAA,uBAAoB;AACpB,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,qBAAkB;AAClB,EAAAA,oBAAA,eAAY;AACZ,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,eAAY;AACZ,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,gBAAa;AACb,EAAAA,oBAAA,aAAU;AACV,EAAAA,oBAAA,eAAY;AAVF,SAAAA;AAAA,GAAA;","names":["HiveShipmentStatus"]}

package/dist/client/index.mjs

@@ -0,0 +1,47 @@
+import {
+  HiveShipmentStatus
+} from "../chunk-BADYBNR7.mjs";
+
+// src/client/use-hive-tracking.ts
+import { useCallback, useEffect, useState } from "react";
+function useHiveTracking(orderId, options = {}) {
+  const { baseUrl, publishableKey, enabled = true } = options;
+  const [shipments, setShipments] = useState([]);
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState(null);
+  const refetch = useCallback(async () => {
+    if (!orderId) return;
+    setIsPending(true);
+    setError(null);
+    try {
+      const resolvedBaseUrl = baseUrl ?? process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL ?? "";
+      const resolvedKey = publishableKey ?? process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY ?? "";
+      const url = `${resolvedBaseUrl.replace(/\/$/, "")}/store/hive/shipments?order_id=${encodeURIComponent(orderId)}`;
+      const response = await fetch(url, {
+        headers: {
+          "Content-Type": "application/json",
+          ...resolvedKey ? { "x-publishable-api-key": resolvedKey } : {}
+        }
+      });
+      if (!response.ok) {
+        throw new Error(`Hive shipment lookup failed: ${response.status}`);
+      }
+      const body = await response.json();
+      setShipments(body.shipments ?? []);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Hive shipment lookup failed"));
+    } finally {
+      setIsPending(false);
+    }
+  }, [orderId, baseUrl, publishableKey]);
+  useEffect(() => {
+    if (!enabled) return;
+    void refetch();
+  }, [enabled, refetch]);
+  return { shipments, isPending, error, refetch };
+}
+export {
+  HiveShipmentStatus,
+  useHiveTracking
+};
+//# sourceMappingURL=index.mjs.map

package/dist/client/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/use-hive-tracking.ts"],"sourcesContent":["'use client'\n\nimport { useCallback, useEffect, useState } from 'react'\nimport type { HiveShipmentDto } from '../types'\n\nexport interface UseHiveTrackingOptions {\n  baseUrl?: string\n  publishableKey?: string\n  /** Skip the initial fetch - useful while the order id is still loading. */\n  enabled?: boolean\n}\n\nexport interface UseHiveTrackingResult {\n  shipments: HiveShipmentDto[]\n  isPending: boolean\n  error: Error | null\n  refetch: () => Promise<void>\n}\n\n/**\n * Reads the Hive shipments for one Medusa order.\n *\n * Hits our own `/store/hive/shipments` route rather than Hive directly:\n * the API key is server-side only and Hive rate-limits at 100 req/min per\n * merchant, so the backend owns the call and the caching.\n *\n * `orderId` is the Medusa order id; the backend maps it to Hive's\n * `merchant_order_id`.\n */\nexport function useHiveTracking(\n  orderId: string,\n  options: UseHiveTrackingOptions = {},\n): UseHiveTrackingResult {\n  const { baseUrl, publishableKey, enabled = true } = options\n\n  const [shipments, setShipments] = useState<HiveShipmentDto[]>([])\n  const [isPending, setIsPending] = useState<boolean>(false)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refetch = useCallback(async (): Promise<void> => {\n    if (!orderId) return\n    setIsPending(true)\n    setError(null)\n    try {\n      const resolvedBaseUrl =\n        baseUrl ?? process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL ?? ''\n      const resolvedKey =\n        publishableKey ?? process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY ?? ''\n      const url = `${resolvedBaseUrl.replace(/\\/$/, '')}/store/hive/shipments?order_id=${encodeURIComponent(orderId)}`\n      const response = await fetch(url, {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(resolvedKey ? { 'x-publishable-api-key': resolvedKey } : {}),\n        },\n      })\n      if (!response.ok) {\n        throw new Error(`Hive shipment lookup failed: ${response.status}`)\n      }\n      const body = (await response.json()) as { shipments?: HiveShipmentDto[] }\n      setShipments(body.shipments ?? [])\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Hive shipment lookup failed'))\n    } finally {\n      setIsPending(false)\n    }\n  }, [orderId, baseUrl, publishableKey])\n\n  useEffect(() => {\n    if (!enabled) return\n    void refetch()\n  }, [enabled, refetch])\n\n  return { shipments, isPending, error, refetch }\n}\n"],"mappings":";;;;;AAEA,SAAS,aAAa,WAAW,gBAAgB;AA2B1C,SAAS,gBACd,SACA,UAAkC,CAAC,GACZ;AACvB,QAAM,EAAE,SAAS,gBAAgB,UAAU,KAAK,IAAI;AAEpD,QAAM,CAAC,WAAW,YAAY,IAAI,SAA4B,CAAC,CAAC;AAChE,QAAM,CAAC,WAAW,YAAY,IAAI,SAAkB,KAAK;AACzD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAuB,IAAI;AAErD,QAAM,UAAU,YAAY,YAA2B;AACrD,QAAI,CAAC,QAAS;AACd,iBAAa,IAAI;AACjB,aAAS,IAAI;AACb,QAAI;AACF,YAAM,kBACJ,WAAW,QAAQ,IAAI,kCAAkC;AAC3D,YAAM,cACJ,kBAAkB,QAAQ,IAAI,sCAAsC;AACtE,YAAM,MAAM,GAAG,gBAAgB,QAAQ,OAAO,EAAE,CAAC,kCAAkC,mBAAmB,OAAO,CAAC;AAC9G,YAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,GAAI,cAAc,EAAE,yBAAyB,YAAY,IAAI,CAAC;AAAA,QAChE;AAAA,MACF,CAAC;AACD,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,IAAI,MAAM,gCAAgC,SAAS,MAAM,EAAE;AAAA,MACnE;AACA,YAAM,OAAQ,MAAM,SAAS,KAAK;AAClC,mBAAa,KAAK,aAAa,CAAC,CAAC;AAAA,IACnC,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,6BAA6B,CAAC;AAAA,IAChF,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,SAAS,SAAS,cAAc,CAAC;AAErC,YAAU,MAAM;AACd,QAAI,CAAC,QAAS;AACd,SAAK,QAAQ;AAAA,EACf,GAAG,CAAC,SAAS,OAAO,CAAC;AAErB,SAAO,EAAE,WAAW,WAAW,OAAO,QAAQ;AAChD;","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,244 @@
+/**
+ * Public types for @amboras-dev/hive.
+ *
+ * Single source of truth for the wire shape between the Amboras admin /
+ * storefront and the medusa-backend-orchestrator Store API routes under
+ * `/store/hive/*`. The DTO files on the Medusa side must stay
+ * byte-compatible with these.
+ *
+ * Field names mirror the Hive Merchant API v1
+ * (https://developers.hive.app/reference/api-reference) exactly, including
+ * its snake_case, so a backend route can pass a Hive payload straight
+ * through without a rename layer.
+ *
+ * The Hive API key is a server-side secret and Hive enforces a
+ * 100 req/min per-merchant rate limit, so nothing in this package ever
+ * calls app.hive.app directly - every hook here talks to our own Medusa
+ * routes, which own the Hive HTTP client.
+ */
+/**
+ * Sentinel returned in place of a stored secret when the settings form
+ * reads back current config. Matches the pattern used by meta-ads,
+ * pinterest and aliexpress-dropshipping so the admin never sees the
+ * plaintext API key after write.
+ */
+declare const SECRET_SET_SENTINEL: "__SECRET_SET__";
+type SecretSetSentinel = typeof SECRET_SET_SENTINEL;
+/** Hive base URLs, keyed by the environment chosen in the settings form. */
+declare const HIVE_BASE_URLS: {
+    readonly production: "https://app.hive.app/merchant_api/v1";
+    readonly staging: "https://staging.app.hive.app/merchant_api/v1";
+};
+type HiveEnvironment = keyof typeof HIVE_BASE_URLS;
+/** Hive allows 100 requests per minute per merchant. */
+declare const HIVE_RATE_LIMIT_PER_MINUTE = 100;
+/**
+ * Pagination block attached to every Hive list response.
+ * Requests page through with `page` (default 1) and `limit`
+ * (default 20, max 100).
+ */
+interface HivePagination {
+    current_page: number;
+    item_count: number;
+    page_count: number;
+    items_per_page: number;
+}
+/** Shape of every Hive list endpoint: `{ data, pagination }`. */
+interface HiveListResponse<T> {
+    data: T[];
+    pagination: HivePagination;
+}
+/**
+ * Hive error body. Every failure carries `success: false` and an array of
+ * human-readable messages; there are no machine-readable error codes, so
+ * the HTTP status is the only thing worth branching on.
+ */
+interface HiveErrorResponse {
+    success: false;
+    errors: string[];
+}
+/** `GET /warehouses` is list-only and every field is read-only. */
+interface HiveWarehouseDto {
+    id: number;
+    name: string;
+    /** 2-letter ISO 3166-1 country code. */
+    country: string;
+    city: string;
+}
+/** Whether Hive can pick the order with the stock it currently holds. */
+declare enum HiveOrderStatus {
+    Fulfillable = "fulfillable",
+    Unfulfillable = "unfulfillable",
+    Fulfilled = "fulfilled"
+}
+declare enum HiveFinancialStatus {
+    Paid = "paid",
+    Refunded = "refunded",
+    Pending = "pending",
+    Failed = "failed"
+}
+interface HiveAddressDto {
+    first_name: string | null;
+    last_name: string | null;
+    company: string | null;
+    address_1: string;
+    address_2: string | null;
+    city: string;
+    province: string | null;
+    zip: string;
+    /** 2-letter ISO 3166-1 country code. */
+    country_code: string;
+    phone: string | null;
+    email: string | null;
+}
+interface HiveOrderItemDto {
+    id: number;
+    merchant_item_id: string | null;
+    merchant_sku_id: string;
+    quantity: number;
+}
+/** Body item for `POST /orders` - references a SKU the merchant already created. */
+interface HiveOrderItemInput {
+    merchant_sku_id: string;
+    quantity: number;
+    merchant_item_id?: string;
+}
+interface HiveOrderDto {
+    id: number;
+    merchant_order_id: string;
+    status: HiveOrderStatus;
+    financial_status: HiveFinancialStatus | null;
+    shipping_address: HiveAddressDto;
+    billing_address: HiveAddressDto | null;
+    items: HiveOrderItemDto[];
+    created_at: string;
+    updated_at: string;
+}
+/** Body for `POST /orders`. */
+interface HiveOrderInput {
+    merchant_order_id: string;
+    shipping_address: HiveAddressDto;
+    items: HiveOrderItemInput[];
+    billing_address?: HiveAddressDto;
+    financial_status?: HiveFinancialStatus;
+}
+/** Warehouse-side progress of a shipment. */
+declare enum HiveShipmentStatus {
+    WaitingForPicking = "waiting_for_picking",
+    OnHold = "on_hold",
+    PickingAssigned = "picking_assigned",
+    InPicking = "in_picking",
+    Picked = "picked",
+    InPacking = "in_packing",
+    Packed = "packed",
+    InShipping = "in_shipping",
+    Shipped = "shipped",
+    Cancelled = "cancelled"
+}
+/**
+ * Carrier-side progress. Hive sends these as human-readable strings
+ * rather than slugs, so they are typed as a literal union of the exact
+ * values the API returns.
+ */
+type HiveDeliveryStatus = 'Information transmitted to the carrier' | 'In transit' | 'Out for delivery' | 'Delivered' | 'Returned to sender' | 'Action required';
+interface HiveShipmentItemSkuDto {
+    id: number;
+    merchant_sku_id: string;
+}
+interface HiveShipmentItemDto {
+    id: number;
+    merchant_item_id: string | null;
+    quantity: number;
+    sku: HiveShipmentItemSkuDto;
+}
+interface HiveShipmentDto {
+    id: number;
+    order_id: number;
+    merchant_order_id: string;
+    status: HiveShipmentStatus;
+    delivery_status: HiveDeliveryStatus | null;
+    shipment_provider: string | null;
+    tracking_number: string | null;
+    tracking_url: string | null;
+    items: HiveShipmentItemDto[];
+    shipped_at: string | null;
+    delivered_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * The four events Hive can push. Registration is not self-serve - the
+ * merchant's Hive account manager configures the destination URL.
+ */
+declare enum HiveWebhookEvent {
+    DeliveryStatusUpdated = "delivery_status_updated",
+    ShipmentStatusUpdated = "shipment_status_updated",
+    RestockingShipmentStatusUpdated = "restocking_shipment_status_updated",
+    ReturnStatusUpdated = "return_status_updated"
+}
+/**
+ * HTTP header carrying the hex-encoded HMAC-SHA256 digest of the raw
+ * request body, keyed by the merchant's API token. Requests without it
+ * must be ignored, and the comparison must be constant-time.
+ */
+declare const HIVE_SIGNATURE_HEADER = "x-hive-signature";
+/**
+ * Hive does not guarantee ordering or exactly-once delivery, so a
+ * consumer must compare the payload's `updated_at` against the last
+ * value it stored and drop anything older.
+ */
+interface HiveWebhookPayload<T = unknown> {
+    event: HiveWebhookEvent;
+    data: T;
+}
+type HiveShipmentWebhookPayload = HiveWebhookPayload<HiveShipmentDto>;
+/**
+ * Per-store Hive plugin configuration.
+ *
+ * - `apiKey` is issued by the merchant's Hive account manager. The admin
+ *   form receives `SECRET_SET_SENTINEL` on read and only sends a real
+ *   value when the merchant types a new one.
+ * - `environment` selects between the production and staging domains.
+ * - `defaultWarehouseId` is the warehouse orders route to when the
+ *   multi-3PL rules do not name one.
+ * - `lastSuccessfulCallAt` is an ISO-8601 timestamp for the status card.
+ */
+interface HivePluginConfig {
+    enabled: boolean;
+    apiKey: string | SecretSetSentinel | null;
+    environment: HiveEnvironment;
+    defaultWarehouseId: number | null;
+    lastSuccessfulCallAt: string | null;
+}
+/** Why the backend considers the stored credential unusable. */
+declare enum HiveConnectionError {
+    MissingApiKey = "missing_api_key",
+    Unauthorized = "unauthorized",
+    RateLimited = "rate_limited",
+    Unreachable = "unreachable"
+}
+/** `GET /store/hive/status`. */
+interface HiveConnectionStatusDto {
+    connected: boolean;
+    environment: HiveEnvironment;
+    /** Populated from `GET /warehouses` on the last successful call. */
+    warehouses: HiveWarehouseDto[];
+    lastSuccessfulCallAt: string | null;
+    error: HiveConnectionError | null;
+    /**
+     * Where the merchant's Hive account manager should point webhooks.
+     * Rendered read-only in the settings form.
+     */
+    webhookUrl: string | null;
+}
+/** `POST /store/hive/test-connection`. */
+type HiveTestConnectionResult = {
+    ok: true;
+    warehouses: HiveWarehouseDto[];
+} | {
+    ok: false;
+    code: HiveConnectionError | 'UNKNOWN';
+    msg: string;
+};
+
+export { HIVE_BASE_URLS, HIVE_RATE_LIMIT_PER_MINUTE, HIVE_SIGNATURE_HEADER, type HiveAddressDto, HiveConnectionError, type HiveConnectionStatusDto, type HiveDeliveryStatus, type HiveEnvironment, type HiveErrorResponse, HiveFinancialStatus, type HiveListResponse, type HiveOrderDto, type HiveOrderInput, type HiveOrderItemDto, type HiveOrderItemInput, HiveOrderStatus, type HivePagination, type HivePluginConfig, type HiveShipmentDto, type HiveShipmentItemDto, type HiveShipmentItemSkuDto, HiveShipmentStatus, type HiveShipmentWebhookPayload, type HiveTestConnectionResult, type HiveWarehouseDto, HiveWebhookEvent, type HiveWebhookPayload, SECRET_SET_SENTINEL, type SecretSetSentinel };

package/dist/index.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Public types for @amboras-dev/hive.
+ *
+ * Single source of truth for the wire shape between the Amboras admin /
+ * storefront and the medusa-backend-orchestrator Store API routes under
+ * `/store/hive/*`. The DTO files on the Medusa side must stay
+ * byte-compatible with these.
+ *
+ * Field names mirror the Hive Merchant API v1
+ * (https://developers.hive.app/reference/api-reference) exactly, including
+ * its snake_case, so a backend route can pass a Hive payload straight
+ * through without a rename layer.
+ *
+ * The Hive API key is a server-side secret and Hive enforces a
+ * 100 req/min per-merchant rate limit, so nothing in this package ever
+ * calls app.hive.app directly - every hook here talks to our own Medusa
+ * routes, which own the Hive HTTP client.
+ */
+/**
+ * Sentinel returned in place of a stored secret when the settings form
+ * reads back current config. Matches the pattern used by meta-ads,
+ * pinterest and aliexpress-dropshipping so the admin never sees the
+ * plaintext API key after write.
+ */
+declare const SECRET_SET_SENTINEL: "__SECRET_SET__";
+type SecretSetSentinel = typeof SECRET_SET_SENTINEL;
+/** Hive base URLs, keyed by the environment chosen in the settings form. */
+declare const HIVE_BASE_URLS: {
+    readonly production: "https://app.hive.app/merchant_api/v1";
+    readonly staging: "https://staging.app.hive.app/merchant_api/v1";
+};
+type HiveEnvironment = keyof typeof HIVE_BASE_URLS;
+/** Hive allows 100 requests per minute per merchant. */
+declare const HIVE_RATE_LIMIT_PER_MINUTE = 100;
+/**
+ * Pagination block attached to every Hive list response.
+ * Requests page through with `page` (default 1) and `limit`
+ * (default 20, max 100).
+ */
+interface HivePagination {
+    current_page: number;
+    item_count: number;
+    page_count: number;
+    items_per_page: number;
+}
+/** Shape of every Hive list endpoint: `{ data, pagination }`. */
+interface HiveListResponse<T> {
+    data: T[];
+    pagination: HivePagination;
+}
+/**
+ * Hive error body. Every failure carries `success: false` and an array of
+ * human-readable messages; there are no machine-readable error codes, so
+ * the HTTP status is the only thing worth branching on.
+ */
+interface HiveErrorResponse {
+    success: false;
+    errors: string[];
+}
+/** `GET /warehouses` is list-only and every field is read-only. */
+interface HiveWarehouseDto {
+    id: number;
+    name: string;
+    /** 2-letter ISO 3166-1 country code. */
+    country: string;
+    city: string;
+}
+/** Whether Hive can pick the order with the stock it currently holds. */
+declare enum HiveOrderStatus {
+    Fulfillable = "fulfillable",
+    Unfulfillable = "unfulfillable",
+    Fulfilled = "fulfilled"
+}
+declare enum HiveFinancialStatus {
+    Paid = "paid",
+    Refunded = "refunded",
+    Pending = "pending",
+    Failed = "failed"
+}
+interface HiveAddressDto {
+    first_name: string | null;
+    last_name: string | null;
+    company: string | null;
+    address_1: string;
+    address_2: string | null;
+    city: string;
+    province: string | null;
+    zip: string;
+    /** 2-letter ISO 3166-1 country code. */
+    country_code: string;
+    phone: string | null;
+    email: string | null;
+}
+interface HiveOrderItemDto {
+    id: number;
+    merchant_item_id: string | null;
+    merchant_sku_id: string;
+    quantity: number;
+}
+/** Body item for `POST /orders` - references a SKU the merchant already created. */
+interface HiveOrderItemInput {
+    merchant_sku_id: string;
+    quantity: number;
+    merchant_item_id?: string;
+}
+interface HiveOrderDto {
+    id: number;
+    merchant_order_id: string;
+    status: HiveOrderStatus;
+    financial_status: HiveFinancialStatus | null;
+    shipping_address: HiveAddressDto;
+    billing_address: HiveAddressDto | null;
+    items: HiveOrderItemDto[];
+    created_at: string;
+    updated_at: string;
+}
+/** Body for `POST /orders`. */
+interface HiveOrderInput {
+    merchant_order_id: string;
+    shipping_address: HiveAddressDto;
+    items: HiveOrderItemInput[];
+    billing_address?: HiveAddressDto;
+    financial_status?: HiveFinancialStatus;
+}
+/** Warehouse-side progress of a shipment. */
+declare enum HiveShipmentStatus {
+    WaitingForPicking = "waiting_for_picking",
+    OnHold = "on_hold",
+    PickingAssigned = "picking_assigned",
+    InPicking = "in_picking",
+    Picked = "picked",
+    InPacking = "in_packing",
+    Packed = "packed",
+    InShipping = "in_shipping",
+    Shipped = "shipped",
+    Cancelled = "cancelled"
+}
+/**
+ * Carrier-side progress. Hive sends these as human-readable strings
+ * rather than slugs, so they are typed as a literal union of the exact
+ * values the API returns.
+ */
+type HiveDeliveryStatus = 'Information transmitted to the carrier' | 'In transit' | 'Out for delivery' | 'Delivered' | 'Returned to sender' | 'Action required';
+interface HiveShipmentItemSkuDto {
+    id: number;
+    merchant_sku_id: string;
+}
+interface HiveShipmentItemDto {
+    id: number;
+    merchant_item_id: string | null;
+    quantity: number;
+    sku: HiveShipmentItemSkuDto;
+}
+interface HiveShipmentDto {
+    id: number;
+    order_id: number;
+    merchant_order_id: string;
+    status: HiveShipmentStatus;
+    delivery_status: HiveDeliveryStatus | null;
+    shipment_provider: string | null;
+    tracking_number: string | null;
+    tracking_url: string | null;
+    items: HiveShipmentItemDto[];
+    shipped_at: string | null;
+    delivered_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * The four events Hive can push. Registration is not self-serve - the
+ * merchant's Hive account manager configures the destination URL.
+ */
+declare enum HiveWebhookEvent {
+    DeliveryStatusUpdated = "delivery_status_updated",
+    ShipmentStatusUpdated = "shipment_status_updated",
+    RestockingShipmentStatusUpdated = "restocking_shipment_status_updated",
+    ReturnStatusUpdated = "return_status_updated"
+}
+/**
+ * HTTP header carrying the hex-encoded HMAC-SHA256 digest of the raw
+ * request body, keyed by the merchant's API token. Requests without it
+ * must be ignored, and the comparison must be constant-time.
+ */
+declare const HIVE_SIGNATURE_HEADER = "x-hive-signature";
+/**
+ * Hive does not guarantee ordering or exactly-once delivery, so a
+ * consumer must compare the payload's `updated_at` against the last
+ * value it stored and drop anything older.
+ */
+interface HiveWebhookPayload<T = unknown> {
+    event: HiveWebhookEvent;
+    data: T;
+}
+type HiveShipmentWebhookPayload = HiveWebhookPayload<HiveShipmentDto>;
+/**
+ * Per-store Hive plugin configuration.
+ *
+ * - `apiKey` is issued by the merchant's Hive account manager. The admin
+ *   form receives `SECRET_SET_SENTINEL` on read and only sends a real
+ *   value when the merchant types a new one.
+ * - `environment` selects between the production and staging domains.
+ * - `defaultWarehouseId` is the warehouse orders route to when the
+ *   multi-3PL rules do not name one.
+ * - `lastSuccessfulCallAt` is an ISO-8601 timestamp for the status card.
+ */
+interface HivePluginConfig {
+    enabled: boolean;
+    apiKey: string | SecretSetSentinel | null;
+    environment: HiveEnvironment;
+    defaultWarehouseId: number | null;
+    lastSuccessfulCallAt: string | null;
+}
+/** Why the backend considers the stored credential unusable. */
+declare enum HiveConnectionError {
+    MissingApiKey = "missing_api_key",
+    Unauthorized = "unauthorized",
+    RateLimited = "rate_limited",
+    Unreachable = "unreachable"
+}
+/** `GET /store/hive/status`. */
+interface HiveConnectionStatusDto {
+    connected: boolean;
+    environment: HiveEnvironment;
+    /** Populated from `GET /warehouses` on the last successful call. */
+    warehouses: HiveWarehouseDto[];
+    lastSuccessfulCallAt: string | null;
+    error: HiveConnectionError | null;
+    /**
+     * Where the merchant's Hive account manager should point webhooks.
+     * Rendered read-only in the settings form.
+     */
+    webhookUrl: string | null;
+}
+/** `POST /store/hive/test-connection`. */
+type HiveTestConnectionResult = {
+    ok: true;
+    warehouses: HiveWarehouseDto[];
+} | {
+    ok: false;
+    code: HiveConnectionError | 'UNKNOWN';
+    msg: string;
+};
+
+export { HIVE_BASE_URLS, HIVE_RATE_LIMIT_PER_MINUTE, HIVE_SIGNATURE_HEADER, type HiveAddressDto, HiveConnectionError, type HiveConnectionStatusDto, type HiveDeliveryStatus, type HiveEnvironment, type HiveErrorResponse, HiveFinancialStatus, type HiveListResponse, type HiveOrderDto, type HiveOrderInput, type HiveOrderItemDto, type HiveOrderItemInput, HiveOrderStatus, type HivePagination, type HivePluginConfig, type HiveShipmentDto, type HiveShipmentItemDto, type HiveShipmentItemSkuDto, HiveShipmentStatus, type HiveShipmentWebhookPayload, type HiveTestConnectionResult, type HiveWarehouseDto, HiveWebhookEvent, type HiveWebhookPayload, SECRET_SET_SENTINEL, type SecretSetSentinel };

package/dist/index.js

@@ -0,0 +1,95 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  HIVE_BASE_URLS: () => HIVE_BASE_URLS,
+  HIVE_RATE_LIMIT_PER_MINUTE: () => HIVE_RATE_LIMIT_PER_MINUTE,
+  HIVE_SIGNATURE_HEADER: () => HIVE_SIGNATURE_HEADER,
+  HiveConnectionError: () => HiveConnectionError,
+  HiveFinancialStatus: () => HiveFinancialStatus,
+  HiveOrderStatus: () => HiveOrderStatus,
+  HiveShipmentStatus: () => HiveShipmentStatus,
+  HiveWebhookEvent: () => HiveWebhookEvent,
+  SECRET_SET_SENTINEL: () => SECRET_SET_SENTINEL
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/types.ts
+var SECRET_SET_SENTINEL = "__SECRET_SET__";
+var HIVE_BASE_URLS = {
+  production: "https://app.hive.app/merchant_api/v1",
+  staging: "https://staging.app.hive.app/merchant_api/v1"
+};
+var HIVE_RATE_LIMIT_PER_MINUTE = 100;
+var HiveOrderStatus = /* @__PURE__ */ ((HiveOrderStatus2) => {
+  HiveOrderStatus2["Fulfillable"] = "fulfillable";
+  HiveOrderStatus2["Unfulfillable"] = "unfulfillable";
+  HiveOrderStatus2["Fulfilled"] = "fulfilled";
+  return HiveOrderStatus2;
+})(HiveOrderStatus || {});
+var HiveFinancialStatus = /* @__PURE__ */ ((HiveFinancialStatus2) => {
+  HiveFinancialStatus2["Paid"] = "paid";
+  HiveFinancialStatus2["Refunded"] = "refunded";
+  HiveFinancialStatus2["Pending"] = "pending";
+  HiveFinancialStatus2["Failed"] = "failed";
+  return HiveFinancialStatus2;
+})(HiveFinancialStatus || {});
+var HiveShipmentStatus = /* @__PURE__ */ ((HiveShipmentStatus2) => {
+  HiveShipmentStatus2["WaitingForPicking"] = "waiting_for_picking";
+  HiveShipmentStatus2["OnHold"] = "on_hold";
+  HiveShipmentStatus2["PickingAssigned"] = "picking_assigned";
+  HiveShipmentStatus2["InPicking"] = "in_picking";
+  HiveShipmentStatus2["Picked"] = "picked";
+  HiveShipmentStatus2["InPacking"] = "in_packing";
+  HiveShipmentStatus2["Packed"] = "packed";
+  HiveShipmentStatus2["InShipping"] = "in_shipping";
+  HiveShipmentStatus2["Shipped"] = "shipped";
+  HiveShipmentStatus2["Cancelled"] = "cancelled";
+  return HiveShipmentStatus2;
+})(HiveShipmentStatus || {});
+var HiveWebhookEvent = /* @__PURE__ */ ((HiveWebhookEvent2) => {
+  HiveWebhookEvent2["DeliveryStatusUpdated"] = "delivery_status_updated";
+  HiveWebhookEvent2["ShipmentStatusUpdated"] = "shipment_status_updated";
+  HiveWebhookEvent2["RestockingShipmentStatusUpdated"] = "restocking_shipment_status_updated";
+  HiveWebhookEvent2["ReturnStatusUpdated"] = "return_status_updated";
+  return HiveWebhookEvent2;
+})(HiveWebhookEvent || {});
+var HIVE_SIGNATURE_HEADER = "x-hive-signature";
+var HiveConnectionError = /* @__PURE__ */ ((HiveConnectionError2) => {
+  HiveConnectionError2["MissingApiKey"] = "missing_api_key";
+  HiveConnectionError2["Unauthorized"] = "unauthorized";
+  HiveConnectionError2["RateLimited"] = "rate_limited";
+  HiveConnectionError2["Unreachable"] = "unreachable";
+  return HiveConnectionError2;
+})(HiveConnectionError || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HIVE_BASE_URLS,
+  HIVE_RATE_LIMIT_PER_MINUTE,
+  HIVE_SIGNATURE_HEADER,
+  HiveConnectionError,
+  HiveFinancialStatus,
+  HiveOrderStatus,
+  HiveShipmentStatus,
+  HiveWebhookEvent,
+  SECRET_SET_SENTINEL
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/types.ts"],"sourcesContent":["// Shared wire types for the Hive 3PL integration — kept byte-compatible\n// with the DTOs in medusa-backend-orchestrator's `src/modules/hive/types.ts`.\n//\n// There is no React surface on this entrypoint. The storefront tracking\n// hook lives on `@amboras-dev/hive/client`; the admin settings UI lives in\n// the orchestrator admin app. Same split as meta-ads.\nexport {\n  SECRET_SET_SENTINEL,\n  HIVE_BASE_URLS,\n  HIVE_RATE_LIMIT_PER_MINUTE,\n  HIVE_SIGNATURE_HEADER,\n  HiveOrderStatus,\n  HiveFinancialStatus,\n  HiveShipmentStatus,\n  HiveWebhookEvent,\n  HiveConnectionError,\n} from './types'\nexport type {\n  SecretSetSentinel,\n  HiveEnvironment,\n  HivePagination,\n  HiveListResponse,\n  HiveErrorResponse,\n  HiveWarehouseDto,\n  HiveAddressDto,\n  HiveOrderItemDto,\n  HiveOrderItemInput,\n  HiveOrderDto,\n  HiveOrderInput,\n  HiveDeliveryStatus,\n  HiveShipmentItemSkuDto,\n  HiveShipmentItemDto,\n  HiveShipmentDto,\n  HiveWebhookPayload,\n  HiveShipmentWebhookPayload,\n  HivePluginConfig,\n  HiveConnectionStatusDto,\n  HiveTestConnectionResult,\n} from './types'\n","/**\n * Public types for @amboras-dev/hive.\n *\n * Single source of truth for the wire shape between the Amboras admin /\n * storefront and the medusa-backend-orchestrator Store API routes under\n * `/store/hive/*`. The DTO files on the Medusa side must stay\n * byte-compatible with these.\n *\n * Field names mirror the Hive Merchant API v1\n * (https://developers.hive.app/reference/api-reference) exactly, including\n * its snake_case, so a backend route can pass a Hive payload straight\n * through without a rename layer.\n *\n * The Hive API key is a server-side secret and Hive enforces a\n * 100 req/min per-merchant rate limit, so nothing in this package ever\n * calls app.hive.app directly - every hook here talks to our own Medusa\n * routes, which own the Hive HTTP client.\n */\n\n/**\n * Sentinel returned in place of a stored secret when the settings form\n * reads back current config. Matches the pattern used by meta-ads,\n * pinterest and aliexpress-dropshipping so the admin never sees the\n * plaintext API key after write.\n */\nexport const SECRET_SET_SENTINEL = '__SECRET_SET__' as const\nexport type SecretSetSentinel = typeof SECRET_SET_SENTINEL\n\n/** Hive base URLs, keyed by the environment chosen in the settings form. */\nexport const HIVE_BASE_URLS = {\n  production: 'https://app.hive.app/merchant_api/v1',\n  staging: 'https://staging.app.hive.app/merchant_api/v1',\n} as const\n\nexport type HiveEnvironment = keyof typeof HIVE_BASE_URLS\n\n/** Hive allows 100 requests per minute per merchant. */\nexport const HIVE_RATE_LIMIT_PER_MINUTE = 100\n\n/* -------------------------------------------------------------------------\n * Envelope\n * ---------------------------------------------------------------------- */\n\n/**\n * Pagination block attached to every Hive list response.\n * Requests page through with `page` (default 1) and `limit`\n * (default 20, max 100).\n */\nexport interface HivePagination {\n  current_page: number\n  item_count: number\n  page_count: number\n  items_per_page: number\n}\n\n/** Shape of every Hive list endpoint: `{ data, pagination }`. */\nexport interface HiveListResponse<T> {\n  data: T[]\n  pagination: HivePagination\n}\n\n/**\n * Hive error body. Every failure carries `success: false` and an array of\n * human-readable messages; there are no machine-readable error codes, so\n * the HTTP status is the only thing worth branching on.\n */\nexport interface HiveErrorResponse {\n  success: false\n  errors: string[]\n}\n\n/* -------------------------------------------------------------------------\n * Warehouses\n * ---------------------------------------------------------------------- */\n\n/** `GET /warehouses` is list-only and every field is read-only. */\nexport interface HiveWarehouseDto {\n  id: number\n  name: string\n  /** 2-letter ISO 3166-1 country code. */\n  country: string\n  city: string\n}\n\n/* -------------------------------------------------------------------------\n * Orders\n * ---------------------------------------------------------------------- */\n\n/** Whether Hive can pick the order with the stock it currently holds. */\nexport enum HiveOrderStatus {\n  Fulfillable = 'fulfillable',\n  Unfulfillable = 'unfulfillable',\n  Fulfilled = 'fulfilled',\n}\n\nexport enum HiveFinancialStatus {\n  Paid = 'paid',\n  Refunded = 'refunded',\n  Pending = 'pending',\n  Failed = 'failed',\n}\n\nexport interface HiveAddressDto {\n  first_name: string | null\n  last_name: string | null\n  company: string | null\n  address_1: string\n  address_2: string | null\n  city: string\n  province: string | null\n  zip: string\n  /** 2-letter ISO 3166-1 country code. */\n  country_code: string\n  phone: string | null\n  email: string | null\n}\n\nexport interface HiveOrderItemDto {\n  id: number\n  merchant_item_id: string | null\n  merchant_sku_id: string\n  quantity: number\n}\n\n/** Body item for `POST /orders` - references a SKU the merchant already created. */\nexport interface HiveOrderItemInput {\n  merchant_sku_id: string\n  quantity: number\n  merchant_item_id?: string\n}\n\nexport interface HiveOrderDto {\n  id: number\n  merchant_order_id: string\n  status: HiveOrderStatus\n  financial_status: HiveFinancialStatus | null\n  shipping_address: HiveAddressDto\n  billing_address: HiveAddressDto | null\n  items: HiveOrderItemDto[]\n  created_at: string\n  updated_at: string\n}\n\n/** Body for `POST /orders`. */\nexport interface HiveOrderInput {\n  merchant_order_id: string\n  shipping_address: HiveAddressDto\n  items: HiveOrderItemInput[]\n  billing_address?: HiveAddressDto\n  financial_status?: HiveFinancialStatus\n}\n\n/* -------------------------------------------------------------------------\n * Shipments\n * ---------------------------------------------------------------------- */\n\n/** Warehouse-side progress of a shipment. */\nexport enum HiveShipmentStatus {\n  WaitingForPicking = 'waiting_for_picking',\n  OnHold = 'on_hold',\n  PickingAssigned = 'picking_assigned',\n  InPicking = 'in_picking',\n  Picked = 'picked',\n  InPacking = 'in_packing',\n  Packed = 'packed',\n  InShipping = 'in_shipping',\n  Shipped = 'shipped',\n  Cancelled = 'cancelled',\n}\n\n/**\n * Carrier-side progress. Hive sends these as human-readable strings\n * rather than slugs, so they are typed as a literal union of the exact\n * values the API returns.\n */\nexport type HiveDeliveryStatus =\n  | 'Information transmitted to the carrier'\n  | 'In transit'\n  | 'Out for delivery'\n  | 'Delivered'\n  | 'Returned to sender'\n  | 'Action required'\n\nexport interface HiveShipmentItemSkuDto {\n  id: number\n  merchant_sku_id: string\n}\n\nexport interface HiveShipmentItemDto {\n  id: number\n  merchant_item_id: string | null\n  quantity: number\n  sku: HiveShipmentItemSkuDto\n}\n\nexport interface HiveShipmentDto {\n  id: number\n  order_id: number\n  merchant_order_id: string\n  status: HiveShipmentStatus\n  delivery_status: HiveDeliveryStatus | null\n  shipment_provider: string | null\n  tracking_number: string | null\n  tracking_url: string | null\n  items: HiveShipmentItemDto[]\n  shipped_at: string | null\n  delivered_at: string | null\n  created_at: string\n  updated_at: string\n}\n\n/* -------------------------------------------------------------------------\n * Webhooks\n * ---------------------------------------------------------------------- */\n\n/**\n * The four events Hive can push. Registration is not self-serve - the\n * merchant's Hive account manager configures the destination URL.\n */\nexport enum HiveWebhookEvent {\n  DeliveryStatusUpdated = 'delivery_status_updated',\n  ShipmentStatusUpdated = 'shipment_status_updated',\n  RestockingShipmentStatusUpdated = 'restocking_shipment_status_updated',\n  ReturnStatusUpdated = 'return_status_updated',\n}\n\n/**\n * HTTP header carrying the hex-encoded HMAC-SHA256 digest of the raw\n * request body, keyed by the merchant's API token. Requests without it\n * must be ignored, and the comparison must be constant-time.\n */\nexport const HIVE_SIGNATURE_HEADER = 'x-hive-signature'\n\n/**\n * Hive does not guarantee ordering or exactly-once delivery, so a\n * consumer must compare the payload's `updated_at` against the last\n * value it stored and drop anything older.\n */\nexport interface HiveWebhookPayload<T = unknown> {\n  event: HiveWebhookEvent\n  data: T\n}\n\nexport type HiveShipmentWebhookPayload = HiveWebhookPayload<HiveShipmentDto>\n\n/* -------------------------------------------------------------------------\n * Plugin config + admin surface\n * ---------------------------------------------------------------------- */\n\n/**\n * Per-store Hive plugin configuration.\n *\n * - `apiKey` is issued by the merchant's Hive account manager. The admin\n *   form receives `SECRET_SET_SENTINEL` on read and only sends a real\n *   value when the merchant types a new one.\n * - `environment` selects between the production and staging domains.\n * - `defaultWarehouseId` is the warehouse orders route to when the\n *   multi-3PL rules do not name one.\n * - `lastSuccessfulCallAt` is an ISO-8601 timestamp for the status card.\n */\nexport interface HivePluginConfig {\n  enabled: boolean\n  apiKey: string | SecretSetSentinel | null\n  environment: HiveEnvironment\n  defaultWarehouseId: number | null\n  lastSuccessfulCallAt: string | null\n}\n\n/** Why the backend considers the stored credential unusable. */\nexport enum HiveConnectionError {\n  MissingApiKey = 'missing_api_key',\n  Unauthorized = 'unauthorized',\n  RateLimited = 'rate_limited',\n  Unreachable = 'unreachable',\n}\n\n/** `GET /store/hive/status`. */\nexport interface HiveConnectionStatusDto {\n  connected: boolean\n  environment: HiveEnvironment\n  /** Populated from `GET /warehouses` on the last successful call. */\n  warehouses: HiveWarehouseDto[]\n  lastSuccessfulCallAt: string | null\n  error: HiveConnectionError | null\n  /**\n   * Where the merchant's Hive account manager should point webhooks.\n   * Rendered read-only in the settings form.\n   */\n  webhookUrl: string | null\n}\n\n/** `POST /store/hive/test-connection`. */\nexport type HiveTestConnectionResult =\n  | { ok: true; warehouses: HiveWarehouseDto[] }\n  | { ok: false; code: HiveConnectionError | 'UNKNOWN'; msg: string }\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACyBO,IAAM,sBAAsB;AAI5B,IAAM,iBAAiB;AAAA,EAC5B,YAAY;AAAA,EACZ,SAAS;AACX;AAKO,IAAM,6BAA6B;AAoDnC,IAAK,kBAAL,kBAAKA,qBAAL;AACL,EAAAA,iBAAA,iBAAc;AACd,EAAAA,iBAAA,mBAAgB;AAChB,EAAAA,iBAAA,eAAY;AAHF,SAAAA;AAAA,GAAA;AAML,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,UAAO;AACP,EAAAA,qBAAA,cAAW;AACX,EAAAA,qBAAA,aAAU;AACV,EAAAA,qBAAA,YAAS;AAJC,SAAAA;AAAA,GAAA;AA8DL,IAAK,qBAAL,kBAAKC,wBAAL;AACL,EAAAA,oBAAA,uBAAoB;AACpB,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,qBAAkB;AAClB,EAAAA,oBAAA,eAAY;AACZ,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,eAAY;AACZ,EAAAA,oBAAA,YAAS;AACT,EAAAA,oBAAA,gBAAa;AACb,EAAAA,oBAAA,aAAU;AACV,EAAAA,oBAAA,eAAY;AAVF,SAAAA;AAAA,GAAA;AA8DL,IAAK,mBAAL,kBAAKC,sBAAL;AACL,EAAAA,kBAAA,2BAAwB;AACxB,EAAAA,kBAAA,2BAAwB;AACxB,EAAAA,kBAAA,qCAAkC;AAClC,EAAAA,kBAAA,yBAAsB;AAJZ,SAAAA;AAAA,GAAA;AAYL,IAAM,wBAAwB;AAsC9B,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,mBAAgB;AAChB,EAAAA,qBAAA,kBAAe;AACf,EAAAA,qBAAA,iBAAc;AACd,EAAAA,qBAAA,iBAAc;AAJJ,SAAAA;AAAA,GAAA;","names":["HiveOrderStatus","HiveFinancialStatus","HiveShipmentStatus","HiveWebhookEvent","HiveConnectionError"]}

package/dist/index.mjs

@@ -0,0 +1,23 @@
+import {
+  HIVE_BASE_URLS,
+  HIVE_RATE_LIMIT_PER_MINUTE,
+  HIVE_SIGNATURE_HEADER,
+  HiveConnectionError,
+  HiveFinancialStatus,
+  HiveOrderStatus,
+  HiveShipmentStatus,
+  HiveWebhookEvent,
+  SECRET_SET_SENTINEL
+} from "./chunk-BADYBNR7.mjs";
+export {
+  HIVE_BASE_URLS,
+  HIVE_RATE_LIMIT_PER_MINUTE,
+  HIVE_SIGNATURE_HEADER,
+  HiveConnectionError,
+  HiveFinancialStatus,
+  HiveOrderStatus,
+  HiveShipmentStatus,
+  HiveWebhookEvent,
+  SECRET_SET_SENTINEL
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@amboras-dev/hive",
+  "version": "0.1.0",
+  "description": "Hive 3PL fulfillment integration for Amboras - shared wire types and storefront shipment tracking",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.mjs",
+      "require": "./dist/client/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "next": ">=15"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}