peddler 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f24fcbe5356adc88b3eff33d9f5ca86631c96c4c3187c189594b5771034f111c
-  data.tar.gz: d605c37bade2f932f1661a8351db41e2e77f4c6684796e583dbf28939d08489e
+  metadata.gz: 7620ee0df092e73b0a78eb5e3f9ddd702f8e14bc4a45e782038d85bf0491ce0b
+  data.tar.gz: dc2db93f53918ee36d6cc047e516b1cab57563dd29194daf0f93b3c3565fef8f
 SHA512:
-  metadata.gz: bd19ca60dfbbfefdf17ef1152dc4ab5906265e1266ad66a13fc4bcf3cb4190a1b34b5b6b1908c1ed093ff5fa702c31e0275c7d00d24a1c39c5ea696abd2a6887
-  data.tar.gz: 61f4b5e4238fd997cf7e2606caf39138b8dcda336aa63c6685ef3d67ee41d9c64357577e0831961ef40a7974d6d9e1c567093d5ea2b1884489e3e5835aaaebb7
+  metadata.gz: 928416379dff494fd6fcd87a538a75db8e4a0c6ef3badfeeb9d37da7b4fac118b9fb287e3f30f24bfc7167af784f490ee0054f81c4f65e9a551649598e64c3f0
+  data.tar.gz: 8159e422fb43f6543dbb6541d26f95e51faa89e40bf831a62b872497ad57e66cbb0036c83d4a9a5b1e588d8eb44c360833fe7b3a5a5aeee1db5bad35a792608f

data/README.md

