@shipengine/js-api 1.0.0-next.4 → 1.0.0

package/insurance/api.d.ts

@@ -1,7 +1,14 @@
 import { AxiosInstance } from "axios";
 import { InsuranceAccount, InsuranceProvider } from "./types";
+/**
+ * # Insurance API module - /v1/insurance
+ */
 export declare class InsuranceAPI {
     private client;
     constructor(client: AxiosInstance);
+    /**
+     * The `get` method retrieves the insurance balance for a given `insuranceProvider`
+     * by ID.
+     */
     get: (insuranceProvider: InsuranceProvider) => Promise<import("axios").AxiosResponse<InsuranceAccount, any>>;
 }

package/labels/api.d.ts

@@ -1,22 +1,106 @@
 import { AxiosInstance } from "axios";
+import { CreationRangeQuery, PageableQuery, PageableResult, SortableQuery } from "../resources";
 import { Label, LabelLayout, VoidRequest } from "./types";
+/**
+ * # Labels API - Create Label Options
+ */
 export interface CreateLabelOptions {
+    /**
+     * `displayScheme` is an optional string to control the display scheme of the label.
+     */
     displayScheme?: string;
+    /**
+     * `labelDownloadType` is an optional string to control the download type of the label.
+     *
+     * e.g. `url` or `inline`
+     */
     labelDownloadType?: string;
+    /**
+     * `labelFormat` is an optional string to control the format of the label.
+     *
+     * e.g. `pdf` or `zpl`
+     */
     labelFormat?: string;
+    /**
+     * `labelLayout` is an optional string to control the layout of the label.
+     *
+     * e.g. `4x6` or `8.5x11`
+     */
     labelLayout?: LabelLayout;
+    /**
+     * `validateAddress` is an optional string to control address validation during
+     * label purchase.
+     */
     validateAddress?: string;
 }
-export interface ListLabelsParams {
+/**
+ * # Labels API - List Labels Params
+ */
+export type ListLabelsParams = {
+    /**
+     * `batchId` is an optional string to retrieve labels within a given batch.
+     */
+    batchId?: string;
+    /**
+     * `carrierId` is an optional string to limit results to only lables for
+     * a specific carrier.
+     */
+    carrierId?: string;
+    /**
+     * `labelStatus` optionally allows filtering results to a specific status.
+     */
+    labelStatus?: Label["status"];
+    /**
+     * `rateId` is an optional string to return labels purchased with a
+     * specific rate.
+     */
+    rateId?: string;
+    /**
+     * `serviceCode` is an optional string to limit results to only labels for
+     * a specific carrier service.
+     */
+    serviceCode?: string;
+    /**
+     * `shipmentId` is an optional string to filter labels by shipment ID. This
+     * is a unique identifier that ShipEngine API associates with your shipment.
+     */
     shipmentId?: string;
-}
+    /** `trackingNumber` is an optional string to retrieve labels for a specific
+     * tracking number
+     */
+    trackingNumber?: string;
+    /** `warehouseId` is an optional string to limit results to only those
+     * originating from a specific warehouse.
+     */
+    warehouseId?: string;
+} & PageableQuery & CreationRangeQuery & SortableQuery<"created_at" | "modified_at" | "order_date">;
+export type ListLabelsResult = {
+    labels: Label[];
+} & PageableResult;
+/**
+ * # Labels API module - /v1/labels
+ */
 export declare class LabelsAPI {
     private client;
     constructor(client: AxiosInstance);
+    /**
+     * The `get` method retrieves a specific label by `labelId`.
+     */
     get: (labelId: string) => Promise<import("axios").AxiosResponse<Label, any>>;
-    list: (params?: ListLabelsParams) => Promise<import("axios").AxiosResponse<{
-        labels: Label[];
-    }, any>>;
+    /**
+     * The `list` method retrieves a list of labels created by a given user.
+     */
+    list: (params?: ListLabelsParams) => Promise<import("axios").AxiosResponse<ListLabelsResult, any>>;
+    /**
+     * The `createByRateId` allows you to create a shipping label by using a `rateId`
+     * which is a unique identifier tied to a specific rate.
+     *
+     * This helps ensure that when a user is rate shopping, they can purchase a
+     * label for the price they were initially rated.
+     */
     createByRateId: (rateId: string, options: CreateLabelOptions) => Promise<import("axios").AxiosResponse<Label, any>>;
+    /**
+     * The `void` method allows a user to void a label by `labelId`.
+     */
     void: (labelId: string) => Promise<import("axios").AxiosResponse<VoidRequest, any>>;
 }

