walmart-apimatic-sdk 0.0.1 → 0.0.5

data/lib/walmart_ap_is/apis/authorization_api.rb

@@ -0,0 +1,238 @@
+# walmart_ap_is
+#
+# This file was automatically generated by APIMATIC v3.0 (
+# https://www.apimatic.io ).
+
+module WalmartApIs
+  # AuthorizationApi
+  class AuthorizationApi < BaseApi
+    # Exchanges a grant for an OAuth access token. Supported `grant_type`
+    # values:
+    # | grant_type           | Flow             | Required (besides grant_type)
+    #  |
+    # |----------------------|------------------|-------------------------------
+    # --|
+    # | `client_credentials` | seller-direct    | client auth (see below)
+    #  |
+    # | `authorization_code` | delegated        | `code`, `code_verifier` (PKCE)
+    #  |
+    # | `refresh_token`      | delegated        | `refresh_token`
+    #  |
+    # **Client authentication:** credentials in the form body
+    # (`client_secret_post`)
+    # — `client_id` + `client_secret`. HTTP Basic is also accepted. **Public
+    # clients** (Solution-Provider apps registered `token_endpoint_auth_method:
+    # none`)
+    # send no secret on the delegated grants; PKCE protects the code.
+    # **`client_credentials`:** issues **no** refresh token (re-mint on expiry).
+    # **`scope` is decorative here** — accepted for compatibility but **not
+    # honored**;
+    # access is governed by the scopes provisioned per client in IAM (ADR-012);
+    # there
+    # is no down-scoping and the response does not echo `scope`. (Verified:
+    # `/v3/token`
+    # ignores any `scope=` value.)
+    # **`authorization_code`:** `redirect_uri` is accepted for OAuth 2.0
+    # back-compat
+    # but not required in 2.1 (PKCE covers injection).
+    # **`refresh_token`:** the response includes a **rotated** `refresh_token` —
+    # the
+    # presented token is invalidated (OAuth 2.1 §4.3.1; IAM rotates today,
+    # ~1-year
+    # TTL). A requested `scope` MUST NOT exceed the originally granted scope.
+    # **Token:** `Bearer` (RFC 6750), sent downstream as `Authorization: Bearer
+    # <token>` — **not** `WM_SEC.ACCESS_TOKEN`.
+    # **Implemented by `authorization-service` as a stateless proxy to Walmart
+    # IAM (ADR-026).**
+    # @param [GrantType] grant_type Required parameter: The OAuth grant type.
+    # @param [String] client_id Optional parameter: Client identifier
+    # (client_secret_post / public clients). Omit if using HTTP Basic.
+    # @param [String] client_secret Optional parameter: Client secret
+    # (client_secret_post). Omit for public clients or HTTP Basic.
+    # @param [String] code Optional parameter: Authorization code from
+    # `/auth/v4/authorize` (authorization_code grant).
+    # @param [String] code_verifier Optional parameter: PKCE verifier whose S256
+    # hash equals the earlier `code_challenge` (authorization_code grant).
+    # @param [String] refresh_token Optional parameter: A previously issued
+    # refresh token (refresh_token grant). Rotated on use.
+    # @param [String] redirect_uri Optional parameter: Accepted for OAuth 2.0
+    # back-compat on authorization_code; not required in 2.1 (PKCE covers
+    # injection).
+    # @param [String] scope Optional parameter: **client_credentials:** accepted
+    # for compatibility but **not honored** (ADR-012) — no down-scoping; not
+    # echoed. **refresh_token:** optional; MUST NOT exceed the originally
+    # granted scope.
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def create_token(grant_type,
+                     client_id: nil,
+                     client_secret: nil,
+                     code: nil,
+                     code_verifier: nil,
+                     refresh_token: nil,
+                     redirect_uri: nil,
+                     scope: nil)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/auth/v4/token',
+                                     Server::DEFAULT)
+                   .form_param(new_parameter(grant_type, key: 'grant_type')
+                                .is_required(true))
+                   .form_param(new_parameter(client_id, key: 'client_id'))
+                   .form_param(new_parameter(client_secret, key: 'client_secret'))
+                   .form_param(new_parameter(code, key: 'code'))
+                   .form_param(new_parameter(code_verifier, key: 'code_verifier'))
+                   .form_param(new_parameter(refresh_token, key: 'refresh_token'))
+                   .form_param(new_parameter(redirect_uri, key: 'redirect_uri'))
+                   .form_param(new_parameter(scope, key: 'scope'))
+                   .header_param(new_parameter('application/x-www-form-urlencoded', key: 'content-type'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Or.new('basicClientAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(TokenResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Invalid token request (RFC 6749 §5.2).',
+                                 OauthErrorException)
+                    .local_error('401',
+                                 'Client authentication failed — `invalid_client`.',
+                                 OauthErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded.',
+                                 OauthErrorException)
+                    .local_error('500',
+                                 'Internal error.',
+                                 OauthErrorException))
+        .execute
+    end
+
+    # Browser endpoint for the authorization-code grant (RFC 6749 §3.1). The
+    # Solution Provider redirects the seller here; the seller authenticates and
+    # consents at Walmart IAM, and the response redirects to `redirect_uri` with
+    # a
+    # single-use `code`.
+    # - **PKCE required** — `code_challenge` + `code_challenge_method=S256`
+    #   (RFC 7636). `plain` is not accepted.
+    # - **Exact** `redirect_uri` match against a value registered for the
+    # client.
+    # - `state` required; echoed back verbatim (CSRF).
+    # - The success and error redirects (performed by IAM) carry `iss` (RFC
+    # 9207);
+    #   clients MUST validate it.
+    # **Error handling.** For a valid request, this endpoint `302`-redirects to
+    # the
+    # Walmart IAM consent URL; IAM then drives consent and performs the RFC 6749
+    # §4.1.2.1 redirect back to the client's `redirect_uri` (success or error),
+    # because IAM is the party that can verify the `redirect_uri` is registered.
+    # For request-level errors that `authorization-service` itself detects
+    # (missing/invalid `client_id`/`redirect_uri`, `response_type` != `code`,
+    # `code_challenge_method` != `S256`), it returns a JSON `400`
+    # (`AuthorizeError`).
+    # It deliberately does **not** redirect these errors to the supplied
+    # `redirect_uri`: the proxy has no client registry, so self-redirecting to
+    # an
+    # unverified URI would be an open redirect.
+    # > **Upstream status (ADR-048, pending):** `iss` emission, exact-redirect
+    # > enforcement, and server-side rejection of `code_challenge_method=plain`
+    # are
+    # > IAM / app-store responsibilities not yet fully in place.
+    # authorization-service
+    # > enforces the request-side invariants it can and redirects valid requests
+    # to
+    # > IAM; the full guarantee lands when those upstream changes ship.
+    # @param [ResponseType1] response_type Required parameter: Must be `code`.
+    # @param [String] client_id Required parameter: The registered client
+    # identifier.
+    # @param [String] redirect_uri Required parameter: Callback URI; must
+    # exactly match a registered value.
+    # @param [String] scope Required parameter: Space-delimited scopes. Include
+    # `offline_access` to receive a refresh token.
+    # @param [String] state Required parameter: Opaque CSRF token; echoed back
+    # unchanged.
+    # @param [String] code_challenge Required parameter: PKCE challenge —
+    # base64url(SHA-256(code_verifier)).
+    # @param [CodeChallengeMethod] code_challenge_method Required parameter:
+    # Must be `S256`.
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def authorize(response_type,
+                  client_id,
+                  redirect_uri,
+                  scope,
+                  state,
+                  code_challenge,
+                  code_challenge_method)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/auth/v4/authorize',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(response_type, key: 'response_type')
+                                 .is_required(true))
+                   .query_param(new_parameter(client_id, key: 'client_id')
+                                 .is_required(true))
+                   .query_param(new_parameter(redirect_uri, key: 'redirect_uri')
+                                 .is_required(true))
+                   .query_param(new_parameter(scope, key: 'scope')
+                                 .is_required(true))
+                   .query_param(new_parameter(state, key: 'state')
+                                 .is_required(true))
+                   .query_param(new_parameter(code_challenge, key: 'code_challenge')
+                                 .is_required(true))
+                   .query_param(new_parameter(code_challenge_method, key: 'code_challenge_method')
+                                 .is_required(true)))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Non-redirectable request (bad `client_id`/`redirect_uri`).',
+                                 AuthorizeErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded.',
+                                 OauthErrorException)
+                    .local_error('500',
+                                 'Internal error.',
+                                 OauthErrorException))
+        .execute
+    end
+
+    # Registers a Solution Provider client and returns its `client_id` (RFC
+    # 7591). Lets Solution Providers onboard without manual registration.
+    # Public clients set `token_endpoint_auth_method: none` (no secret; PKCE
+    # required). Confidential clients receive a `client_secret`. `redirect_uris`
+    # are validated and later enforced by exact match at `/auth/v4/authorize`.
+    # Proxied to Walmart IAM's registration endpoint (ADR-026/ADR-048). RFC 7592
+    # registration management (read/update/delete via a
+    # `registration_access_token`) is not offered in this version.
+    # @param [ClientRegistrationRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def register_client(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/auth/v4/register',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(ClientRegistrationResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Invalid client metadata (RFC 7591 §3.2.2).',
+                                 RegistrationErrorException)
+                    .local_error('401',
+                                 'Registration requires an initial access token and none/invalid'\
+                                  ' was supplied.',
+                                 RegistrationErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded.',
+                                 OauthErrorException)
+                    .local_error('500',
+                                 'Internal error.',
+                                 OauthErrorException))
+        .execute
+    end
+  end
+end

