terminal-shop 1.7.0 → 1.8.0

data/rbi/lib/terminal-shop/models/view_init_response.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Models
     class ViewInitResponse < TerminalShop::BaseModel
+      # Initial app data.
       sig { returns(TerminalShop::Models::ViewInitResponse::Data) }
       def data
       end
@@ -47,6 +48,7 @@ module TerminalShop
         def cards=(_)
         end
 
+        # The current Terminal shop user's cart.
         sig { returns(TerminalShop::Models::CartAPI) }
         def cart
         end
@@ -71,6 +73,7 @@ module TerminalShop
         def products=(_)
         end
 
+        # A Terminal shop user's profile. (We have users, btw.)
         sig { returns(TerminalShop::Models::ProfileAPI) }
         def profile
         end
@@ -79,6 +82,7 @@ module TerminalShop
         def profile=(_)
         end
 
+        # A Terminal shop user's region.
         sig { returns(Symbol) }
         def region
         end
@@ -106,6 +110,7 @@ module TerminalShop
         def tokens=(_)
         end
 
+        # Initial app data.
         sig do
           params(
             addresses: T::Array[TerminalShop::Models::AddressAPI],

data/rbi/lib/terminal-shop/pooled_net_requester.rbi

@@ -1,20 +1,24 @@
 # typed: strong
 
 module TerminalShop
+  # @api private
   class PooledNetRequester
     RequestShape = T.type_alias do
       {method: Symbol, url: URI::Generic, headers: T::Hash[String, String], body: T.anything, deadline: Float}
     end
 
     class << self
+      # @api private
       sig { params(url: URI::Generic).returns(Net::HTTP) }
       def connect(url)
       end
 
+      # @api private
       sig { params(conn: Net::HTTP, deadline: Float).void }
       def calibrate_socket_timeout(conn, deadline)
       end
 
+      # @api private
       sig do
         params(request: TerminalShop::PooledNetRequester::RequestShape, blk: T.proc.params(arg0: String).void)
           .returns(Net::HTTPGenericRequest)
@@ -23,17 +27,20 @@ module TerminalShop
       end
     end
 
-    sig { params(url: URI::Generic, blk: T.proc.params(arg0: Net::HTTP).void).void }
-    private def with_pool(url, &blk)
+    # @api private
+    sig { params(url: URI::Generic, deadline: Float, blk: T.proc.params(arg0: Net::HTTP).void).void }
+    private def with_pool(url, deadline:, &blk)
     end
 
+    # @api private
     sig do
       params(request: TerminalShop::PooledNetRequester::RequestShape)
-        .returns([Net::HTTPResponse, T::Enumerable[String]])
+        .returns([Integer, Net::HTTPResponse, T::Enumerable[String]])
     end
     def execute(request)
     end
 
+    # @api private
     sig { params(size: Integer).returns(T.attached_class) }
     def self.new(size: Etc.nprocessors)
     end

data/rbi/lib/terminal-shop/request_options.rbi

@@ -1,9 +1,9 @@
 # typed: strong
 
 module TerminalShop
+  # @api private
   module RequestParameters
-    abstract!
-
+    # Options to specify HTTP behaviour for this request.
     sig { returns(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])) }
     def request_options
     end
@@ -15,18 +15,28 @@ module TerminalShop
     def request_options=(_)
     end
 
+    # @api private
     module Converter
+      # @api private
       sig { params(params: T.anything).returns([T.anything, T::Hash[Symbol, T.anything]]) }
       def dump_request(params)
       end
     end
   end
 
+  # Specify HTTP behaviour to use for a specific request. These options supplement
+  #   or override those provided at the client level.
+  #
+  #   When making a request, you can pass an actual {RequestOptions} instance, or
+  #   simply pass a Hash with symbol keys matching the attributes on this class.
   class RequestOptions < TerminalShop::BaseModel
+    # @api private
     sig { params(opts: T.any(T.self_type, T::Hash[Symbol, T.anything])).void }
     def self.validate!(opts)
     end
 