package/order-sources/api.d.ts

@@ -1,11 +1,28 @@
 import { AxiosInstance } from "axios";
 import { OrderSource } from "./types";
+/**
+ * # Order Sources API module - /v-beta/order_sources
+ */
 export declare class OrderSourcesAPI {
     private client;
     constructor(client: AxiosInstance);
+    /**
+     * The `list` method retrieves a list of connected order sources for a given user.
+     */
     list: () => Promise<import("axios").AxiosResponse<{
         orderSources: OrderSource[];
     }, any>>;
+    /**
+     * The `get` method retrieves a specific order source by `orderSourceId`.
+     */
     get: (orderSourceId: string) => Promise<import("axios").AxiosResponse<OrderSource, any>>;
+    /**
+     * The `refresh` method refreshes a specific order source by `orderSourceId`.
+     * This will pull in any `new orders` since the last order import.
+     */
     refresh: (orderSourceId: string) => Promise<import("axios").AxiosResponse<OrderSource, any>>;
+    /**
+     * The `deactivate` method remove a specific connected order source by `orderSourceId`.
+     */
+    deactivate: (orderSourceId: string) => Promise<import("axios").AxiosResponse<any, any>>;
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@shipengine/js-api",
-  "version": "1.0.0-next.4",
+  "version": "1.0.0",
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {
     ".": {
       "import": "./index.mjs",
-      "require": "./index.js"
+      "require": "./index.js",
+      "types": "./index.d.ts"
     }
   },
   "typedoc": {
@@ -14,5 +15,8 @@
     "entryPoint": "./src/index.ts",
     "readmeFile": "./README.md",
     "tsconfig": "./tsconfig.lib.json"
+  },
+  "peerDependencies": {
+    "axios": "^0.26.1"
   }
 }

package/rate-cards/api.d.ts

@@ -0,0 +1,44 @@
+import { AxiosInstance } from "axios";
+import { RateCard, RateCardInput } from "./types";
+/**
+ * # Rate Cards API module - /v1/rate_cards
+ */
+export declare class RateCardsAPI {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * The `list` method retrieves a list of rate cards for a given list of carrier ID's.
+     */
+    list: (carrierIds: string[]) => Promise<import("axios").AxiosResponse<{
+        rateCards: RateCard[];
+    }, any>>;
+    /**
+     * The `get` method retrieves a specific rate card by `rateCardId`.
+     */
+    get: (rateCardId: string) => Promise<import("axios").AxiosResponse<RateCard, any>>;
+    /**
+     * The `create` method creates a new rate card for a given user.
+     */
+    create: (rateCardInput: RateCardInput) => Promise<import("axios").AxiosResponse<RateCard, any>>;
+    /**
+     * The `update` method updates a specific rate card by `rateCardId` with a new
+     * `RateCard`.
+     */
+    update: (rateCard: RateCard) => Promise<import("axios").AxiosResponse<RateCard, any>>;
+    /**
+     * The `download` method allows for downloading a given rate card by `rateCardId`.
+     */
+    download: (rateCardId: string) => Promise<import("axios").AxiosResponse<Blob, any>>;
+    /**
+     * The `upload` method allows for uploading a given rate card as a spreadsheet file.
+     */
+    upload: (rateCardId: string, file: File) => Promise<import("axios").AxiosResponse<RateCard, any>>;
+    /**
+     * The `publish` method allows for publishing a given rate card by `rateCardId`.
+     */
+    publish: (rateCardId: string) => Promise<import("axios").AxiosResponse<any, any>>;
+    /**
+     * @description https://auctane.atlassian.net/wiki/spaces/TE/pages/3837431603/Inc+1+3.+Rate+Card+Details#Delete-Rate-Card
+     */
+    delete: (rateCardId: string) => Promise<import("axios").AxiosResponse<any, any>>;
+}

package/rate-cards/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./api";
+export * from "./types";

package/rate-cards/types.d.ts