data/lib/walmart_ap_is/apis/base_api.rb

@@ -1,38 +1,38 @@
-# walmart_ap_is
-#
-# This file was automatically generated by APIMATIC v3.0 (
-# https://www.apimatic.io ).
-
-module WalmartApIs
-  # BaseApi.
-  class BaseApi
-    include CoreLibrary
-    attr_accessor :config, :http_call_back
-
-    def self.user_agent
-      'Ruby-SDK/0.0.1 (OS: {os-info}, Engine: {engine}/{engine-version})'
-    end
-
-    def self.user_agent_parameters
-      {
-        '{engine}' => { 'value' => RUBY_ENGINE, 'encode' => false },
-        '{engine-version}' => { 'value' => RUBY_ENGINE_VERSION, 'encode' => false },
-        '{os-info}' => { 'value' => RUBY_PLATFORM, 'encode' => false }
-      }
-    end
-
-    GLOBAL_ERRORS = {
-      'default' => ErrorCase.new
-                            .error_message('HTTP response not OK.')
-                            .exception_type(APIException)
-    }.freeze
-
-    # Initialization constructor.
-    # @param [GlobalConfiguration] global_configuration The instance of GlobalConfiguration.
-    def initialize(global_configuration)
-      @global_configuration = global_configuration
-      @config = @global_configuration.client_configuration
-      @http_call_back = @config.http_callback
+# walmart_ap_is
+#
+# This file was automatically generated by APIMATIC v3.0 (
+# https://www.apimatic.io ).
+
+module WalmartApIs
+  # BaseApi.
+  class BaseApi
+    include CoreLibrary
+    attr_accessor :config, :http_call_back
+
+    def self.user_agent
+      'Ruby-SDK/0.0.5 (OS: {os-info}, Engine: {engine}/{engine-version})'
+    end
+
+    def self.user_agent_parameters
+      {
+        '{engine}' => { 'value' => RUBY_ENGINE, 'encode' => false },
+        '{engine-version}' => { 'value' => RUBY_ENGINE_VERSION, 'encode' => false },
+        '{os-info}' => { 'value' => RUBY_PLATFORM, 'encode' => false }
+      }
+    end
+
+    GLOBAL_ERRORS = {
+      'default' => ErrorCase.new
+                            .error_message('HTTP response not OK.')
+                            .exception_type(APIException)
+    }.freeze
+
+    # Initialization constructor.
+    # @param [GlobalConfiguration] global_configuration The instance of GlobalConfiguration.
+    def initialize(global_configuration)
+      @global_configuration = global_configuration
+      @config = @global_configuration.client_configuration
+      @http_call_back = @config.http_callback
       @api_call = ApiCall.new(@global_configuration)
     end
 
