shipbob-node-sdk 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -26,7 +26,21 @@ export type DataResponse<T> = ({
      */
     data: object | string;
 }) & {
+    headers: Record<string, string>;
     statusCode: number;
+    rateLimit: {
+        /**
+         * There are 150 calls in a sliding window of 1 minute.
+         *
+         * Retrieved from x-remaining-calls header in response.
+         * null when not found.
+         */
+        remainingCalls: Nullable<number>;
+        /**
+         * Seconds remaining in sliding window once rate limit has been exhausted.
+         */
+        retryAfter: Nullable<number>;
+    };
 };
 export type ChannelsResponse = {
     id: number;
@@ -72,10 +86,231 @@ export type AddProductResponse = {
     id: number;
     reference_id: string;
 };
-export type GetProductResult = {
+/**
+ * This is missing practically all fields of actual result.
+ */
+export type GetProduct1_0Result = {
     id: number;
     reference_id: string;
 };
+export type ActionName = 'Dispose' | 'Restock' | 'Quarantine';
+export type ProductType = 'Regular' | 'Bundle';
+type GetProduct2_0Variant = {
+    /**
+     * The expected barcode to be found on the item and checked during the pick process
+     */
+    barcode: string;
+    barcode_sticker_url: Nullable<string>;
+    channel_metadata: unknown[];
+    reviews_pending: unknown[];
+    associated_bundles: unknown[];
+    bundle_definition: unknown[];
+    created_on: string;
+    customs: {
+        /**
+         * The customs code (6 digit)
+         */
+        hs_tariff_code: string;
+        /**
+         * 2 character country code
+         */
+        country_code_of_origin: string;
+        /**
+         * Value of object for customs (in USD)
+         */
+        value: Nullable<string>;
+        currency: 'USD';
+        /**
+         * Description of product for customs purposes
+         */
+        description: string;
+        is321_eligible: boolean;
+    };
+    dimension: {
+        length: number;
+        width: number;
+        height: number;
+        /**
+         * "inch"
+         */
+        unit: string;
+        is_locked: boolean;
+        /**
+         * ie: "UserEntry"
+         */
+        source: string;
+    };
+    fulfillment_settings: {
+        /**
+         * If the product requires a prop65 label in the box
+         */
+        requires_prop65: false;
+        serial_scan: {
+            /**
+             * Indicates if a Serial Scan is required during the pack process.
+             * Note: Serial scan requires either a prefix or a suffix to be defined
+             */
+            is_enabled: false;
+            /**
+             * The prefix expected on the serial number
+             */
+            prefix: string;
+            /**
+             * The suffix expected on the serial number
+             */
+            suffix: string;
+            /**
+             * The exact number of characters expected in the serial number
+             */
+            exact_character_length: Nullable<number>;
+        };
+        /**
+         * If the product needs to classified as a hazmat product with the shipping carrier
+         */
+        dangerous_goods: false;
+        /**
+         * URL of the Safety Data Sheet for this product.
+         * Note: should be populated by ShipBob system via the UI, should not reference a URL outside of the ShipBob domain
+         */
+        msds_url: string;
+        /**
+         * If the product should be picked as an entire case
+         */
+        is_case_pick: boolean;
+        /**
+         * Is Bound Printed Matter, must be set by the ShipBob internal team
+         */
+        is_bpm_parcel: boolean;
+    };
+    /**
+     * Global Trade Item Number
+     */
+    gtin: string;
+    /**
+     * Variant Id (used to alter product lot, packaging, etc.)
+     */
+    id: number;
+    inventory: {
+        inventory_id: number;
+        on_hand_qty: number;
+    };
+    is_digital: boolean;
+    lot_information: {
+        /**
+         * If the product should use lot date based picking
+         */
+        is_lot: boolean;
+        minimum_shelf_life_days: Nullable<number>;
+    };
+    /**
+     * Name of the Variant (should match the Product name if a non-varying product)
+     */
+    name: string;
+    /**
+     * PDf has wrong field: The specific material to package the product in (box, poly mailer, bubble mailer, etc_
+     */
+    packaging_material_type: {
+        id: number;
+        /**
+         * Not sure what else can be here
+         */
+        name: 'Box';
+    };
+    /**
+     * PDF has wrong field. int The id of the packaging_requirement (No requirement, fragile, ship in own container, etc)
+     */
+    packaging_requirement: {
+        id: number;
+        name: 'NoRequirements' | 'Fragile';
+    };
+    return_preferences: {
+        /**
+         * Restock (1) Quarantine (2) Dispose (3)
+         */
+        primary_action: Nullable<{
+            id: number;
+            name: ActionName;
+        }>;
+        /**
+         * Restock (1) Quarantine (2) Dispose (3)
+         */
+        backup_action: Nullable<{
+            id: number;
+            name: ActionName;
+        }>;
+        /**
+         * Instructions for inspecting returns
+         */
+        instructions: Nullable<string>;
+        return_to_sender_primary_action: Nullable<{
+            id: number;
+            name: ActionName;
+        }>;
+        return_to_sender_backup_action: Nullable<{
+            id: number;
+            name: ActionName;
+        }>;
+    };
+    /**
+     * The SKU of the product. This is a required field and must be unique.
+     */
+    sku: string;
+    /**
+     * PDF is incorrect - it describes in int.  Active (1) or Inactive (2)
+     */
+    status: 'Active' | 'Inactive';
+    /**
+     * Universal Product Code
+     */
+    upc: string;
+    is_image_uploaded: false;
+    updated_on: string;
+    weight: {
+        weight: number;
+        /**
+         * ie: "oz"
+         */
+        unit: string;
+    };
+    additional_hazmat_attributes: Nullable<unknown>;
+    merge_children: [];
+};
+/**
+ * This is just some guessing based on found responses
+ */
+export type GetProduct2_0Response = {
+    /**
+     * Product Id
+     */
+    id: number;
+    /**
+     * Product Name
+     */
+    name: string;
+    type: ProductType;
+    category: Nullable<unknown>;
+    sub_category: Nullable<unknown>;
+    user_id: number;
+    created_on: string;
+    updated_on: string;
+    /**
+     * null | ?
+     */
+    taxonomy: null;
+    variants: GetProduct2_0Variant[];
+};
+export type GetProductExperimentalVariant = Omit<GetProduct2_0Variant, 'barcode'> & {
+    barcodes: {
+        value: string;
+        sticker_url: Nullable<string>;
+    }[];
+};
+/**
+ * Just the barcode -> barcodes on the variant seems like the only difference so far.
+ */
+export type GetProductExperimentalResponse = Omit<GetProduct2_0Response, 'variants'> & {
+    variants: GetProductExperimentalVariant[];
+};
 export type OrderType = 'DTC' | 'DropShip' | 'B2B' | 'Transportation';
 export type AnyProduct = ({
     /**
@@ -314,6 +549,39 @@ export type PlaceOrderRequest = {
      */
     type: OrderType;
 };
+export type ShippingMethod = {
+    /**
+     * Unique id for shipping method
+     */
+    id: number;
+    /**
+     * Indicates if the shipping method is active
+     */
+    active: boolean;
+    /**
+     * Indicates the shipping method is a ShipBob default shipping method.
+     */
+    default: boolean;
+    /**
+     * Name of the ship method as selected by the merchant and saved in ShipBob’s database (i.e. “ground”).
+     *
+     * Corresponds to the shipping_method field in the Orders API.
+     */
+    name: string;
+    /**
+     * ShipBob.Orders.Presentation.ViewModels.ServiceLevelDetailViewModel)
+     */
+    service_level: {
+        /**
+         * Unique id for the service level
+         */
+        id: number;
+        /**
+         * The name or title of the service level
+         */
+        name: string;
+    };
+};
 export type Webhook = {
     id: number;
     /**
@@ -397,7 +665,8 @@ export type WarehouseReceivingOrderRequest = {
              */
             inventory_id: number;
             /**
-             * Lot number of the items in the box
+             * Lot number of the items in the box.  Must be supplied for products that have lot set, otherwise will be:
+             * 422 status code "Wrong Lot Information Provided For Inventory IDs: 8619859,8619860, etc."
              */
             lot_number?: Nullable<string>;
             /**
@@ -409,6 +678,8 @@ export type WarehouseReceivingOrderRequest = {
     /**
      * Expected arrival date of all the box shipments in this receiving order
      * ie: ISO date "2019-08-24T14:15:22Z"
+     *
+     * NOTE: Must be in the future or it will generate a 422 error.
      */
     expected_arrival_date: string;
     /**
@@ -627,6 +898,265 @@ export type WarehouseReceivingOrderBoxesResponse = {
         lot_date: Nullable<string>;
     }[];
 }[];
+export declare enum PackagingRequirement {
+    'No Requirements' = 1,
+    Fragile = 2,
+    'Is Foldable' = 3,
+    'Is Media (Media mail)' = 4,
+    'Is Book' = 5,
+    'Is Poster' = 6,
+    'Is Apparel' = 7,
+    'Is Packaging Material (for custom boxes, marketing inserts, etc)' = 8,
+    'Ship In Own Container' = 9
+}
+export declare enum PackagingMaterial {
+    'Box' = 1,
+    'Bubble Mailer' = 2,
+    'Poly Mailer' = 3,
+    'Poster Tube' = 5,
+    'Custom Box' = 6,
+    'Bookfold' = 7,
+    'Ship In Own Container' = 8,
+    'Custom Bubble Mailer' = 9,
+    'Custom Poly Mailer' = 10
+}
+/**
+ * Restock (1)
+ * Quarantine (2)
+ * Dispose (3)
+ */
+export declare enum ReturnAction {
+    /**
+     * Restock (1)
+     */
+    Restock = 1,
+    /**
+     * Quarantine (2)
+     */
+    Quarantine = 2,
+    /**
+     * Dispose (3)
+     */
+    Dispose = 3
+}
+export type VariantRequestProductExperimental = Omit<VariantRequestProduct2_0, 'barcode'> & {
+    barcodes: {
+        value: string;
+        sticker_url: Nullable<string>;
+    }[];
+};
+export type VariantRequestProduct2_0 = {
+    /**
+     * Required for updates
+     */
+    id?: number;
+    name?: string;
+    sku?: string;
+    /**
+     * will serialize as a number
+     */
+    packaging_requirement_id?: PackagingRequirement;
+    /**
+     * will serialize as a number
+     */
+    packaging_material_type_id?: PackagingMaterial;
+    barcode?: string;
+    upc?: string;
+    gtin?: string;
+    customs?: {
+        /**
+         * 2 character country code
+         */
+        country_code_of_origin: 'US';
+        /**
+         * The customs code (6 digit)
+         * ie: “6103.22”
+         */
+        hs_tariff_code: string;
+        /**
+         * Value of object for customs (in USD)
+         * ie: “15”
+         */
+        value: string;
+        /**
+         * Description of product for customs purposes
+         */
+        description: string;
+    };
+    /**
+     * Not sure if these can be partially supplied.
+     */
+    return_preferences?: {
+        primary_action_id: Nullable<ReturnAction>;
+        backup_action_id: null;
+        /**
+         * Cannot be set when "primary_action_id" has certain values (ie: Quarantine)
+         * error: variants.return_preferences.instructions cannot be set for the selected primary action
+         */
+        instructions: Nullable<string>;
+        return_to_sender_primary_action_id: Nullable<ReturnAction>;
+        return_to_sender_backup_action_id: Nullable<ReturnAction>;
+    };
+    lot_information: {
+        /**
+         * If the product should use lot date based picking
+         */
+        is_lot: boolean;
+        minimum_shelf_life_days: Nullable<number>;
+    };
+};
+export type GetProductQueryStrings = {
+    Page: number;
+    Limit: number;
+    /**
+     * Regular product (1) or Bundle (2)
+     */
+    productTypeId: 1 | 2;
+    /**
+     * Active (1) or Inactive (2)
+     */
+    variantStatus: 1 | 2;
+    /**
+     * True -> at least one variant is digital
+     * False -> at least one variant is not-digital
+     */
+    hasDigitalVariants: boolean;
+    /**
+     * Search by one or more Product Ids (comma separated) to return multiple products
+     */
+    Ids: string;
+    /**
+     * Search by one or more Variant Ids (comma separated) to return multiple products
+     */
+    VariantIds: string;
+    /**
+     * Search by product barcode
+     */
+    barcode: string;
+    /**
+     * Search by an exact sku
+     */
+    sku: string;
+    /**
+     * Search for products that vary or non-varying products
+     */
+    hasVariants: boolean;
+    /**
+     * Search by one or more InventoryIds (comma separated) to return multiple barcodes
+     */
+    InventoryId: string;
+    /**
+     * Search by Variant Name.
+     * NOTE: Query parameters should be URL encoded such as "Green%20Shirt"
+     */
+    Name: string;
+    /**
+     * Search by matching Taxonomy (category) of the product (comma separated)
+     */
+    TaxonomyIds: string;
+};
+export type ExperimentalPagedResult<T> = {
+    /**
+     * Will be null when there are no items
+     */
+    first: Nullable<string>;
+    next: Nullable<string>;
+    items: T[];
+    prev: Nullable<string>;
+    /**
+     * Will be null when there are no items.
+     */
+    last: Nullable<string>;
+};
+export type GetInventory1_0Result = {
+    id: number;
+    name: string;
+    is_digital: boolean;
+    is_case_pick: boolean;
+    is_lot: boolean;
+    dimensions: {
+        weight: number;
+        length: number;
+        width: number;
+        depth: number;
+    };
+    /**
+     * Total fulfillable quantity of this inventory item
+     */
+    total_fulfillable_quantity: number;
+    /**
+     * Total onhand quantity of this inventory item
+     */
+    total_onhand_quantity: number;
+    /**
+     * Total committed quantity of this inventory item
+     */
+    total_committed_quantity: number;
+    /**
+     * Total quantity that can be sold without overselling the inventory item. This is calculated by subtracting the total exception quantity from the fulfillable quantity.
+     */
+    total_sellable_quantity: number;
+    /**
+     * Total quantity in unreceived receiving orders for this inventory item
+     */
+    total_awaiting_quantity: number;
+    /**
+     * The total quantity of all items that are contained within orders that are in exception/out of stock status. Out of stock orders have not been processed and therefore do not have lot or fulfillment centers assigned.
+     */
+    total_exception_quantity: number;
+    /**
+     * The total quantity of all items that are in the process of internal transit between ShipBob fulfillment centers. These items are not pickable or fulfillable until they have been received and moved to the "On Hand" quantity of the destination FC. Internal transit quantities for each FC represent the incoming transfer stock for that specific location.
+     */
+    total_internal_transfer_quantity: number;
+    /**
+     * The amount of the item you need to send to ShipBob to fulfill all exception orders containing the item. This is the exception_quantity less the fulfillable_quantity of the item.
+     */
+    total_backordered_quantity: number;
+    /**
+     * Whether the inventory is active or not
+     */
+    is_active: boolean;
+    /**
+     * Fulfillable quantity of this inventory item broken down by fulfillment center location
+     */
+    fulfillable_quantity_by_fulfillment_center: {
+        id: number;
+        name: string;
+        fulfillable_quantity: number;
+        onhand_quantity: number;
+        committed_quantity: number;
+        awaiting_quantity: number;
+        internal_transfer_quantity: number;
+    }[];
+    /**
+     * Fulfillable quantity of this inventory item broken down by lot
+     */
+    fulfillable_quantity_by_lot: {
+        lot_number: string;
+        /**
+         * ie: "2019-08-24T14:15:22Z"
+         */
+        expiration_date: string;
+        fulfillable_quantity: number;
+        onhand_quantity: number;
+        committed_quantity: number;
+        awaiting_quantity: number;
+        internal_transfer_quantity: number;
+        fulfillable_quantity_by_fulfillment_center: {
+            id: number;
+            name: string;
+            fulfillable_quantity: number;
+            onhand_quantity: number;
+            committed_quantity: number;
+            awaiting_quantity: number;
+            internal_transfer_quantity: number;
+        }[];
+    }[];
+    /**
+     * ie: "None" "Fragile" "Foldable" "Stackable" "Book" "CustomPackaging" "CustomDunnage" "MarketingInsert" or "Poster"
+     */
+    packaging_attribute: 'None' | 'Fragile' | 'Foldable' | 'Stackable' | 'Book' | 'CustomPackaging' | 'CustomDunnage' | 'MarketingInsert' | 'Poster';
+};
 /**
  * Create API with PAT (personal access token) - defaults to sandbox endpoints and "SMA" channel.
  *
@@ -637,11 +1167,18 @@ export type WarehouseReceivingOrderBoxesResponse = {
  * @param personalAccessToken passing *undefined* or empty string has a guar clause that will throw
  * @param apiBaseUrl
  * @param channelApplicationName
+ * @param options
  * @returns
  */
-export declare const createShipBobApi: (personalAccessToken: string | undefined, apiBaseUrl?: string, channelApplicationName?: string) => Promise<{
-    getProductById: (productId: number) => Promise<DataResponse<GetProductResult>>;
-    getProducts: (query: Partial<{
+export declare const createShipBobApi: (personalAccessToken: string | undefined, apiBaseUrl?: string, channelApplicationName?: string, options?: {
+    logTraffic: boolean;
+}) => Promise<{
+    /**
+     * You would need a product id on your side.  Not sure how useful this is in all practicality unless
+     * you maintain the association on your side.
+     */
+    getProductById: (productId: number) => Promise<DataResponse<GetProduct1_0Result>>;
+    getProducts1_0: (query: Partial<{
         ReferenceIds: string;
         Page: number;
         Limit: number;
@@ -649,13 +1186,56 @@ export declare const createShipBobApi: (personalAccessToken: string | undefined,
         Search: string;
         ActiveStatus: "Any" | "Active" | "Inactive";
         BundleStatus: "Any" | "Bundle" | "NotBundle";
-    }>) => Promise<DataResponse<GetProductResult[]>>;
-    addProduct: (product: {
+    }>) => Promise<DataResponse<GetProduct1_0Result[]>>;
+    /**
+     * NOTE: you need to use the headers (part of this client response) to page the results.
+     * page-number='1'
+     * page-size='50'
+     * total-count='1'
+     * total-pages='1'
+     *
+     * NOTE: we can probably pass more than "variants" prop.  We could on the /1.0/product endpoint
+     * NOTE: This PATCH functionality will be available in the next version available in ShipBob next large release January 2025, it may require extra scope.
+     */
+    updateProduct2_0: (productId: number, variants: VariantRequestProduct2_0[]) => Promise<DataResponse<AddProductResponse>>;
+    /**
+     * Unsure how this is different from /2.0/product except for "barcode" -> "barcodes"
+     */
+    updateProductExperimental: (productId: number, variants: VariantRequestProductExperimental[]) => Promise<DataResponse<AddProductResponse>>;
+    /**
+     * Not supported here, but:
+     * Some search filters allow for operators (equals, not equals, starts with, ends with, contains, etc) to get more exact values. When filtering with an operator, the query string will look like the below:
+     * Example: /product?{filter}={operator}:{value}
+     * Example: /product?sku=any:shirt-a,shirt-b,shirt-c Find products that match any of these SKUs
+     * Example: /product?onHandQuantity=gt:0 Find products where OnHandQty greater than 0
+     */
+    getProducts2_0: (query: Partial<GetProductQueryStrings>) => Promise<DataResponse<GetProduct2_0Response[]>>;
+    /**
+     * Note sure how this is different from /2.0/product.  Only notable difference is "barcodes" type from string to object.
+     */
+    getProductsExperimental: (query: Partial<GetProductQueryStrings>) => Promise<DataResponse<ExperimentalPagedResult<GetProductExperimentalResponse>>>;
+    createProduct1_0: (product: {
         reference_id: string;
         sku: string;
         name: string;
         barcode: string;
     }) => Promise<DataResponse<AddProductResponse>>;
+    /**
+     * The request part for variant is not accurate.  This is just for testing - there are no official docs.
+     */
+    createProduct2_0: (product: {
+        type_id: number;
+        name: string;
+        variants: VariantRequestProduct2_0[];
+    }) => Promise<DataResponse<AddProductResponse>>;
+    /**
+     * Unsure how this is different from '2.0/product' except for "barcode" -> "barcodes"
+     */
+    createProductExperimental: (product: {
+        type_id: number;
+        name: string;
+        variants: VariantRequestProductExperimental[];
+    }) => Promise<DataResponse<AddProductResponse>>;
     placeOrder: (order: PlaceOrderRequest) => Promise<DataResponse<PlaceOrderResponse>>;
     /**
      * Cancel single Order by Order Id
@@ -663,16 +1243,29 @@ export declare const createShipBobApi: (personalAccessToken: string | undefined,
      * @param orderId The order Id to cancel
      */
     cancelSingleOrderByOrderId: (orderId: number) => Promise<DataResponse<CancelOrderResponse>>;
-    getWebhooks: () => Promise<DataResponse<Webhook[][]>>;
-    createWebhookSubscription: (webhook: Omit<Webhook, "id" | "created_at">) => Promise<DataResponse<Webhook>>;
+    getShippingMethods: () => Promise<DataResponse<ShippingMethod[]>>;
+    getWebhooks: () => Promise<DataResponse<Webhook[]>>;
+    /**
+     * NOTE: can consider option to add without providing channel id (would need matching unregister)
+     */
+    registerWebhookSubscription: (webhook: Omit<Webhook, "id" | "created_at">) => Promise<DataResponse<Webhook>>;
+    /**
+     * Can generate 500 response with data: "The wait operation timed out."  If so, check your channel id matches.
+     *
+     * NOTE: can consider option to add without providing channel id (would need matching register)
+     */
+    unregisterWebhookSubscription: (id: number) => Promise<DataResponse<Webhook>>;
     getFulfillmentCenters: () => Promise<DataResponse<FulfillmentCenter[]>>;
     createWarehouseReceivingOrder: (request: WarehouseReceivingOrderRequest) => Promise<DataResponse<WarehouseReceivingOrderResponse>>;
     getWarehouseReceivingOrder: (orderId: number) => Promise<DataResponse<WarehouseReceivingOrderResponse>>;
     getWarehouseReceivingOrderBoxes: (orderId: number) => Promise<DataResponse<WarehouseReceivingOrderBoxesResponse>>;
+    /**
+     * NOTE: should verify that response matches 1.0 product endpoint
+     */
     getReceivingExtended: (query: Partial<{
         Statuses: string;
         ExternalSync: boolean;
-    }>) => Promise<DataResponse<GetProductResult[]>>;
+    }>) => Promise<DataResponse<GetProduct1_0Result[]>>;
     /**
      * This must be for setting/clearing if it has been synced externally.
      *
@@ -681,6 +1274,9 @@ export declare const createShipBobApi: (personalAccessToken: string | undefined,
      * NOTE: this is tagged experimental, so might change or be dropped
      */
     experimentalReceivingSetExternalSync: (ids: number[], isExternalSync: boolean) => Promise<DataResponse<SetExternalSyncResponse>>;
+    /**
+     * NOTE: should verify the response type matches the product 1.0 endpoint
+     */
     listInventory: (query: Partial<{
         /**
          * Page of inventory items to get
@@ -712,7 +1308,7 @@ export declare const createShipBobApi: (personalAccessToken: string | undefined,
          * LocationType is valid for hub, spoke, or lts. LocationType will default to all locations.
          */
         LocationType: string;
-    }>) => Promise<DataResponse<GetProductResult[]>>;
+    }>) => Promise<DataResponse<GetInventory1_0Result[]>>;
     /**
      * Only for sandbox: https://developer.shipbob.com/sandbox-simulations/
      *
@@ -727,3 +1323,4 @@ export declare const createShipBobApi: (personalAccessToken: string | undefined,
      */
     getSimulationStatus: (simulationId: string) => Promise<DataResponse<SimulationResponse>>;
 }>;
+export {};