ShipEngine API

/**
 * ShipEngineAPI - generated by OmniStream from ShipEngine API's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/shipengine";

export class ShipEngineAPIError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `ShipEngineAPI error ${status}`);
    this.name = "ShipEngineAPIError";
    this.status = status;
    this.code = code;
  }
}

export interface ShipEngineAPIOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class ShipEngineAPI {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: ShipEngineAPIOptions = {}) {
    if (!token) throw new Error("ShipEngineAPI: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new ShipEngineAPIError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Parse an address */
  parseAddress(body: unknown): Promise<any> {
    return this._request("PUT", "/v1/addresses/recognize", { body });
  }

  /** Validate An Address */
  validateAddress(body: unknown): Promise<any> {
    return this._request("POST", "/v1/addresses/validate", { body });
  }

  /** List Batches */
  listBatches(params: { "status"?: string; "page"?: number; "page_size"?: number; "sort_dir"?: string; "batch_number"?: string; "sort_by"?: string }): Promise<any> {
    return this._request("GET", "/v1/batches", { params });
  }

  /** Create A Batch */
  createBatch(body: unknown): Promise<any> {
    return this._request("POST", "/v1/batches", { body });
  }

  /** Get Batch By External ID */
  getBatchByExternalId(params: { "external_batch_id": string }): Promise<any> {
    return this._request("GET", "/v1/batches/external_batch_id/{external_batch_id}", { params });
  }

  /** Get Batch By ID */
  getBatchById(params: { "batch_id": string }): Promise<any> {
    return this._request("GET", "/v1/batches/{batch_id}", { params });
  }

  /** Update Batch By Id */
  updateBatch(params: { "batch_id": string }): Promise<any> {
    return this._request("PUT", "/v1/batches/{batch_id}", { params });
  }

  /** Delete Batch By Id */
  deleteBatch(params: { "batch_id": string }): Promise<any> {
    return this._request("DELETE", "/v1/batches/{batch_id}", { params });
  }

  /** Add to a Batch */
  addToBatch(body: unknown, params: { "batch_id": string }): Promise<any> {
    return this._request("POST", "/v1/batches/{batch_id}/add", { body, params });
  }

  /** Get Batch Errors */
  listBatchErrors(params: { "batch_id": string; "page"?: number; "pagesize"?: number }): Promise<any> {
    return this._request("GET", "/v1/batches/{batch_id}/errors", { params });
  }

  /** Process Batch ID Labels */
  processBatch(body: unknown, params: { "batch_id": string }): Promise<any> {
    return this._request("POST", "/v1/batches/{batch_id}/process/labels", { body, params });
  }

  /** Remove From Batch */
  removeFromBatch(body: unknown, params: { "batch_id": string }): Promise<any> {
    return this._request("POST", "/v1/batches/{batch_id}/remove", { body, params });
  }

  /** List Carriers */
  listCarriers(): Promise<any> {
    return this._request("GET", "/v1/carriers", {});
  }

  /** Get Carrier By ID */
  getCarrierById(params: { "carrier_id": string }): Promise<any> {
    return this._request("GET", "/v1/carriers/{carrier_id}", { params });
  }

  /** Add Funds To Carrier */
  addFundsToCarrier(body: unknown, params: { "carrier_id": string }): Promise<any> {
    return this._request("PUT", "/v1/carriers/{carrier_id}/add_funds", { body, params });
  }

  /** Get Carrier Options */
  getCarrierOptions(params: { "carrier_id": string }): Promise<any> {
    return this._request("GET", "/v1/carriers/{carrier_id}/options", { params });
  }

  /** List Carrier Package Types */
  listCarrierPackageTypes(params: { "carrier_id": string }): Promise<any> {
    return this._request("GET", "/v1/carriers/{carrier_id}/packages", { params });
  }

  /** List Carrier Services */
  listCarrierServices(params: { "carrier_id": string }): Promise<any> {
    return this._request("GET", "/v1/carriers/{carrier_id}/services", { params });
  }

  /** Connect a carrier account */
  connectCarrier(body: unknown, params: { "carrier_name": string }): Promise<any> {
    return this._request("POST", "/v1/connections/carriers/{carrier_name}", { body, params });
  }

  /** Disconnect a carrier */
  disconnectCarrier(params: { "carrier_name": string; "carrier_id": string }): Promise<any> {
    return this._request("DELETE", "/v1/connections/carriers/{carrier_name}/{carrier_id}", { params });
  }

  /** Get carrier settings */
  getCarrierSettings(params: { "carrier_name": string; "carrier_id": string }): Promise<any> {
    return this._request("GET", "/v1/connections/carriers/{carrier_name}/{carrier_id}/settings", { params });
  }

  /** Update carrier settings */
  updateCarrierSettings(body: unknown, params: { "carrier_name": string; "carrier_id": string }): Promise<any> {
    return this._request("PUT", "/v1/connections/carriers/{carrier_name}/{carrier_id}/settings", { body, params });
  }

  /** Connect a Shipsurance Account */
  connectInsurer(body: unknown): Promise<any> {
    return this._request("POST", "/v1/connections/insurance/shipsurance", { body });
  }

  /** Disconnect a Shipsurance Account */
  disconnectInsurer(): Promise<any> {
    return this._request("DELETE", "/v1/connections/insurance/shipsurance", {});
  }

  /** Download File */
  downloadFile(params: { "subdir": string; "filename": string; "dir": string; "download"?: string; "rotation"?: number }): Promise<any> {
    return this._request("GET", "/v1/downloads/{dir}/{subdir}/{filename}", { params });
  }

  /** List Webhooks */
  listWebhooks(): Promise<any> {
    return this._request("GET", "/v1/environment/webhooks", {});
  }

  /** Create a Webhook */
  createWebhook(body: unknown): Promise<any> {
    return this._request("POST", "/v1/environment/webhooks", { body });
  }

  /** Get Webhook By ID */
  getWebhookById(params: { "webhook_id": string }): Promise<any> {
    return this._request("GET", "/v1/environment/webhooks/{webhook_id}", { params });
  }

  /** Update a Webhook */
  updateWebhook(body: unknown, params: { "webhook_id": string }): Promise<any> {
    return this._request("PUT", "/v1/environment/webhooks/{webhook_id}", { body, params });
  }

  /** Delete Webhook By ID */
  deleteWebhook(params: { "webhook_id": string }): Promise<any> {
    return this._request("DELETE", "/v1/environment/webhooks/{webhook_id}", { params });
  }

  /** Add Funds To Insurance */
  addFundsToInsurance(body: unknown): Promise<any> {
    return this._request("PATCH", "/v1/insurance/shipsurance/add_funds", { body });
  }

  /** Get Insurance Funds Balance */
  getInsuranceBalance(): Promise<any> {
    return this._request("GET", "/v1/insurance/shipsurance/balance", {});
  }

  /** List labels */
  listLabels(params: { "label_status"?: string; "service_code"?: string; "carrier_id"?: string; "tracking_number"?: string; "batch_id"?: string; "rate_id"?: string; "shipment_id"?: string; "warehouse_id"?: string; "created_at_start"?: string; "created_at_end"?: string; "page"?: number; "page_size"?: number; "sort_dir"?: string; "sort_by"?: string }): Promise<any> {
    return this._request("GET", "/v1/labels", { params });
  }

  /** Purchase Label */
  createLabel(body: unknown): Promise<any> {
    return this._request("POST", "/v1/labels", { body });
  }

  /** Get Label By External Shipment ID */
  getLabelByExternalShipmentId(params: { "external_shipment_id": string; "label_download_type"?: string }): Promise<any> {
    return this._request("GET", "/v1/labels/external_shipment_id/{external_shipment_id}", { params });
  }

  /** Purchase Label with Rate ID */
  createLabelFromRate(body: unknown, params: { "rate_id": string }): Promise<any> {
    return this._request("POST", "/v1/labels/rates/{rate_id}", { body, params });
  }

  /** Purchase Label with Shipment ID */
  createLabelFromShipment(body: unknown, params: { "shipment_id": string }): Promise<any> {
    return this._request("POST", "/v1/labels/shipment/{shipment_id}", { body, params });
  }

  /** Get Label By ID */
  getLabelById(params: { "label_id": string; "label_download_type"?: string }): Promise<any> {
    return this._request("GET", "/v1/labels/{label_id}", { params });
  }

  /** Create a return label */
  createReturnLabel(body: unknown, params: { "label_id": string }): Promise<any> {
    return this._request("POST", "/v1/labels/{label_id}/return", { body, params });
  }

  /** Get Label Tracking Information */
  getTrackingLogFromLabel(params: { "label_id": string }): Promise<any> {
    return this._request("GET", "/v1/labels/{label_id}/track", { params });
  }

  /** Void a Label By ID */
  voidLabel(params: { "label_id": string }): Promise<any> {
    return this._request("PUT", "/v1/labels/{label_id}/void", { params });
  }

  /** List Manifests */
  listManifests(params: { "warehouse_id"?: string; "ship_date_start"?: string; "ship_date_end"?: string; "created_at_start"?: string; "created_at_end"?: string; "carrier_id"?: string; "page"?: number; "page_size"?: number; "label_ids"?: unknown[] }): Promise<any> {
    return this._request("GET", "/v1/manifests", { params });
  }

  /** Create Manifest */
  createManifest(body: unknown): Promise<any> {
    return this._request("POST", "/v1/manifests", { body });
  }

  /** Get Manifest Request By Id */
  getManifestRequestById(params: { "manifest_request_id": string }): Promise<any> {
    return this._request("GET", "/v1/manifests/requests/{manifest_request_id}", { params });
  }

  /** Get Manifest By Id */
  getManifestById(params: { "manifest_id": string }): Promise<any> {
    return this._request("GET", "/v1/manifests/{manifest_id}", { params });
  }

  /** List Custom Package Types */
  listPackageTypes(): Promise<any> {
    return this._request("GET", "/v1/packages", {});
  }

  /** Create Custom Package Type */
  createPackageType(body: unknown): Promise<any> {
    return this._request("POST", "/v1/packages", { body });
  }

  /** Get Custom Package Type By ID */
  getPackageTypeById(params: { "package_id": string }): Promise<any> {
    return this._request("GET", "/v1/packages/{package_id}", { params });
  }

  /** Update Custom Package Type By ID */
  updatePackageType(body: unknown, params: { "package_id": string }): Promise<any> {
    return this._request("PUT", "/v1/packages/{package_id}", { body, params });
  }

  /** Delete A Custom Package By ID */
  deletePackageType(params: { "package_id": string }): Promise<any> {
    return this._request("DELETE", "/v1/packages/{package_id}", { params });
  }

  /** List Scheduled Pickups */
  listScheduledPickups(params: { "carrier_id"?: string; "warehouse_id"?: string; "created_at_start"?: string; "created_at_end"?: string; "page"?: number; "page_size"?: number }): Promise<any> {
    return this._request("GET", "/v1/pickups", { params });
  }

  /** Schedule a Pickup */
  schedulePickup(body: unknown): Promise<any> {
    return this._request("POST", "/v1/pickups", { body });
  }

  /** Get Pickup By ID */
  getPickupById(params: { "pickup_id": string }): Promise<any> {
    return this._request("GET", "/v1/pickups/{pickup_id}", { params });
  }

  /** Delete a Scheduled Pickup */
  deleteScheduledPickup(params: { "pickup_id": string }): Promise<any> {
    return this._request("DELETE", "/v1/pickups/{pickup_id}", { params });
  }

  /** Get Shipping Rates */
  calculateRates(body: unknown): Promise<any> {
    return this._request("POST", "/v1/rates", { body });
  }

  /** Get Bulk Rates */
  compareBulkRates(body: unknown): Promise<any> {
    return this._request("POST", "/v1/rates/bulk", { body });
  }

  /** Estimate Rates */
  estimateRates(body: unknown): Promise<any> {
    return this._request("POST", "/v1/rates/estimate", { body });
  }

  /** Get Rate By ID */
  getRateById(params: { "rate_id": string }): Promise<any> {
    return this._request("GET", "/v1/rates/{rate_id}", { params });
  }

  /** List Service Points */
  servicePointsList(body: unknown): Promise<any> {
    return this._request("POST", "/v1/service_points/list", { body });
  }

  /** Get Service Point By ID */
  servicePointsGetById(params: { "carrier_code": string; "country_code": string; "service_point_id": string }): Promise<any> {
    return this._request("GET", "/v1/service_points/{carrier_code}/{country_code}/{service_point_id}", { params });
  }

  /** List Shipments */
  listShipments(params: { "shipment_status"?: string; "batch_id"?: string; "tag"?: string; "created_at_start"?: string; "created_at_end"?: string; "modified_at_start"?: string; "modified_at_end"?: string; "page"?: number; "page_size"?: number; "sales_order_id"?: string; "sort_dir"?: string; "sort_by"?: string }): Promise<any> {
    return this._request("GET", "/v1/shipments", { params });
  }

  /** Create Shipments */
  createShipments(body: unknown): Promise<any> {
    return this._request("POST", "/v1/shipments", { body });
  }

  /** Get Shipment By External ID */
  getShipmentByExternalId(params: { "external_shipment_id": string }): Promise<any> {
    return this._request("GET", "/v1/shipments/external_shipment_id/{external_shipment_id}", { params });
  }

  /** Parse shipping info */
  parseShipment(body: unknown): Promise<any> {
    return this._request("PUT", "/v1/shipments/recognize", { body });
  }

  /** Get Shipment By ID */
  getShipmentById(params: { "shipment_id": string }): Promise<any> {
    return this._request("GET", "/v1/shipments/{shipment_id}", { params });
  }

  /** Update Shipment By ID */
  updateShipment(body: unknown, params: { "shipment_id": string }): Promise<any> {
    return this._request("PUT", "/v1/shipments/{shipment_id}", { body, params });
  }

  /** Cancel a Shipment */
  cancelShipments(params: { "shipment_id": string }): Promise<any> {
    return this._request("PUT", "/v1/shipments/{shipment_id}/cancel", { params });
  }

  /** Get Shipment Rates */
  listShipmentRates(params: { "shipment_id": string; "created_at_start"?: string }): Promise<any> {
    return this._request("GET", "/v1/shipments/{shipment_id}/rates", { params });
  }

  /** Add Tag to Shipment */
  tagShipment(params: { "shipment_id": string; "tag_name": string }): Promise<any> {
    return this._request("POST", "/v1/shipments/{shipment_id}/tags/{tag_name}", { params });
  }

  /** Remove Tag from Shipment */
  untagShipment(params: { "shipment_id": string; "tag_name": string }): Promise<any> {
    return this._request("DELETE", "/v1/shipments/{shipment_id}/tags/{tag_name}", { params });
  }

  /** Get Tags */
  listTags(): Promise<any> {
    return this._request("GET", "/v1/tags", {});
  }

  /** Create a New Tag */
  createTag(params: { "tag_name": string }): Promise<any> {
    return this._request("POST", "/v1/tags/{tag_name}", { params });
  }

  /** Delete Tag */
  deleteTag(params: { "tag_name": string }): Promise<any> {
    return this._request("DELETE", "/v1/tags/{tag_name}", { params });
  }

  /** Update Tag Name */
  renameTag(params: { "tag_name": string; "new_tag_name": string }): Promise<any> {
    return this._request("PUT", "/v1/tags/{tag_name}/{new_tag_name}", { params });
  }

  /** Get Ephemeral Token */
  tokensGetEphemeralToken(params: { "redirect"?: string }): Promise<any> {
    return this._request("POST", "/v1/tokens/ephemeral", { params });
  }

  /** Get Tracking Information */
  getTrackingLog(params: { "carrier_code"?: string; "tracking_number"?: string }): Promise<any> {
    return this._request("GET", "/v1/tracking", { params });
  }

  /** Start Tracking a Package */
  startTracking(params: { "carrier_code"?: string; "tracking_number"?: string }): Promise<any> {
    return this._request("POST", "/v1/tracking/start", { params });
  }

  /** Stop Tracking a Package */
  stopTracking(params: { "carrier_code"?: string; "tracking_number"?: string }): Promise<any> {
    return this._request("POST", "/v1/tracking/stop", { params });
  }

  /** List Warehouses */
  listWarehouses(): Promise<any> {
    return this._request("GET", "/v1/warehouses", {});
  }

  /** Create Warehouse */
  createWarehouse(body: unknown): Promise<any> {
    return this._request("POST", "/v1/warehouses", { body });
  }

  /** Get Warehouse By Id */
  getWarehouseById(params: { "warehouse_id": string }): Promise<any> {
    return this._request("GET", "/v1/warehouses/{warehouse_id}", { params });
  }

  /** Update Warehouse By Id */
  updateWarehouse(body: unknown, params: { "warehouse_id": string }): Promise<any> {
    return this._request("PUT", "/v1/warehouses/{warehouse_id}", { body, params });
  }

  /** Delete Warehouse By ID */
  deleteWarehouse(params: { "warehouse_id": string }): Promise<any> {
    return this._request("DELETE", "/v1/warehouses/{warehouse_id}", { params });
  }

  /** Update Warehouse Settings */
  updateWarehouseSettings(body: unknown, params: { "warehouse_id": string }): Promise<any> {
    return this._request("PUT", "/v1/warehouses/{warehouse_id}/settings", { body, params });
  }
}

export default ShipEngineAPI;