+    # Idempotency key to send with request and all associated retries. Will only be
+    #   sent for write requests.
     sig { returns(T.nilable(String)) }
     def idempotency_key
     end
@@ -35,6 +45,8 @@ module TerminalShop
     def idempotency_key=(_)
     end
 
+    # Extra query params to send with the request. These are `.merge`’d into any
+    #   `query` given at the client level.
     sig { returns(T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))])) }
     def extra_query
     end
@@ -46,6 +58,8 @@ module TerminalShop
     def extra_query=(_)
     end
 
+    # Extra headers to send with the request. These are `.merged`’d into any
+    #   `extra_headers` given at the client level.
     sig { returns(T.nilable(T::Hash[String, T.nilable(String)])) }
     def extra_headers
     end
@@ -57,6 +71,8 @@ module TerminalShop
     def extra_headers=(_)
     end
 
+    # Extra data to send with the request. These are deep merged into any data
+    #   generated as part of the normal request.
     sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
     def extra_body
     end
@@ -65,6 +81,7 @@ module TerminalShop
     def extra_body=(_)
     end
 
+    # Maximum number of retries to attempt after a failed initial request.
     sig { returns(T.nilable(Integer)) }
     def max_retries
     end
@@ -73,6 +90,7 @@ module TerminalShop
     def max_retries=(_)
     end
 
+    # Request timeout in seconds.
     sig { returns(T.nilable(Float)) }
     def timeout
     end
@@ -81,6 +99,7 @@ module TerminalShop
     def timeout=(_)
     end
 
+    # Returns a new instance of RequestOptions.
     sig { params(values: T::Hash[Symbol, T.anything]).returns(T.attached_class) }
     def self.new(values = {})
     end