@@ -1,8 +1,6 @@
 # Peddler
 
 [![Build](https://github.com/hakanensari/peddler/workflows/build/badge.svg)][build]
-[![Maintainability](https://api.codeclimate.com/v1/badges/281e6176048f3c0a1ed3/maintainability)][maintainability]
-[![Test Coverage](https://api.codeclimate.com/v1/badges/281e6176048f3c0a1ed3/test_coverage)][test-coverage]
 
 **Peddler** is a Ruby interface to the [Amazon Selling Partner API (SP-API)][docs-overview]. The SP-API enables Amazon sellers and vendors to programmatically access their data on orders, shipments, payments, and more.
 
@@ -70,7 +68,7 @@ access_token = Peddler::Token.request(
 ).parse["access_token"]
 ```
 
-If you haven’t set your LWA credentials as environment variables, pass them directly when requesting the token.
+If you haven't set your LWA credentials as environment variables, pass them directly when requesting the token.
 
 ```ruby
 access_token = Peddler::Token.request(
@@ -100,13 +98,11 @@ end
 
 ### Rate limiting
 
-Amazon’s Selling Partner API (SP-API) imposes [rate limits][rate-limits] on most operations. Peddler respects these limits and will automatically back off when throttled. You can override the default rate limit by passing a `:rate_limit` to the operation.
+Amazon's SP-API imposes [rate limits][rate-limits] on operations. Override the default rate limit by passing a `:rate_limit` parameter when calling an operation.
 
-You can also provide an optional `:retries` argument when initializing an API to specify the number of retries if throttled. By default, this is set to 0, meaning no retries will be attempted. If set to a positive value, Peddler will retry the request that many times if throttled, backing off based on the specified rate limit.
+Provide an optional `:retries` argument when initializing an API to specify retry attempts if throttled. Default is 0 (no retries). If set to a positive value, Peddler will retry with exponential backoff based on the rate limit.
 
-**Note:** This functionality requires version 6 of the underlying [HTTP library][httprb]. As of writing, this is not released yet. To use rate limiting, point to their main branch on GitHub.
-
-Example usage:
+**Note:** This functionality requires version 6 of the [HTTP library][httprb], which is not yet released. To use rate limiting, point to their main branch on GitHub.
 
 ```ruby
 api = Peddler.orders_v0(aws_region, access_token, retries: 3)
@@ -116,171 +112,144 @@ api.get_orders(
 )
 ```
 
-In this example, if the request to `get_orders` is throttled, Peddler will retry the request up to 3 times, backing off according to the rate limit specified by Amazon.
+### Available APIs
+
+Peddler provides Ruby interfaces to all Amazon SP-API endpoints. Each API is available in its respective version. Access APIs by calling methods on the Peddler module:
 
-### The APIs
+```ruby
+api = Peddler.<api_name>_<version>(aws_region, access_token, options)
+```
 
-Peddler provides a class for each API version under an eponymous namespace. Below is a list of the more important APIs, along with brief descriptions and code examples to help you get started.
+Below are key APIs with examples of their usage:
 
-#### Catalog Items API (2022-04-01)
+#### Orders API (v0)
 
-Provides programmatic access to Amazon's catalog data, such as item titles, descriptions, and other product details.
+Retrieve order information and manage orders.
 
 ```ruby
-api = Peddler.catalog_items_2022_04_01(aws_region, access_token)
-response = api.get_catalog_item(
+api = Peddler.orders_v0(aws_region, access_token)
+response = api.get_orders(
   marketplaceIds: ["ATVPDKIKX0DER"],
-  asin: "B08N5WRWNW"
+  createdAfter: "2023-01-01T00:00:00Z"
 )
-items = response.dig("items")
+orders = response.parse["orders"]
 ```
 
-#### Orders API (v0)
+#### Catalog Items API (2022-04-01, 2020-12-01, v0)
 
-Allows you to retrieve order information, including order details, buyer information, and order items.
+Access Amazon's catalog data including product details, offers, and competitive pricing.
 
 ```ruby
-api = Peddler.orders_v0(aws_region, access_token)
-response = api.get_orders(
+api = Peddler.catalog_items_2022_04_01(aws_region, access_token)
+response = api.get_catalog_item(
   marketplaceIds: ["ATVPDKIKX0DER"],
-  createdAfter: "2023-01-01T00:00:00Z"
+  asin: "B08N5WRWNW"
 )
-response.dig("orders")
+item_details = response.parse["payload"]
 ```
 
 #### Feeds API (2021-06-30)
 
-Enables you to upload data to Amazon for updating listings, prices, inventory, and more.
+Upload data to Amazon to update listings, prices, inventory, and more.
 
 ```ruby
 api = Peddler.feeds_2021_06_30(aws_region, access_token)
 
-# Create a feed document to get an upload URL
-response = api.create_feed_document(
+# Create feed document
+document_response = api.create_feed_document(
   contentType: "text/xml; charset=UTF-8"
 )
-feed_document_id = response.parse["feedDocumentId"]
-upload_url = response.parse["url"]
+feed_document_id = document_response.parse["feedDocumentId"]
+upload_url = document_response.parse["url"]
 
-# Upload the feed content to the provided URL
+# Upload feed content
 feed_content = File.read("inventory_update.xml")
 api.upload_feed_document(upload_url, feed_content, "text/xml; charset=UTF-8")
 
-# Create the feed
-response = api.create_feed(
+# Create feed
+feed_response = api.create_feed(
   feedType: "POST_INVENTORY_AVAILABILITY_DATA",
   marketplaceIds: ["ATVPDKIKX0DER"],
   inputFeedDocumentId: feed_document_id
 )
-response.parse["feedId"]
+feed_id = feed_response.parse["feedId"]
 ```
 
 #### Reports API (2021-06-30)
 
-Allows you to request and download various reports, such as order and inventory reports.
+Request and download reports about orders, inventory, fulfillment, and more.
 
 ```ruby
 api = Peddler.reports_2021_06_30(aws_region, access_token)
-response = api.create_report(
+
+# Request a report
+create_response = api.create_report(
   reportType: "GET_FLAT_FILE_OPEN_LISTINGS_DATA",
   marketplaceIds: ["ATVPDKIKX0DER"]
 )
-response.parse["reportId"]
+report_id = create_response.parse["reportId"]
+
+# Check report status
+report = api.get_report(report_id).parse
+
+# Once processed, get the document
+if report["processingStatus"] == "DONE"
+  doc_id = report["reportDocumentId"]
+  document = api.get_report_document(doc_id).parse
+  download_url = document["url"]
+  # Download report from URL
+end
 ```
 
-#### Listings Items API (2021-08-01)
+#### Listings APIs
 
-Enables you to manage your product listings on Amazon, including creating, updating, and deleting listings.
+Manage product listings with multiple APIs:
+
+- **Listings Items API (2021-08-01, 2020-09-01)**: Create and update listings
+- **Listings Restrictions API (2021-08-01)**: Check listing eligibility
+- **Product Type Definitions API (2020-09-01)**: Get schema requirements for listings
 
 ```ruby
 api = Peddler.listings_items_2021_08_01(aws_region, access_token)
-response = api.put_listings_item(
-  "<SELLER_ID>",
+api.put_listings_item(
+  seller_id,
   "SKU123",
   "ATVPDKIKX0DER",
   body: {
-    productType: "PRODUCT",
+    productType: "LUGGAGE",
     requirements: "LISTING",
     attributes: {
-      title: [{ value: "New Product Title" }],
-      description: [{ value: "Product description goes here." }],
-      bullet_point: [{ value: "Feature 1" }, { value: "Feature 2" }],
-      manufacturer: [{ value: "Your Brand" }]
+      title: [{ value: "Travel Backpack" }],
+      manufacturer: [{ value: "Brand Name" }]
     }
   }
 )
-response.parse
 ```
 
-#### Notifications API (v1)
+#### Fulfillment APIs
 
-Allows you to subscribe to notifications for specific events like order status updates or feed processing statuses.
+Manage inventory and fulfillment through FBA and merchant fulfillment:
 
-```ruby
-api = Peddler.notifications_v1(aws_region, access_token)
-# Create a destination
-response = api.create_destination(
-  name: "MySQSQueue",
-  resourceSpecification: {
-    sqs: {
-      arn: "arn:aws:sqs:us-east-1:123456789012:MyQueue"
-    }
-  }
-)
-destination_id = response.parse["destinationId"]
-
-# Create a subscription
-response = api.create_subscription(
-  notificationType: "ANY_OFFER_CHANGED",
-  destinationId: destination_id
-)
-subscription = response.parse
-```
-
-#### Product Fees API (v0)
-
-Provides information about fees that may be charged for selling products on Amazon.
-
-```ruby
-api = Peddler.product_fees_v0(aws_region, access_token)
-response = api.get_my_fees_estimate_for_sku(
-  sellerId: "<YOUR_SELLER_ID>",
-  sku: "SKU123",
-  body: {
-    FeesEstimateRequest: {
-      MarketplaceId: "ATVPDKIKX0DER",
-      IsAmazonFulfilled: true,
-      PriceToEstimateFees: {
-        ListingPrice: {
-          CurrencyCode: "USD",
-          Amount: 25.00
-        }
-      }
-    }
-  }
-)
-fees_estimate = response.parse
-```
-
-#### Fulfillment Outbound API (2020-07-01)
-
-Allows you to create and manage fulfillment orders using Amazon's fulfillment network.
+- **Fulfillment Inbound API (2024-03-20, v0)**: Send inventory to FBA
+- **Fulfillment Outbound API (2020-07-01)**: Create and track FBA orders
+- **FBA Inventory API (v1)**: Manage FBA inventory quantities
+- **Merchant Fulfillment API (v0)**: Create shipping labels for self-fulfilled orders
 
 ```ruby
+# FBA outbound example
 api = Peddler.fulfillment_outbound_2020_07_01(aws_region, access_token)
-response = api.create_fulfillment_order(
+api.create_fulfillment_order(
   body: {
     sellerFulfillmentOrderId: "ORDER123",
     displayableOrderId: "ORDER123",
     displayableOrderDate: Time.now.iso8601,
-    displayableOrderComment: "Thank you for your order!",
     shippingSpeedCategory: "Standard",
     destinationAddress: {
-      name: "John Doe",
+      name: "Customer Name",
       addressLine1: "123 Main St",
-      city: "Anytown",
-      stateOrRegion: "NY",
-      postalCode: "12345",
+      city: "Seattle",
+      stateOrRegion: "WA",
+      postalCode: "98101",
       countryCode: "US"
     },
     items: [
@@ -292,227 +261,81 @@ response = api.create_fulfillment_order(
     ]
   }
 )
-response.parse
-```
-
-#### Merchant Fulfillment API (v0)
-
-Allows you to create shipping labels for orders using Amazon's negotiated shipping rates.
-
-```ruby
-api = Peddler.merchant_fulfillment_v0(aws_region, access_token)
-response = api.get_eligible_shipping_services(
-  body: {
-    shipmentRequestDetails: {
-      amazonOrderId: "ORDER123",
-      itemList: [
-        {
-          orderItemId: "ITEM123",
-          quantity: 1
-        }
-      ],
-      shipFromAddress: {
-        name: "Your Company",
-        addressLine1: "123 Warehouse Ave",
-        city: "Anytown",
-        stateOrRegion: "NY",
-        postalCode: "12345",
-        countryCode: "US"
-      },
-      packageDimensions: {
-        length: 10,
-        width: 5,
-        height: 8,
-        unit: "INCHES"
-      },
-      weight: {
-        value: 2,
-        unit: "POUNDS"
-      },
-      shippingServiceOptions: {
-        deliveryExperience: "DELIVERY_CONFIRMATION_WITHOUT_SIGNATURE",
-        carrierWillPickUp: false
-      }
-    }
-  }
-)
-shipping_services = response.parse["shippingServiceList"]
 ```
 
-#### Vendor Orders API (2021-12-29)
+#### Financial APIs (2024-06-19, 2024-06-01, v0)
 
-Allows vendors to retrieve purchase orders and order details from Amazon.
+Get financial data including transaction details, payments, and refunds.
 
 ```ruby
-api = Peddler.vendor_orders_2021_12_28(aws_region, access_token)
-response = api.get_purchase_orders(
-  shipToPartyId: "<PARTY_ID>",
-  limit: 10,
-  createdAfter: "2023-01-01T00:00:00Z"
-)
-purchase_orders = response.parse["purchaseOrders"]
-```
-
-#### Vendor Direct Fulfillment Shipping API (2021-12-28)
-
-Enables vendors to manage shipping labels and shipping information for direct fulfillment orders.
-
-```ruby
-api = Peddler.vendor_direct_fulfillment_shipping_2021_12_28(aws_region, access_token)
-response = api.get_packing_slip(
-  purchaseOrderNumber: "PO123456789"
-)
-response.parse
-```
-
-#### Vendor Direct Fulfillment Orders API (2021-12-28)
-
-Allows vendors to receive orders for direct fulfillment and provide shipment confirmations.
-
-```ruby
-api = Peddler.vendor_direct_fulfillment_orders_2021_12_28(aws_region, access_token)
-response = api.get_orders(
-  createdAfter: "2023-01-01T00:00:00Z",
-  limit: 10
+api = Peddler.finances_v0(aws_region, access_token)
+response = api.list_financial_events(
+  posted_after: "2023-01-01T00:00:00Z"
 )
-response.parse["orders"]
+financial_events = response.parse["FinancialEvents"]
 ```
 
-#### Vendor Direct Fulfillment Inventory API (2021-12-28)
+#### Notifications API (v1)
 
-Enables vendors to update inventory levels for direct fulfillment items.
+Subscribe to notifications for various events like order updates and report processing.
 
 ```ruby
-api = Peddler.vendor_direct_fulfillment_inventory_2021_12_28(aws_region, access_token)
-response = api.submit_inventory_update(
-  body: {
-    inventory: [
-      {
-        sellingParty: {
-          partyId: "<PARTY_ID>"
-        },
-        warehouseId: "<WAREHOUSE_ID>",
-        items: [
-          {
-            buyerProductIdentifier: "B08N5WRWNW",
-            availableQuantity: {
-              amount: 100,
-              unitOfMeasure: "Each"
-            }
-          }
-        ]
-      }
-    ]
+api = Peddler.notifications_v1(aws_region, access_token)
+# Create destination
+destination = api.create_destination(
+  name: "MyEventQueue",
+  resourceSpecification: {
+    sqs: { arn: "arn:aws:sqs:us-east-1:123456789012:MyQueue" }
   }
 )
-response.parse
-```
-
-#### Shipping API (v2)
+destination_id = destination.parse["payload"]["destinationId"]
 
-Provides functionalities for purchasing shipping labels and tracking shipments.
-
-```ruby
-api = Peddler.shipping_v2(aws_region, access_token)
-response = api.purchase_shipment(
-  body: {
-    clientReferenceId: "CLIENT_REF_123",
-    shipTo: {
-      name: "John Doe",
-      addressLine1: "123 Main St",
-      city: "Anytown",
-      stateOrRegion: "NY",
-      postalCode: "12345",
-      countryCode: "US"
-    },
-    shipFrom: {
-      name: "Your Company",
-      addressLine1: "123 Warehouse Ave",
-      city: "Anytown",
-      stateOrRegion: "NY",
-      postalCode: "12345",
-      countryCode: "US"
-    },
-    packages: [
-      {
-        dimensions: {
-          length: 10,
-          width: 5,
-          height: 8,
-          unit: "IN"
-        },
-        weight: {
-          value: 2,
-          unit: "LB"
-        }
-      }
-    ],
-    serviceType: "Standard"
-  }
+# Create subscription
+api.create_subscription(
+  notificationType: "ANY_OFFER_CHANGED",
+  destinationId: destination_id,
+  payloadVersion: "1"
 )
-response.parse
 ```
 
-#### Token API (2021-03-01)
-
-Allows you to create restricted data tokens to access personally identifiable information (PII) in specific API calls.
-
-```ruby
-api = Peddler.tokens_2021_03_01(aws_region, access_token)
-response = api.create_restricted_data_token(
-  body: {
-    restrictedResources: [
-      {
-        method: "GET",
-        path: "/orders/v0/orders/123-1234567-1234567",
-        dataElements: ["buyerInfo", "shippingAddress"]
-      }
-    ]
-  }
-)
-restricted_data_token = response.parse["restrictedDataToken"]
-
-# Use the token in subsequent API calls
-orders_api = Peddler.orders_2021_12_01("<AWS_REGION>", restricted_data_token)
-response = orders_api.get_order(
-  orderId: "123-1234567-1234567"
-)
-response.parse
-```
+#### Vendor APIs
 
-#### Finances API (v0)
+APIs for vendors selling to Amazon:
 
-Provides information about financial events for your seller account, such as order payments, refunds, and fees.
+- **Vendor Orders API (v1)**: Retrieve purchase orders
+- **Vendor Direct Fulfillment APIs**: Manage orders, shipping, payments, and inventory
+- **Vendor Shipments API (v1)**: Track vendor shipments
+- **Vendor Invoices API (v1)**: Submit and track invoices
 
 ```ruby
-api = Peddler.finances_v0(aws_region, access_token)
-response = api.list_financial_events(
-  postedAfter: "2023-01-01T00:00:00Z",
-  maxResultsPerPage: 100
-)
-response.parse
+api = Peddler.vendor_orders_v1(aws_region, access_token)
+orders = api.get_purchase_orders(
+  limit: 10,
+  createdAfter: "2023-01-01T00:00:00Z"
+).parse
 ```
 
-#### Sellers API (V1)
+#### Additional APIs
 
-Provides information about seller's marketplaces and participation status.
+- **A+ Content API (2020-11-01)**: Create and manage enhanced marketing content
+- **Authorization API (2023-11-30)**: Manage app authorization
+- **Messaging API (v1)**: Send messages to customers
+- **Product Fees API (v0)**: Retrieve fee estimates for products
+- **Product Pricing API (2022-05-01, v0)**: Get pricing information
+- **Sellers API (v1)**: Get seller account information and marketplace participation
+- **Shipping APIs (v1, v2)**: Create shipments and purchase shipping labels
+- **Solicitations API (v1)**: Request customer reviews
+- **Tokens API (2021-03-01)**: Generate restricted data tokens for accessing PII
+- **Uploads API (2020-11-01)**: Upload files for various SP-API operations
 
-```ruby
-api = Peddler.sellers_v1(aws_region, access_token)
-response = api.get_marketplace_participations
-response.parse
-```
+For a complete list of available APIs, refer to the [API models repository](https://github.com/amzn/selling-partner-api-models).
 
 ## TODO
 
-- [ ] Code generate payload parsers.
-- [ ] Code generate the APIs section—descriptions and code examples—in this README here.
-- [ ] Schedule code generation with GitHub Actions. Push new gem when models change.
-- [ ] Review and consider applying [these patches][patches].
+- [ ] Code generate payload parsers
+- [ ] Review and consider applying [these patches][patches]
 
 [build]: https://github.com/hakanensari/peddler/actions
-[maintainability]: https://codeclimate.com/github/hakanensari/peddler/maintainability
-[test-coverage]: https://codeclimate.com/github/hakanensari/peddler/test_coverage
 [docs-overview]: https://developer.amazonservices.com/sp-api-docs/overview
 [register-as-developer]: https://developer-docs.amazon.com/sp-api/docs/registering-as-a-developer
 [register-application]: https://developer-docs.amazon.com/sp-api/docs/registering-your-application

data/lib/peddler/apis/catalog_items_v0.rb

@@ -15,68 +15,6 @@ module Peddler
     # The Selling Partner API for Catalog Items helps you programmatically retrieve item details for items in the
     # catalog.
     class CatalogItemsV0 < API
-      # Effective September 30, 2022, the `listCatalogItems` operation will no longer be available in the Selling
-      # Partner API for Catalog Items v0. As an alternative, `searchCatalogItems` is available in the latest version of
-      # the {https://developer-docs.amazon.com/sp-api/docs/catalog-items-api-v2022-04-01-reference Selling Partner API
-      # for Catalog Items v2022-04-01}. Integrations that rely on the `listCatalogItems` operation should migrate to the
-      # `searchCatalogItems`operation to avoid service disruption. _Note:_ The
-      # [`listCatalogCategories`](#get-catalogv0categories) operation is not being deprecated and you can continue to
-      # make calls to it.
-      #
-      # @note This operation can make a static sandbox call.
-      # @param marketplace_id [String] A marketplace identifier. Specifies the marketplace for which items are returned.
-      # @param query [String] Keyword(s) to use to search for items in the catalog. Example: 'harry potter books'.
-      # @param query_context_id [String] An identifier for the context within which the given search will be performed.
-      #   A marketplace might provide mechanisms for constraining a search to a subset of potential items. For example,
-      #   the retail marketplace allows queries to be constrained to a specific category. The QueryContextId parameter
-      #   specifies such a subset. If it is omitted, the search will be performed using the default context for the
-      #   marketplace, which will typically contain the largest set of items.
-      # @param seller_sku [String] Used to identify an item in the given marketplace. SellerSKU is qualified by the
-      #   seller's SellerId, which is included with every operation that you submit.
-      # @param upc [String] A 12-digit bar code used for retail packaging.
-      # @param ean [String] A European article number that uniquely identifies the catalog item, manufacturer, and its
-      #   attributes.
-      # @param isbn [String] The unique commercial book identifier used to identify books internationally.
-      # @param jan [String] A Japanese article number that uniquely identifies the product, manufacturer, and its
-      #   attributes.
-      # @return [Peddler::Response] The API response
-      def list_catalog_items(marketplace_id, query: nil, query_context_id: nil, seller_sku: nil, upc: nil, ean: nil,
-        isbn: nil, jan: nil)
-        path = "/catalog/v0/items"
-        params = {
-          "MarketplaceId" => marketplace_id,
-          "Query" => query,
-          "QueryContextId" => query_context_id,
-          "SellerSKU" => seller_sku,
-          "UPC" => upc,
-          "EAN" => ean,
-          "ISBN" => isbn,
-          "JAN" => jan,
-        }.compact
-
-        get(path, params:)
-      end
-
-      # Effective September 30, 2022, the `getCatalogItem` operation will no longer be available in the Selling Partner
-      # API for Catalog Items v0. This operation is available in the latest version of the
-      # {https://developer-docs.amazon.com/sp-api/docs/catalog-items-api-v2022-04-01-reference Selling Partner API for
-      # Catalog Items v2022-04-01}. Integrations that rely on this operation should migrate to the latest version to
-      # avoid service disruption. _Note:_ The [`listCatalogCategories`](#get-catalogv0categories) operation is not being
-      # deprecated and you can continue to make calls to it.
-      #
-      # @note This operation can make a static sandbox call.
-      # @param marketplace_id [String] A marketplace identifier. Specifies the marketplace for the item.
-      # @param asin [String] The Amazon Standard Identification Number (ASIN) of the item.
-      # @return [Peddler::Response] The API response
-      def get_catalog_item(marketplace_id, asin)
-        path = "/catalog/v0/items/#{asin}"
-        params = {
-          "MarketplaceId" => marketplace_id,
-        }.compact
-
-        get(path, params:)
-      end
-
       # Returns the parent categories to which an item belongs, based on the specified ASIN or SellerSKU.
       #
       # @note This operation can make a static sandbox call.