@@ -0,0 +1,88 @@
+import { CarrierService, PackageRatingType } from "../carriers";
+import { Currency } from "../payments";
+import { ISOString } from "../resources";
+import { WeightBandIncremental, WeightBandMinMax } from "../weight-band";
+import { Zone } from "../zones";
+/**
+ * @category Entities
+ */
+export interface ShipFromLocation {
+    countryCode: string;
+    postalCode?: string;
+}
+/**
+ * @category Entities
+ */
+export type SurchargeType = "percentage" | "fixed";
+/**
+ * @category Entities
+ */
+export interface RateSurcharge {
+    name: string;
+    type: SurchargeType;
+    value: number;
+}
+/**
+ * @category Entities
+ */
+export type RateService = Pick<CarrierService, "serviceCode" | "name"> & {
+    surcharges?: RateSurcharge[];
+    zones?: RateZone[];
+};
+/**
+ * @category Entities
+ */
+export type RateZone = Zone & {
+    packageTypes?: RatePackageType[];
+    surcharges?: RateSurcharge[];
+};
+/**
+ * @category Entities
+ */
+export type RateWeightBandMinMax = WeightBandMinMax & {
+    rate?: number;
+};
+/**
+ * @category Entities
+ */
+export type RateWeightBandIncremental = WeightBandIncremental & {
+    rate?: number;
+};
+/**
+ * @category Entities
+ */
+export type RatePackageType = Pick<PackageRatingType, "packageId" | "name" | "description" | "dimensions" | "maxWeight" | "carrierPackageTypeCode"> & {
+    weightBands?: {
+        incrementalBands?: RateWeightBandIncremental[];
+        minMaxBands?: RateWeightBandMinMax[];
+    };
+};
+/**
+ * @category Entities
+ */
+export declare enum RateCardStatus {
+    DRAFT = "Draft",
+    DELETED = "Deleted",
+    PUBLISHED = "Published"
+}
+/**
+ * @category Entities
+ */
+export interface RateCard {
+    carrierId: string;
+    createdAt?: ISOString;
+    currency?: Currency;
+    endDate?: ISOString;
+    id: string;
+    name: string;
+    publishedAt?: ISOString;
+    services?: RateService[];
+    shipFrom?: ShipFromLocation;
+    startDate?: ISOString;
+    status?: RateCardStatus;
+    surcharges?: RateSurcharge[];
+}
+/**
+ * @category Entities
+ */
+export type RateCardInput = Partial<RateCard> & Pick<RateCard, "carrierId" | "name">;

package/rates/api.d.ts

@@ -1,16 +1,42 @@
 import { AxiosInstance } from "axios";
 import { Currency } from "../payments";
 import { RateResponse } from "./types";
+/**
+ * # Rates API - Calculate Rates Options
+ */
 export interface CalculateRatesOptions {
+    /**
+     * `calculateTaxAmount` is an optional boolean that indicates rates returned
+     * should include the tax amount.
+     */
     calculateTaxAmount?: boolean;
+    /**
+     * `carrierIds` is an array of carrier IDs to filter rates by.
+     */
     carrierIds: string[];
+    /**
+     * `packageTypes` is an optional array of package types to filter rates by.
+     */
     packageTypes?: string[];
+    /**
+     * `preferredCurrency` is an optional indicator of the currency to return rates in.
+     */
     preferredCurrency?: Currency;
+    /**
+     * `serviceCodes` is an optional array of specific carrier service codes to filter rates by.
+     */
     serviceCodes?: string[];
 }