@@ -40,28 +40,28 @@ module WalmartApIs
     # @param [String] http_method The HTTP method to use in the request.
     # @param [String] path The endpoint path to use in the request.
     # @param [String] server The server to extract the base uri for the request.
-    # @return [RequestBuilder] The instance of RequestBuilder.
-    def new_request_builder(http_method, path, server)
-      RequestBuilder.new
-                    .http_method(http_method)
-                    .path(path)
-                    .server(server)
-    end
-
-    # Creates a new instance of the response handler.
-    # @return [ResponseHandler] The instance of ResponseHandler.
-    def new_response_handler
-      ResponseHandler.new
-    end
-
-    # Creates a new instance of the parameter.
-    # @param [String|optional] key The key of the parameter.
-    # @param [Object] value The value of the parameter.
-    # @return [Parameter] The instance of Parameter.
-    def new_parameter(value, key: nil)
-      Parameter.new
-               .key(key)
-               .value(value)
-    end
-  end
-end
+    # @return [RequestBuilder] The instance of RequestBuilder.
+    def new_request_builder(http_method, path, server)
+      RequestBuilder.new
+                    .http_method(http_method)
+                    .path(path)
+                    .server(server)
+    end
+
+    # Creates a new instance of the response handler.
+    # @return [ResponseHandler] The instance of ResponseHandler.
+    def new_response_handler
+      ResponseHandler.new
+    end
+
+    # Creates a new instance of the parameter.
+    # @param [String|optional] key The key of the parameter.
+    # @param [Object] value The value of the parameter.
+    # @return [Parameter] The instance of Parameter.
+    def new_parameter(value, key: nil)
+      Parameter.new
+               .key(key)
+               .value(value)
+    end
+  end
+end