data/rbi/lib/terminal-shop/resources/address.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Address
+      # Create and add a shipping address to the current user.
       sig do
         params(
           city: String,
@@ -18,18 +19,27 @@ module TerminalShop
           .returns(TerminalShop::Models::AddressCreateResponse)
       end
       def create(
+        # City of the address.
         city:,
+        # ISO 3166-1 alpha-2 country code of the address.
         country:,
+        # The recipient's name.
         name:,
+        # Street of the address.
         street1:,
+        # Zip code of the address.
         zip:,
+        # Phone number of the recipient.
         phone: nil,
+        # Province or state of the address.
         province: nil,
+        # Apartment, suite, etc. of the address.
         street2: nil,
         request_options: {}
       )
       end
 
+      # Get the shipping addresses associated with the current user.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::AddressListResponse)
@@ -37,6 +47,7 @@ module TerminalShop
       def list(request_options: {})
       end
 
+      # Delete a shipping address from the current user.
       sig do
         params(
           id: String,
@@ -44,9 +55,14 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::AddressDeleteResponse)
       end
-      def delete(id, request_options: {})
+      def delete(
+        # ID of the shipping address to delete.
+        id,
+        request_options: {}
+      )
       end
 
+      # Get the shipping address with the given ID.
       sig do
         params(
           id: String,
@@ -54,7 +70,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::AddressGetResponse)
       end
-      def get(id, request_options: {})
+      def get(
+        # ID of the shipping address to get.
+        id,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/app.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class App
+      # Create an app.
       sig do
         params(
           name: String,
@@ -14,6 +15,7 @@ module TerminalShop
       def create(name:, redirect_uri:, request_options: {})
       end
 
+      # List the current user's registered apps.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::AppListResponse)
@@ -21,6 +23,7 @@ module TerminalShop
       def list(request_options: {})
       end
 
+      # Delete the app with the given ID.
       sig do
         params(
           id: String,
@@ -28,9 +31,14 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::AppDeleteResponse)
       end
-      def delete(id, request_options: {})
+      def delete(
+        # ID of the app to delete.
+        id,
+        request_options: {}
+      )
       end
 
+      # Get the app with the given ID.
       sig do
         params(
           id: String,
@@ -38,7 +46,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::AppGetResponse)
       end
-      def get(id, request_options: {})
+      def get(
+        # ID of the app to get.
+        id,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/card.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Card
+      # Attach a credit card (tokenized via Stripe) to the current user.
       sig do
         params(
           token: String,
@@ -10,9 +11,15 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::CardCreateResponse)
       end
-      def create(token:, request_options: {})
+      def create(
+        # Stripe card token. Learn how to
+        #   [create one here](https://docs.stripe.com/api/tokens/create_card).
+        token:,
+        request_options: {}
+      )
       end
 
+      # List the credit cards associated with the current user.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::CardListResponse)
@@ -20,6 +27,7 @@ module TerminalShop
       def list(request_options: {})
       end
 
+      # Delete a credit card associated with the current user.
       sig do
         params(
           id: String,
@@ -27,9 +35,15 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::CardDeleteResponse)
       end
-      def delete(id, request_options: {})
+      def delete(
+        # ID of the card to delete.
+        id,
+        request_options: {}
+      )
       end
 
+      # Create a temporary URL for collecting credit card information for the current
+      #   user.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::CardCollectResponse)
@@ -37,6 +51,7 @@ module TerminalShop
       def collect(request_options: {})
       end
 
+      # Get a credit card by ID associated with the current user.
       sig do
         params(
           id: String,
@@ -44,7 +59,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::CardGetResponse)
       end
-      def get(id, request_options: {})
+      def get(
+        # ID of the card to get.
+        id,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/cart.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Cart
+      # Clear the current user's cart.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::CartClearResponse)
@@ -10,6 +11,7 @@ module TerminalShop
       def clear(request_options: {})
       end
 
+      # Convert the current user's cart to an order.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::CartConvertResponse)
@@ -17,6 +19,7 @@ module TerminalShop
       def convert(request_options: {})
       end
 
+      # Get the current user's cart.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::CartGetResponse)
@@ -24,6 +27,7 @@ module TerminalShop
       def get(request_options: {})
       end
 
+      # Set the shipping address for the current user's cart.
       sig do
         params(
           address_id: String,
@@ -31,9 +35,14 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::CartSetAddressResponse)
       end
-      def set_address(address_id:, request_options: {})
+      def set_address(
+        # ID of the shipping address to set for the current user's cart.
+        address_id:,
+        request_options: {}
+      )
       end
 
+      # Set the credit card for the current user's cart.
       sig do
         params(
           card_id: String,
@@ -41,9 +50,14 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::CartSetCardResponse)
       end
-      def set_card(card_id:, request_options: {})
+      def set_card(
+        # ID of the credit card to set for the current user's cart.
+        card_id:,
+        request_options: {}
+      )
       end
 
+      # Add an item to the current user's cart.
       sig do
         params(
           product_variant_id: String,
@@ -52,7 +66,13 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::CartSetItemResponse)
       end
-      def set_item(product_variant_id:, quantity:, request_options: {})
+      def set_item(
+        # ID of the product variant to add to the cart.
+        product_variant_id:,
+        # Quantity of the item to add to the cart.
+        quantity:,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/email.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Email
+      # Subscribe to email updates from Terminal.
       sig do
         params(
           email: String,
@@ -10,7 +11,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::EmailCreateResponse)
       end
-      def create(email:, request_options: {})
+      def create(
+        # Email address to subscribe to Terminal updates with.
+        email:,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/order.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Order
+      # Create an order without a cart. The order will be placed immediately.
       sig do
         params(
           address_id: String,
@@ -12,9 +13,18 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::OrderCreateResponse)
       end
-      def create(address_id:, card_id:, variants:, request_options: {})
+      def create(
+        # Shipping address ID.
+        address_id:,
+        # Card ID.
+        card_id:,
+        # Product variants to include in the order, along with their quantities.
+        variants:,
+        request_options: {}
+      )
       end
 
+      # List the orders associated with the current user.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::OrderListResponse)
@@ -22,6 +32,7 @@ module TerminalShop
       def list(request_options: {})
       end
 
+      # Get the order with the given ID.
       sig do
         params(
           id: String,
@@ -29,7 +40,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::OrderGetResponse)
       end
-      def get(id, request_options: {})
+      def get(
+        # ID of the order to get.
+        id,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/product.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Product
+      # List all products for sale in the Terminal shop.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::ProductListResponse)
@@ -10,6 +11,7 @@ module TerminalShop
       def list(request_options: {})
       end
 
+      # Get a product by ID from the Terminal shop.
       sig do
         params(
           id: String,
@@ -17,7 +19,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::ProductGetResponse)
       end
-      def get(id, request_options: {})
+      def get(
+        # ID of the product to get.
+        id,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/profile.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Profile
+      # Update the current user's profile.
       sig do
         params(
           email: String,
@@ -14,6 +15,7 @@ module TerminalShop
       def update(email:, name:, request_options: {})
       end
 
+      # Get the current user's profile.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::ProfileMeResponse)

data/rbi/lib/terminal-shop/resources/subscription.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Subscription
+      # Create a subscription for the current user.
       sig do
         params(
           id: String,
@@ -20,17 +21,25 @@ module TerminalShop
           .returns(TerminalShop::Models::SubscriptionCreateResponse)
       end
       def create(
+        # Unique object identifier. The format and length of IDs may change over time.
         id:,
+        # ID of the shipping address used for the subscription.
         address_id:,
+        # ID of the card used for the subscription.
         card_id:,
+        # ID of the product variant being subscribed to.
         product_variant_id:,
+        # Quantity of the subscription.
         quantity:,
+        # Next shipment and billing date for the subscription.
         next_: nil,
+        # Schedule of the subscription.
         schedule: nil,
         request_options: {}
       )
       end
 
+      # List the subscriptions associated with the current user.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::SubscriptionListResponse)
@@ -38,6 +47,7 @@ module TerminalShop
       def list(request_options: {})
       end
 
+      # Cancel a subscription for the current user.
       sig do
         params(
           id: String,
@@ -45,9 +55,14 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::SubscriptionDeleteResponse)
       end
-      def delete(id, request_options: {})
+      def delete(
+        # ID of the subscription to cancel.
+        id,
+        request_options: {}
+      )
       end
 
+      # Get the subscription with the given ID.
       sig do
         params(
           id: String,
@@ -55,7 +70,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::SubscriptionGetResponse)
       end
-      def get(id, request_options: {})
+      def get(
+        # ID of the subscription to get.
+        id,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/token.rbi

@@ -3,6 +3,7 @@
 module TerminalShop
   module Resources
     class Token
+      # Create a personal access token.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::TokenCreateResponse)
@@ -10,6 +11,7 @@ module TerminalShop
       def create(request_options: {})
       end
 
+      # List the current user's personal access tokens.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::TokenListResponse)
@@ -17,6 +19,7 @@ module TerminalShop
       def list(request_options: {})
       end
 
+      # Delete the personal access token with the given ID.
       sig do
         params(
           id: String,
@@ -24,9 +27,14 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::TokenDeleteResponse)
       end
-      def delete(id, request_options: {})
+      def delete(
+        # ID of the personal token to delete.
+        id,
+        request_options: {}
+      )
       end
 
+      # Get the personal access token with the given ID.
       sig do
         params(
           id: String,
@@ -34,7 +42,11 @@ module TerminalShop
         )
           .returns(TerminalShop::Models::TokenGetResponse)
       end
-      def get(id, request_options: {})
+      def get(
+        # ID of the personal token to get.
+        id,
+        request_options: {}
+      )
       end
 
       sig { params(client: TerminalShop::Client).returns(T.attached_class) }

data/rbi/lib/terminal-shop/resources/view.rbi

@@ -3,6 +3,8 @@
 module TerminalShop
   module Resources
     class View
+      # Get initial app data, including user, products, cart, addresses, cards,
+      #   subscriptions, and orders.
       sig do
         params(request_options: T.nilable(T.any(TerminalShop::RequestOptions, T::Hash[Symbol, T.anything])))
           .returns(TerminalShop::Models::ViewInitResponse)