+/**
+ * # Rates API module - /v1/rates
+ */
 export declare class RatesAPI {
     private client;
     constructor(client: AxiosInstance);
+    /**
+     * The `calculate` method calculates rates for a shipment by shipment ID based
+     * on the shipment's options.
+     */
     calculateByShipmentId: (shipmentId: string, options: CalculateRatesOptions) => Promise<import("axios").AxiosResponse<Omit<import("..").Shipment, "items"> & {
         items: import("../sales-order-shipments").SalesOrderShipmentItem[];
         salesOrderIds: string[];

package/resources/types.d.ts

@@ -7,6 +7,9 @@ export interface Download {
     png: string;
     zpl: string;
 }
+export type GenericObject = {
+    [name: string]: any;
+};
 /**
  * @category Entities
  */
@@ -14,3 +17,40 @@ export interface LinkedResource {
     href: string;
     type: string;
 }
+export type ISOString = string;
+export type PageableQuery = {
+    page?: number;
+    pageSize?: number;
+};
+export type PageableResult = {
+    links: {
+        first: LinkedResource;
+        last: LinkedResource;
+        next: LinkedResource;
+        prev: LinkedResource;
+    };
+    page: number;
+    pages: number;
+    total: number;
+};
+export type BatchableQuery = {
+    batchId?: string;
+};
+export type TaggableQuery = {
+    tag?: string;
+};
+export type CreationRangeQuery = {
+    createdAtEnd?: ISOString;
+    createdAtStart?: ISOString;
+};
+export type ModificationRangeQuery = {
+    modifiedAtEnd?: ISOString;
+    modifiedAtStart?: ISOString;
+};
+export type SortableQuery<TSortKeys = "created_at" | "modified_at"> = {
+    sortBy?: TSortKeys;
+    sortDir?: "asc" | "desc";
+};
+export type LocaleBasedQuery = {
+    locale?: string;
+};

package/sales-order-shipments/api.d.ts

@@ -1,15 +1,104 @@
 import { AxiosInstance } from "axios";
+import { CreationRangeQuery, ISOString, ModificationRangeQuery, PageableQuery, PageableResult, SortableQuery } from "../resources";
+import { FulfillmentStatus, PaymentStatus } from "../sales-orders";
 import { SalesOrderShipment } from "./types";
-export interface ListSalesOrderShipmentsParams {
+/**
+ *
+ */
+export type ListSalesOrderShipmentsParams = {
+    /**
+     * `cancelled` is an optional boolean indicating if cancelled shipments
+     * should be included in the response.
+     */
+    cancelled?: boolean;
+    /**
+     * `externalOrderId` is an optional unique ID that can be set by the user to
+     * associate shipments with an external system.
+     */
+    externalOrderId?: string;
+    /**
+     * `externalOrderNumber` is an optional unique ID that can be set by the
+     * user to associate orders with an external system.
+     */
+    externalOrderNumber?: string;
+    /**
+     * `fulfillmentStatus` is an optional string that indicates the fulfillment
+     * status of the shipments to be returned.
+     */
+    fulfillmentStatus?: FulfillmentStatus;
+    /**
+     * `orderDateEnd` is an optional ISO 8601 string that indicates the end of the
+     * date range to query orders from.
+     */
+    orderDateEnd?: ISOString;
+    /**
+     * `orderDateStart` is an optional ISO 8601 string that indicates the start of
+     * the date range to query orders from.
+     */
+    orderDateStart?: ISOString;
+    /**
+     * `orderSourceId` is an optional string that indicates the order source ID
+     * to query orders from.
+     */
+    orderSourceId?: string;
+    /**
+     * `paymentStatus` is an optional string that indicates the payment status of
+     * the shipments to be returned.
+     */
+    paymentStatus?: PaymentStatus;
+    /**
+     * `salesOrderIds` is an optional array of sales order IDs to be used when
+     * querying sales orders.
+     */
     salesOrderIds?: string[];
-}
+    /**
+     * `shipmentIds` is an optional array of shipment IDs to fetch.
+     */
+    shipmentIds?: string[];
+} & PageableQuery & CreationRangeQuery & ModificationRangeQuery & SortableQuery<"created_at" | "modified_at" | "order_date">;
+/**
+ * # Sales Order Shipments - List Sales Order Shipments Body
+ */
+export type ListSalesOrderShipmentBody = {
+    /**
+     * `salesOrderIds` is an array of sales order IDs to be used when listing sales
+     * orders.
+     */
+    salesOrderIds?: string[];
+    /**
+     * `shipments` is an array of shipments associated with the sales orders.
+     */
+    shipments?: SalesOrderShipment[];
+};
+/**
+ * # Sales Order Shipments - List Sales Order Shipments Result
+ */
+export type ListSalesOrderShipmentsResult = {
+    /**
+     * `shipments` is an array of sales order shipments.
+     */
+    shipments: SalesOrderShipment[];
+} & PageableResult;
+/**
+ * # Sales Order Shipments API module - /v-beta/shipments
+ */
 export declare class SalesOrderShipmentsAPI {
     private client;
     constructor(client: AxiosInstance);
-    list: (params?: ListSalesOrderShipmentsParams) => Promise<import("axios").AxiosResponse<{
-        shipments: SalesOrderShipment[];
-    }, any>>;
+    /**
+     * The `list` method retrieves a list of sales order shipments for a given user.
+     */
+    list: (body?: ListSalesOrderShipmentBody | undefined, params?: ListSalesOrderShipmentsParams) => Promise<import("axios").AxiosResponse<ListSalesOrderShipmentsResult, any>>;
+    /**
+     * The `get` method retrieves a specific sales order shipment by `shipmentId`.
+     */
     get: (shipmentId: string) => Promise<import("axios").AxiosResponse<SalesOrderShipment, any>>;
+    /**
+     * The `create` method creates a new shipment for a sales order.
+     */
     create: (salesOrderId: string, shipment: Partial<SalesOrderShipment>) => Promise<import("axios").AxiosResponse<SalesOrderShipment, any>>;
+    /**
+     * The `update` method updates a specific sales order shipment by `shipmentId`.
+     */
     update: (shipmentId: string, shipment: Partial<SalesOrderShipment>) => Promise<import("axios").AxiosResponse<SalesOrderShipment, any>>;
 }

package/sales-orders/api.d.ts

@@ -1,15 +1,40 @@
 import { AxiosInstance } from "axios";
 import { SalesOrder, SalesOrderTracking } from "./types";
+/**
+ * # Sales Orders - List Sales Orders Params
+ */
 export interface ListSalesOrdersParams {
+    /**
+     * `externalOrderId` is an optional unique ID that can be set by the user to
+     * associate shipments with an external system.
+     */
     externalOrderId?: string;
+    /**
+     * `externalOrderNumber` is an optional unique identifier that can be set by
+     * the user to associate shipments with an external order system.
+     */
     externalOrderNumber?: string;
 }
+/**
+ * # Sales Orders API module - /v-beta/sales_orders
+ */
 export declare class SalesOrdersAPI {
     private client;
     constructor(client: AxiosInstance);
+    /**
+     * The `list` method retrieves a list of sales orders.
+     */
     list: (params?: ListSalesOrdersParams) => Promise<import("axios").AxiosResponse<{
         salesOrders: SalesOrder[];
     }, any>>;
+    /**
+     * The `get` method retrieves a specific sales order by `salesOrderId`.
+     */
     get: (salesOrderId: string) => Promise<import("axios").AxiosResponse<SalesOrder, any>>;
+    /**
+     * The `notifyShipped` method notifies order source that the order has been
+     * shipped. Typically, the order source will then notify the user based on
+     * this update from ShipEngine API.
+     */
     notifyShipped: (salesOrderId: string, tracking: SalesOrderTracking) => Promise<import("axios").AxiosResponse<SalesOrder, any>>;
 }

package/shipments/api.d.ts

@@ -0,0 +1,72 @@
+import { AxiosInstance } from "axios";
+import { BatchableQuery, CreationRangeQuery, ModificationRangeQuery, PageableQuery, PageableResult, SortableQuery, TaggableQuery } from "../resources";
+import { Shipment, ShipmentRateResponse, ShipmentStatus } from "./types";
+/**
+ * # Shipments - Get Shipment Rates Options
+ */
+export type GetShipmentRatesOptions = {
+    /**
+     * Date to filter rates by (they must be more recent than this date if passed)
+     * @example "2019-03-12T19:24:13.657Z"
+     */
+    createdAtStart?: string;
+    /**
+     * `shipmentId` is the unique identifier of the shipment to retrieve.
+     */
+    shipmentId: string;
+};
+export type ListShipmentOptions = {
+    /**
+     * `salesOrderIds` is an array of sales order IDs to be used when listing sales
+     * orders.
+     */
+    salesOrderId?: string;
+    /**
+     * `shipmentStatus` is the current fulfillment status of the shipment.
+     */
+    shipmentStatus?: ShipmentStatus;
+} & BatchableQuery & PageableQuery & CreationRangeQuery & ModificationRangeQuery & SortableQuery & TaggableQuery;
+/**
+ * # Shipments - List Shipments Result
+ */
+export type ListShipmentResult = {
+    /**
+     * `shipments` is an array of shipments to be returned.
+     */
+    shipments: Shipment[];
+} & PageableResult;
+/**
+ * # Shipments - Create Shipments Result
+ */
+export type CreateShipmentResult = {
+    /**
+     * `hasErrors` is a boolean that indicates if any errors occurred during the
+     * creation of the shipments.
+     */
+    hasErrors: boolean;
+    /**
+     * `shipments` is an array of shipments that were created.
+     */
+    shipments: Shipment[];
+};
+/**
+ * # Shipments API module - /v1/shipments
+ */
+export declare class ShipmentsAPI {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * The `getShipmentRates` method retrieves rates for a given shipment by
+     * shipment ID.
+     */
+    getShipmentRates: ({ shipmentId, createdAtStart }: GetShipmentRatesOptions) => Promise<import("axios").AxiosResponse<ShipmentRateResponse, any>>;
+    /**
+     * The `list` method retrieves a list of shipments for a given user.
+     */
+    list: (options?: ListShipmentOptions) => Promise<import("axios").AxiosResponse<ListShipmentResult, any>>;
+    /**
+     * The `create` method allows for creating shipments based on a list of shipment
+     * items passed into this method.
+     */
+    create: (...shipments: Partial<Omit<Shipment, "items">>[]) => Promise<import("axios").AxiosResponse<CreateShipmentResult, any>>;
+}

package/shipments/index.d.ts

@@ -1 +1,2 @@
 export * from "./types";
+export * from "./api";