shipbob-node-sdk 0.0.2 → 0.0.3

package/README.md

@@ -3,7 +3,7 @@ First of all there are no official SDKs for ShipBob.  I'm just dropping this her
 
 These is just a starting point for anybody looking to integrate ShipBob into a Node.js application.
 
-You could make it run in the browser by replacing `https` with `fetch` or `axios`.  I could have used fetch as well, but in case somebody is on Node < v18 (and it wasn't stable till v21 anyway).
+It uses the built-in node.js fetch.
 
 This is not an official or supported library.  If you extend or have any issues kindly open a PR.  Not really sure anybody will ever need this as most common platforms probably have built-in support.
 
@@ -52,10 +52,17 @@ SHIPBOB_API_TOKEN=<redacted>
 - [x] Get logs for one Shipment by Shipment Id
 - [?] Get shipping methods (hard-code shipping methods?)
 
-## Products
-- [✓] Get multiple products: api.getProducts(...)
-- [✓] Add a single product to the store: api.addProduct(...)
-- [ ] Modify a single product (we will need this to add multiple barcodes)
+## Products 1.0
+- [✓] Get multiple products: api.getProducts1_0(...)
+- [✓] Add a single product to the store: api.createProduct1_0(...)
+- [x] Modify a single product (using 2.0 for additional properties)
+- [x] Add multiple products to the store
+
+## Products 2.0
+These are not documented on the site yet.
+- [✓] Get multiple products: api.getProducts2_0(...)
+- [✓] Add a single product to the store: api.createProduct2_0(...)
+- [✓] Modify a single product: api.updateProducts2_0(..,)
 - [x] Add multiple products to the store
 
 ## Inventory

package/dist/index.d.ts

@@ -72,10 +72,218 @@ 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';
+/**
+ * This is just some guessing based on a response
+ */
+export type GetProduct2_0Result = {
+    /**
+     * 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: {
+        /**
+         * 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: [];
+    }[];
+};
 export type OrderType = 'DTC' | 'DropShip' | 'B2B' | 'Transportation';
 export type AnyProduct = ({
     /**
@@ -627,6 +835,103 @@ 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 ProductVariantRequest = {
+    /**
+     * 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;
+        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>;
+    };
+};
 /**
  * Create API with PAT (personal access token) - defaults to sandbox endpoints and "SMA" channel.
  *
@@ -640,8 +945,8 @@ export type WarehouseReceivingOrderBoxesResponse = {
  * @returns
  */
 export declare const createShipBobApi: (personalAccessToken: string | undefined, apiBaseUrl?: string, channelApplicationName?: string) => Promise<{
-    getProductById: (productId: number) => Promise<DataResponse<GetProductResult>>;
-    getProducts: (query: Partial<{
+    getProductById: (productId: number) => Promise<DataResponse<GetProduct1_0Result>>;
+    getProducts1_0: (query: Partial<{
         ReferenceIds: string;
         Page: number;
         Limit: number;
@@ -649,13 +954,85 @@ 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: 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.
+     */
+    updateProducts2_0: (productId: number, variants: ProductVariantRequest[]) => 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<{
+        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;
+    }>) => Promise<DataResponse<GetProduct2_0Result[]>>;
+    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: {
+        reference_id: string;
+        sku: string;
+        type_id: number;
+        name: string;
+        variants: ProductVariantRequest[];
+    }) => Promise<DataResponse<AddProductResponse>>;
     placeOrder: (order: PlaceOrderRequest) => Promise<DataResponse<PlaceOrderResponse>>;
     /**
      * Cancel single Order by Order Id
@@ -669,10 +1046,13 @@ export declare const createShipBobApi: (personalAccessToken: string | undefined,
     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 +1061,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 +1095,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<GetProduct1_0Result[]>>;
     /**
      * Only for sandbox: https://developer.shipbob.com/sandbox-simulations/
      *