data/lib/walmart_ap_is/apis/catalog_api.rb

@@ -0,0 +1,126 @@
+# walmart_ap_is
+#
+# This file was automatically generated by APIMATIC v3.0 (
+# https://www.apimatic.io ).
+
+module WalmartApIs
+  # CatalogApi
+  class CatalogApi < BaseApi
+    # Search the Walmart Marketplace catalog using keywords, WalmartItemId,
+    # GTIN, UPC, or seller SKU. Returns matching catalog items.
+    # @param [Array[MarketplaceId]] marketplace_ids Required parameter: Walmart
+    # marketplace identifiers. Use WALMART_US for the US marketplace.
+    # @param [String] keywords Optional parameter: Keyword search terms
+    # @param [String] walmart_item_ids Optional parameter: Comma-separated
+    # Walmart Item IDs (14-digit). Max 20.
+    # @param [String] seller_sku Optional parameter: Seller-defined SKU
+    # @param [String] gtin Optional parameter: Global Trade Item Number
+    # (14-digit)
+    # @param [String] upc Optional parameter: Universal Product Code
+    # (12-digit)
+    # @param [Array[IncludedDatum]] included_data Optional parameter: Data
+    # sections to include in the response
+    # @param [Integer] page_size Optional parameter: Number of results per page
+    # (1–20). **Known limitation:** The PIQS keyword search backend hard-caps
+    # results at 40 items per call regardless of this value.
+    # @param [String] page_token Optional parameter: Token for the next page of
+    # results, obtained from `pagination.nextToken` in a previous response.
+    # **Known limitation:** Cursor-based pagination is not currently supported
+    # for keyword search. The PIQS search backend (`/v3/items/walmart/search`)
+    # does not return a `nextCursor` and does not honour this parameter. Results
+    # are capped at 40 items per call. Reserved for future use once PIQS exposes
+    # pagination support.
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def search_catalog_items(marketplace_ids,
+                             keywords: nil,
+                             walmart_item_ids: nil,
+                             seller_sku: nil,
+                             gtin: nil,
+                             upc: nil,
+                             included_data: nil,
+                             page_size: 10,
+                             page_token: nil)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/catalog/v4/items',
+                                     Server::DEFAULT1)
+                   .query_param(new_parameter(marketplace_ids, key: 'marketplaceIds')
+                                 .is_required(true))
+                   .query_param(new_parameter(keywords, key: 'keywords'))
+                   .query_param(new_parameter(walmart_item_ids, key: 'walmartItemIds'))
+                   .query_param(new_parameter(seller_sku, key: 'sellerSku'))
+                   .query_param(new_parameter(gtin, key: 'gtin'))
+                   .query_param(new_parameter(upc, key: 'upc'))
+                   .query_param(new_parameter(included_data, key: 'includedData'))
+                   .query_param(new_parameter(page_size, key: 'pageSize'))
+                   .query_param(new_parameter(page_token, key: 'pageToken'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(ItemSearchResults.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden — insufficient permissions',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Resource not found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # TODO: type endpoint description here
+    # @param [String] walmart_item_id Required parameter: Walmart Item ID
+    # (14-digit numeric identifier)
+    # @param [Array[MarketplaceId]] marketplace_ids Required parameter: Walmart
+    # marketplace identifiers. Use WALMART_US for the US marketplace.
+    # @param [Array[IncludedDatum]] included_data Optional parameter: Data
+    # sections to include in the response
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_catalog_item(walmart_item_id,
+                         marketplace_ids,
+                         included_data: nil)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/catalog/v4/items/{walmartItemId}',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(walmart_item_id, key: 'walmartItemId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .query_param(new_parameter(marketplace_ids, key: 'marketplaceIds')
+                                 .is_required(true))
+                   .query_param(new_parameter(included_data, key: 'includedData'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Item.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Bad Request',
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden — insufficient permissions',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Resource not found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException))
+        .execute
+    end
+  end
+end