peddler 4.1.1 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7677959689b208211817ca535b18ec25d495df736d1e502e8b758cdb2c826603
-  data.tar.gz: c4c4f26d97ab8bcbb18e2ee0bbac890e7e2284b475a0d19286ea1c15e456b942
+  metadata.gz: 7620ee0df092e73b0a78eb5e3f9ddd702f8e14bc4a45e782038d85bf0491ce0b
+  data.tar.gz: dc2db93f53918ee36d6cc047e516b1cab57563dd29194daf0f93b3c3565fef8f
 SHA512:
-  metadata.gz: cc020ae6bda468c2d82044b8a7b226f6101ea141b63d3cd8731ae1c58507b93f11c9e8e18040cb8a31ff0c8dcef40617bdc080f76346f029ddab1b35076027e3
-  data.tar.gz: 9e8d25fbdfe70c203331fa4ffda8147000b59e66b0ec0658b99d17a25342e975706d9366d6b7c2d6d9314593cfc6a4fbd7e4bc50b4ff5613aaf452337b7b1061
+  metadata.gz: 928416379dff494fd6fcd87a538a75db8e4a0c6ef3badfeeb9d37da7b4fac118b9fb287e3f30f24bfc7167af784f490ee0054f81c4f65e9a551649598e64c3f0
+  data.tar.gz: 8159e422fb43f6543dbb6541d26f95e51faa89e40bf831a62b872497ad57e66cbb0036c83d4a9a5b1e588d8eb44c360833fe7b3a5a5aeee1db5bad35a792608f

data/README.md

@@ -1,10 +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]
-
-> **_NOTE:_** This README explains the main branch, which may contain unreleased code. For the README of the latest release, please refer to [this link][latest-release-readme].
 
 **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.
 
@@ -72,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(
@@ -102,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.
-
-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.
+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.
 
-**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.
+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.
 
-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)
@@ -118,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
 
-### The 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:
+
+```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
+
+Manage product listings with multiple APIs:
 
-Enables you to manage your product listings on Amazon, including creating, updating, and deleting listings.
+- **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: [
@@ -294,228 +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
-[latest-release-readme]: https://github.com/lineofflight/peddler/tree/v3.0.0
 [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/api.rb

@@ -30,8 +30,9 @@ module Peddler
     # @return [Integer]
     attr_reader :retries
 
-    # @param [String] aws_region
-    # @param [String] access_token
+    # @param [String] aws_region The AWS region to use for the endpoint
+    # @param [String] access_token The access token for authentication
+    # @param [Integer] retries The number of retries if throttled (default: 0)
     def initialize(aws_region, access_token, retries: 0)
       @endpoint = Endpoint.find(aws_region)
       @access_token = access_token