usps-ruby-client 0.1.0 → 0.1.3

data/lib/usps/api/endpoints/scan.rb

@@ -6,68 +6,37 @@ module Usps
 	module Api
 		module Endpoints
 			module SCAN
-				#
-				# SCAN API
-				#
 				# The SCAN API allows integrators to consolidate
 				# multiple domestic and international labels and custom forms through one
 				# Electronic File Number (EFN) and physical SCAN Form (PS Form 5630 or 3152). The
 				# API operates as follows:
-				#
-				# @option option [(Alias)] :SCANRequest (Required)
-				# - API=SCAN
-				#   @option option [(Group)] :Option (Optional)
-				#   - Groups form information
-				#     @option option [String] :Form (Optional)
-				#     - Designates desired label option selected by customer. Enter one of the valid entries: ‘3152’ generates PS Form 3152. ‘5630’ generates PS Form 5630. For example: <Form>3152</Form>
-				#     @option option [String] :FromName (Required)
-				#     - Name of sender. Example: <FromName>Joe Smith</FromName>
-				#     @option option [String] :FromFirm (Optional)
-				#     - Company name. Example: <FromFirm>ABC Corp.</FromFirm>
-				#     @option option [String] :FromAddress1 (Optional)
-				#     - From address line 1. Denote apartment or suite number. Example: <FromAddress1>Apt. 3C</FromAddress1>
-				#     @option option [String] :FromAddress2 (Required)
-				#     - From address line 2. Denote street/structure number. Example: <FromAddress2>475 L’Enfant Plaza SW</FromAddress2>
-				#     @option option [String] :FromCity (Required)
-				#     - From city. Example: <FromCity>Greenbelt</FromCity>
-				#     @option option [String] :FromState (Required)
-				#     - From state. Example: <FromState>MD</FromState>
-				#     @option option [String] :FromZip5 (Required)
-				#     - From ZIP Code. Must be a valid ZIP5 Code. Example: <FromZip5>20770</FromZip5>
-				#     @option option [String] :FromZip4 (Optional)
-				#     - From ZIP Code+4. Example: <FromZip4>1234</FromZip4>
-				#     @option option [(Group)] :Shipment (Optional)
-				#     - Groups shipment information
-				#       @option option [(Group)] :PackageDetail (Optional)
-				#       - Groups package detail information
-				#         @option option [String] :PkgBarcode (Required)
-				#         - Individual package barcodes. Example: <PkgBarcode>42020260910180521390702413570 </PkgBarcode> Note: The SCAN API can contain no more than 1,000 package barcodes in a single request. If exceeded, 'Total PackageDetail items exceeded 1000.’ error will return”
-				#         @option option [(Group)] :SpecialService (Optional)
-				#         - FOR FUTURE USE. Groups extra service information.
-				#           @option option [String] :SpcServCode (Required)
-				#           - FOR FUTURE USE. If present, must be <SpcServFee>. From Extra Service Code table. Example: <SpcServCode>01</SpcServCode>
-				#           @option option [String] :SpcServFee (Required)
-				#           - FOR FUTURE USE. Fee for Extra Service. Example: <SpcServFee>00275</SpcServFee>
-				#           @option option [String] :EMail (Optional)
-				#           - FOR FUTURE USE. Email address of acceptance scan event recipient. Example: <EMail>john.smith@abc.com</EMail>
-				#           @option option [Boolean] :CloseManifest (Optional)
-				#           - Used to include all labels for the submitted UserID. There are two values: “ALL” will close all labels for the submitted USERID. “SHIPDATE” will close all the labels for the submitted USERID that have the <Shipdate> tag matching the value in the <MailDate> tag. Note: When <CloseManifest> is indicated in the request, the following two response fields are eligible to return if conditions are met: · <MaxPackagesExceeded> · <MaxLabelsExceeded>
-				#           @option option [String] :MailDate (Required)
-				#           - Date of mailing/Carrier Pickup. This denotes date mail to be tendered to Postal Service. YYYYMMDD format. Example: <MailDate>20060103</MailDate>
-				#           @option option [String] :MailTime (Required)
-				#           - Time of mailing/Carrier Pickup. This is an approximation. This denotes time of mail to be tendered to Postal Service. HHMMSS (24 hour) format. Example: <MailTime>143000</MailTime>
-				#           @option option [String] :EntryFacility (Required)
-				#           - ZIP Code of Postal Service facility. Populate/required only if different from <FromZip5>. Example: <EntryFacility>07067</EntryFacility>
-				#           @option option [String] :ImageType (Required)
-				#           - The form image format desired. Enter one of the valid entries: Example: <ImageType>TIF</ImageType>
-				#           @option option [String] :CustomerRefNo (Optional)
-				#           - Arbitrary number for customers own tracking or inventory systems, does not print to form or manifest with Product Tracking. May be any combination of alpha and numeric characters, up to a maximum of 30. Example: <CustomerRefNo>123456</CustomerRefNo>
-				#           @option option [Boolean] :CarrierPickup (Optional)
-				#           - FOR FUTURE USE.
-
-				#
-				# @see 
-				def scan(options = {})
+				# @param [Hash] options
+				# @option options [required, Hash] scan_request API=SCAN
+				#  * *:option* (Hash) — Groups form information
+				#    * *:form* (String) — Designates desired label option selected by customer. Enter one of the valid entries: ‘3152’ generates PS Form 3152. ‘5630’ generates PS Form 5630. For example: <Form>3152</Form>
+				#    * *:from_name* (required, String) — Name of sender. Example: <FromName>Joe Smith</FromName>
+				#    * *:from_firm* (String) — Company name. Example: <FromFirm>ABC Corp.</FromFirm>
+				#    * *:from_address1* (String) — From address line 1. Denote apartment or suite number. Example: <FromAddress1>Apt. 3C</FromAddress1>
+				#    * *:from_address2* (required, String) — From address line 2. Denote street/structure number. Example: <FromAddress2>475 L’Enfant Plaza SW</FromAddress2>
+				#    * *:from_city* (required, String) — From city. Example: <FromCity>Greenbelt</FromCity>
+				#    * *:from_state* (required, String) — From state. Example: <FromState>MD</FromState>
+				#    * *:from_zip5* (required, String) — From ZIP Code. Must be a valid ZIP5 Code. Example: <FromZip5>20770</FromZip5>
+				#    * *:from_zip4* (String) — From ZIP Code+4. Example: <FromZip4>1234</FromZip4>
+				#    * *:shipment* (Hash) — Groups shipment information
+				#      * *:package_detail* (Hash) — Groups package detail information
+				#        * *:pkg_barcode* (required, String) — Individual package barcodes. Example: <PkgBarcode>42020260910180521390702413570 </PkgBarcode> Note: The SCAN API can contain no more than 1,000 package barcodes in a single request. If exceeded, 'Total PackageDetail items exceeded 1000.’ error will return”
+				#        * *:special_service* (Hash) — FOR FUTURE USE. Groups extra service information.
+				#          * *:spc_serv_code* (required, String) — FOR FUTURE USE. If present, must be <SpcServFee>. From Extra Service Code table. Example: <SpcServCode>01</SpcServCode>
+				#          * *:spc_serv_fee* (required, String) — FOR FUTURE USE. Fee for Extra Service. Example: <SpcServFee>00275</SpcServFee>
+				#          * *:e_mail* (String) — FOR FUTURE USE. Email address of acceptance scan event recipient. Example: <EMail>john.smith@abc.com</EMail>
+				#          * *:close_manifest* (Boolean) — Used to include all labels for the submitted UserID. There are two values: “ALL” will close all labels for the submitted USERID. “SHIPDATE” will close all the labels for the submitted USERID that have the <Shipdate> tag matching the value in the <MailDate> tag. Note: When <CloseManifest> is indicated in the request, the following two response fields are eligible to return if conditions are met: · <MaxPackagesExceeded> · <MaxLabelsExceeded>
+				#          * *:mail_date* (required, String) — Date of mailing/Carrier Pickup. This denotes date mail to be tendered to Postal Service. YYYYMMDD format. Example: <MailDate>20060103</MailDate>
+				#          * *:mail_time* (required, String) — Time of mailing/Carrier Pickup. This is an approximation. This denotes time of mail to be tendered to Postal Service. HHMMSS (24 hour) format. Example: <MailTime>143000</MailTime>
+				#          * *:entry_facility* (required, String) — ZIP Code of Postal Service facility. Populate/required only if different from <FromZip5>. Example: <EntryFacility>07067</EntryFacility>
+				#          * *:image_type* (required, String) — The form image format desired. Enter one of the valid entries: Example: <ImageType>TIF</ImageType>
+				#          * *:customer_ref_no* (String) — Arbitrary number for customers own tracking or inventory systems, does not print to form or manifest with Product Tracking. May be any combination of alpha and numeric characters, up to a maximum of 30. Example: <CustomerRefNo>123456</CustomerRefNo>
+				#          * *:carrier_pickup* (Boolean) — FOR FUTURE USE.
+def scan(options = {})
 					throw ArgumentError.new('Required arguments :scan_request missing') if options[:scan_request].nil?
 
 					request = build_request(:scan, options)

data/lib/usps/api/endpoints/track_v2.rb

@@ -6,9 +6,6 @@ module Usps
 	module Api
 		module Endpoints
 			module TrackV2
-				#
-				# Package Tracking
-				#
 				# The Package Tracking “Fields” API is similar
 				# to the Package Track API
 				# except for the request fields, API name, and the return information. Data
@@ -16,18 +13,15 @@ module Usps
 				# information is broken down into fields instead of having only one line of text.
 				# Up to 10 tracking IDs may be contained in each API request to the Web Tools
 				# server.
-				#
-				# @option option [(Alias)] :TrackFieldRequest (Required)
-				#   @option option [Integer] :Revision (Required)
-				#   @option option [String] :ClientIp (Optional)
-				#   @option option [String] :SourceId (Required)
-				#   @option option [String] :TrackID (Required)
-				#   @option option [String] :DestinationZipCode (Optional)
-				#   @option option [String] :MailingDate (Optional)
-
-				#
-				# @see 
-				def track_v2(options = {})
+				# @param [Hash] options
+				# @option options [required, Hash] track_field_request 
+				#  * *:revision* (required, Integer)
+				#  * *:client_ip* (String)
+				#  * *:source_id* (required, String)
+				#  * *:track_id* (required, String)
+				#  * *:destination_zip_code* (String)
+				#  * *:mailing_date* (String)
+def track_v2(options = {})
 					throw ArgumentError.new('Required arguments :track_field_request missing') if options[:track_field_request].nil?
 					throw ArgumentError.new('Required arguments :track_field_request, :revision missing') if options[:track_field_request][:revision].nil?
 					throw ArgumentError.new('Required arguments :track_field_request, :source_id missing') if options[:track_field_request][:source_id].nil?

data/lib/usps/api/endpoints/usps_returns_label.rb

@@ -6,9 +6,6 @@ module Usps
 	module Api
 		module Endpoints
 			module USPSReturnsLabel
-				#
-				# USPS Returns Label API
-				#
 				# The Web Tools USPS Returns Label API enables
 				# customers to receive USPS Returns service labels which are processed using the
 				# new automated returns process via Package Platform. USPS Returns service account holders will pay
@@ -18,73 +15,39 @@ module Usps
 				# to request USPS Returns service labels for
 				# items that can be mailed using First-Class Package Return Service, Priority Mail Return Service, and Ground Return Service. For
 				# additional USPS Returns service details, reference: https://www.federalregister.gov/documents/2020/02/25/2020-03170/usps-returns-service.
-				#
-				# @option option [(Alias)] :USPSReturnsLabelRequest (Required)
-				# - Used with API=USPSReturnsLabel
-				#   @option option [String] :Option (Optional)
-				#   - For future use.
-				#   @option option [String] :Revision (Optional)
-				#   - For future use. Used to indicate API version.
-				#   @option option [(Group)] :ImageParameters (Required)
-				#   - Group containing all request parameters pertaining to the Label Image generation.
-				#     @option option [String] :ImageType (Required)
-				#     - Label Image Type. For example: <ImageType>PDF</ImageType>
-				#     @option option [Boolean] :SeparateReceiptPage (Optional)
-				#     - Flag to request a Separate Receipt Image. Enter “true” if you want receipt returned on a separate page – this will return label in <LabelImage> tag and receipt in <ReceiptImage> tag. For example: <SeparateReceiptPage>true</SeparateReceiptPage> Note: If not specified, receipt will return on same page as returns label. Response will contain a single <LabelImage> tag containing label and receipt on the same page.
-				#     @option option [String] :CustomerFirstName (Optional)
-				#     - First Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.
-				#     @option option [String] :CustomerLastName (Optional)
-				#     - Last Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.
-				#     @option option [String] :CustomerFirm (Optional)
-				#     - Firm Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirm> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.
-				#     @option option [String] :CustomerAddress1 (Optional)
-				#     - Secondary address unit designator and number (such as an apartment or suite number). For example: “APT 202” or “STE 100” etc. Note: This tag must be included in the request, even if the value is null, to return a successful response. For addresses that do not require secondary information, integrators should include “<CustomerAddress1/>” in the request.
-				#     @option option [String] :CustomerAddress2 (Required)
-				#     - Address of customer returning the package. (Primary Street address). For example: <CustomerAddress2>123 Main St.</CustomerAddress2>
-				#     @option option [String] :CustomerCity (Required)
-				#     - City of customer returning the package.
-				#     @option option [String] :CustomerState (Required)
-				#     - State of customer returning the package. Value should be passed as two-letter state abbreviation. For example: <CustomerState>DC</CustomerState>
-				#     @option option [String] :CustomerZip5 (Required)
-				#     - ZIP Code of customer returning the package.
-				#     @option option [String] :CustomerZip4 (Optional)
-				#     - ZIP+4 Code of customer returning the package.
-				#     @option option [String] :POZipCode (Optional)
-				#     - ZIP Code of Post Office or collection box where item is mailed. May be different than CustomerZip5. This tag will take precedence over CustomerZip5 when provided. For example: <POZipCode>20770</ POZipCode>
-				#     @option option [Boolean] :AllowNonCleansedOriginAddr (Optional)
-				#     - Allows Non-Validated Origin Street Address. Enter “true” to bypass street address validation failures/errors or “false” if only validated addresses should be allowed. Note: Integrators are recommended to always use “false” to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when “true” is indicated to allow label creation which could impact delivery. The <AllowNonCleansedOriginAddr> excludes City, State, and ZIP Code which must be valid for a successful response. Reference https://pe.usps.com/text/pub28/28c2_001.htm.
-				#     @option option [Integer] :WeightInOunces (Optional)
-				#     - Package weight used to calculate postage. Items must weigh 70 pounds (1120 ounces) or less. For example: <WeightInOunces>80</ WeightInOunces> Note: If weight not supplied, 4oz used.
-				#     @option option [String] :ServiceType (Required)
-				#     - Enter one of the valid Mail Service entries: “PRIORITY” for Priority Mail Return Service. “FIRST CLASS” for First-Class Package Return Service. “GROUND” for Ground Return Service.
-				#     @option option [Decimal] :Width (Optional)
-				#     - Value must be numeric. Units are inches. For example: <Width>5.5</ Width> If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm
-				#     @option option [Decimal] :Length (Optional)
-				#     - Value must be numeric. Units are inches. Length should be longest dimension when compared to Width and Height values supplied. For example: <Length>11</Length> If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm
-				#     @option option [Decimal] :Height (Optional)
-				#     - Value must be numeric. Units are inches. For example: <Height>7</Height> If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm
-				#     @option option [Decimal] :Girth (Optional)
-				#     - Note: Girth is required only for a non-rectangular package. For rectangular packages, girth must be left blank. Value must be numeric. Units are inches. Girth is distance around the thickest part of package (perpendicular to the length). For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail https://pe.usps.com/text/dmm300/index.htm. For example: <Girth>25</Girth> Note: If partial dimensions are provided, an error response will return. (i.e. Length, Width, and Height must all be supplied with Girth).
-				#     @option option [Boolean] :Machinable (Optional)
-				#     - Indicates if packaging is Machinable. Used to calculate postage. For example: <Machinable>true</Machinable>
-				#     @option option [String] :ShipDate (Optional)
-				#     - Date Package Will Be Mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in either format: dd-mmm-yyyy, such as 14-Feb-2020, or mm/dd/ yyyy, such as 02/14/2020. If not provided, current day will be used as a basis for delivery date calculations. For example: <ShipDate>02/14/2011</ShipDate>
-				#     @option option [String] :SenderName (Optional)
-				#     - Used for the USPS Tracking email. Indicates the name of the person or company sending the USPS tracking email notification. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
-				#     @option option [String] :SenderEMail (Optional)
-				#     - Used for the USPS Tracking email. Indicates the email address of sender used for USPS tracking email notification. Valid email addresses must be used. Note: <RecipientEMail> must be populated to generate USPS tracking email notification. If <SenderEMail> provided without <RecipientEMail>, USPS tracking email notification will not be generated. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
-				#     @option option [String] :RecipientName (Optional)
-				#     - Used for the USPS Tracking email. Indicates the name of the person or company receiving the USPS tracking email notification. If recipient name not provided, email will be addressed to <RecipientEMail> value provided. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
-				#     @option option [String] :RecipientEMail (Optional)
-				#     - Required to generate the USPS Tracking email. Indicates email address of recipient receiving the USPS tracking email notification. Valid email addresses must be used. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
-				#     @option option [(Group)] :ExtraServices (Optional)
-				#     - Groups extra services elements
-				#       @option option [Service Name] :ExtraService (Optional)
-				#       - [{"Service Name"=>"Signature Confirmation Electronic", "Service ID"=>"156"}]
-
-				#
-				# @see 
-				def usps_returns_label(options = {})
+				# @param [Hash] options
+				# @option options [required, Hash] usps_returns_label_request Used with API=USPSReturnsLabel
+				#  * *:option* (String) — For future use.
+				#  * *:revision* (String) — For future use. Used to indicate API version.
+				#  * *:image_parameters* (required, Hash) — Group containing all request parameters pertaining to the Label Image generation.
+				#    * *:image_type* (required, String) — Label Image Type. For example: <ImageType>PDF</ImageType>
+				#    * *:separate_receipt_page* (Boolean) — Flag to request a Separate Receipt Image. Enter “true” if you want receipt returned on a separate page – this will return label in <LabelImage> tag and receipt in <ReceiptImage> tag. For example: <SeparateReceiptPage>true</SeparateReceiptPage> Note: If not specified, receipt will return on same page as returns label. Response will contain a single <LabelImage> tag containing label and receipt on the same page.
+				#    * *:customer_first_name* (String) — First Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.
+				#    * *:customer_last_name* (String) — Last Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.
+				#    * *:customer_firm* (String) — Firm Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirm> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.
+				#    * *:customer_address1* (String) — Secondary address unit designator and number (such as an apartment or suite number). For example: “APT 202” or “STE 100” etc. Note: This tag must be included in the request, even if the value is null, to return a successful response. For addresses that do not require secondary information, integrators should include “<CustomerAddress1/>” in the request.
+				#    * *:customer_address2* (required, String) — Address of customer returning the package. (Primary Street address). For example: <CustomerAddress2>123 Main St.</CustomerAddress2>
+				#    * *:customer_city* (required, String) — City of customer returning the package.
+				#    * *:customer_state* (required, String) — State of customer returning the package. Value should be passed as two-letter state abbreviation. For example: <CustomerState>DC</CustomerState>
+				#    * *:customer_zip5* (required, String) — ZIP Code of customer returning the package.
+				#    * *:customer_zip4* (String) — ZIP+4 Code of customer returning the package.
+				#    * *:po_zip_code* (String) — ZIP Code of Post Office or collection box where item is mailed. May be different than CustomerZip5. This tag will take precedence over CustomerZip5 when provided. For example: <POZipCode>20770</ POZipCode>
+				#    * *:allow_non_cleansed_origin_addr* (Boolean) — Allows Non-Validated Origin Street Address. Enter “true” to bypass street address validation failures/errors or “false” if only validated addresses should be allowed. Note: Integrators are recommended to always use “false” to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when “true” is indicated to allow label creation which could impact delivery. The <AllowNonCleansedOriginAddr> excludes City, State, and ZIP Code which must be valid for a successful response. Reference https://pe.usps.com/text/pub28/28c2_001.htm.
+				#    * *:weight_in_ounces* (Integer) — Package weight used to calculate postage. Items must weigh 70 pounds (1120 ounces) or less. For example: <WeightInOunces>80</ WeightInOunces> Note: If weight not supplied, 4oz used.
+				#    * *:service_type* (required, String) — Enter one of the valid Mail Service entries: “PRIORITY” for Priority Mail Return Service. “FIRST CLASS” for First-Class Package Return Service. “GROUND” for Ground Return Service.
+				#    * *:width* (Decimal) — Value must be numeric. Units are inches. For example: <Width>5.5</ Width> If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm
+				#    * *:length* (Decimal) — Value must be numeric. Units are inches. Length should be longest dimension when compared to Width and Height values supplied. For example: <Length>11</Length> If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm
+				#    * *:height* (Decimal) — Value must be numeric. Units are inches. For example: <Height>7</Height> If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. https://pe.usps.com/text/dmm300/index.htm
+				#    * *:girth* (Decimal) — Note: Girth is required only for a non-rectangular package. For rectangular packages, girth must be left blank. Value must be numeric. Units are inches. Girth is distance around the thickest part of package (perpendicular to the length). For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail https://pe.usps.com/text/dmm300/index.htm. For example: <Girth>25</Girth> Note: If partial dimensions are provided, an error response will return. (i.e. Length, Width, and Height must all be supplied with Girth).
+				#    * *:machinable* (Boolean) — Indicates if packaging is Machinable. Used to calculate postage. For example: <Machinable>true</Machinable>
+				#    * *:ship_date* (String) — Date Package Will Be Mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in either format: dd-mmm-yyyy, such as 14-Feb-2020, or mm/dd/ yyyy, such as 02/14/2020. If not provided, current day will be used as a basis for delivery date calculations. For example: <ShipDate>02/14/2011</ShipDate>
+				#    * *:sender_name* (String) — Used for the USPS Tracking email. Indicates the name of the person or company sending the USPS tracking email notification. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
+				#    * *:sender_e_mail* (String) — Used for the USPS Tracking email. Indicates the email address of sender used for USPS tracking email notification. Valid email addresses must be used. Note: <RecipientEMail> must be populated to generate USPS tracking email notification. If <SenderEMail> provided without <RecipientEMail>, USPS tracking email notification will not be generated. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
+				#    * *:recipient_name* (String) — Used for the USPS Tracking email. Indicates the name of the person or company receiving the USPS tracking email notification. If recipient name not provided, email will be addressed to <RecipientEMail> value provided. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
+				#    * *:recipient_e_mail* (String) — Required to generate the USPS Tracking email. Indicates email address of recipient receiving the USPS tracking email notification. Valid email addresses must be used. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.
+				#    * *:extra_services* (Hash) — Groups extra services elements
+				#      * *:extra_service* (Service Name) — [{"Service Name"=>"Signature Confirmation Electronic", "Service ID"=>"156"}]
+def usps_returns_label(options = {})
 					throw ArgumentError.new('Required arguments :usps_returns_label_request missing') if options[:usps_returns_label_request].nil?
 					throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters missing') if options[:usps_returns_label_request][:image_parameters].nil?
 					throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters, :image_type missing') if options[:usps_returns_label_request][:image_parameters][:image_type].nil?

data/lib/usps/api/endpoints/verify.rb

@@ -6,36 +6,19 @@ module Usps
 	module Api
 		module Endpoints
 			module Verify
-				#
-				# Address Validation API
-				#
-				#
-				# @option option [(Alias)] :AddressValidateRequest (Required)
-				# - API = AddressValidateRequest
-				#   @option option [String] :Revision (Required)
-				#   - Integer value used to return of all available response fields. Set this value to 1 to return all currently documented response fields. Example: Revision>1</Revision>
-				#   @option option [(group)] :Address (Required)
-				#   - Up to 5 address verifications can be included per transaction.
-				#     @option option [String] :FirmName (Optional)
-				#     - Firm Name Example:<FirmName>XYZ Corp.</FirmName>
-				#     @option option [String] :Address1 (Optional)
-				#     - Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)
-				#     @option option [String] :Address2 (Required)
-				#     - Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
-				#     @option option [String] :City (Optional)
-				#     - City name of the destination address.
-				#     @option option [String] :State (Optional)
-				#     - Two-character state code of the destination address.
-				#     @option option [String] :Urbanization (Optional)
-				#     - Urbanization. For Puerto Rico addresses only.
-				#     @option option [String] :Zip5 (Optional)
-				#     - Destination 5-digit ZIP Code. Numeric values (0-9) only. If International, all zeroes.
-				#     @option option [String] :Zip4 (Optional)
-				#     - Destination ZIP+4 Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
-
-				#
-				# @see 
-				def verify(options = {})
+				# @param [Hash] options
+				# @option options [required, Hash] address_validate_request API = AddressValidateRequest
+				#  * *:revision* (required, String) — Integer value used to return of all available response fields. Set this value to 1 to return all currently documented response fields. Example: Revision>1</Revision>
+				#  * *:address* (required, Hash) — Up to 5 address verifications can be included per transaction.
+				#    * *:firm_name* (String) — Firm Name Example:<FirmName>XYZ Corp.</FirmName>
+				#    * *:address1* (String) — Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)
+				#    * *:address2* (required, String) — Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
+				#    * *:city* (String) — City name of the destination address.
+				#    * *:state* (String) — Two-character state code of the destination address.
+				#    * *:urbanization* (String) — Urbanization. For Puerto Rico addresses only.
+				#    * *:zip5* (String) — Destination 5-digit ZIP Code. Numeric values (0-9) only. If International, all zeroes.
+				#    * *:zip4* (String) — Destination ZIP+4 Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
+def verify(options = {})
 					throw ArgumentError.new('Required arguments :address_validate_request missing') if options[:address_validate_request].nil?
 					throw ArgumentError.new('Required arguments :address_validate_request, :revision missing') if options[:address_validate_request][:revision].nil?
 					throw ArgumentError.new('Required arguments :address_validate_request, :address missing') if options[:address_validate_request][:address].nil?

data/lib/usps/api/endpoints/zip_code_lookup.rb

@@ -6,35 +6,21 @@ module Usps
 	module Api
 		module Endpoints
 			module ZipCodeLookup
-				#
-				# ZIP Code Lookup API
-				#
 				# The ZipCodeLookup API, which returns the ZIP Code and ZIP
 				# Code + 4 corresponding to the given address, city, and state (use USPS state
 				# abbreviations). The ZipCodeLookup API processes up to
 				# five lookups per request.
-				#
-				# @option option [(Alias)] :ZipCodeLookupRequest (Required)
-				# - API = ZipCodeLookupRequest
-				#   @option option [(Group)] :Address (Optional)
-				#     @option option [String] :FirmName (Optional)
-				#     - Up to 5 address verifications can be included per transaction.
-				#     @option option [String] :Address1 (Optional)
-				#     - Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)
-				#     @option option [String] :Address2 (Required)
-				#     - Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
-				#     @option option [String] :City (Optional)
-				#     - City name of the destination address. Field is required, unless a verified 11-digit DPV is provided for the mail piece.
-				#     @option option [String] :State (Optional)
-				#     - Two-character state code of the destination address.
-				#     @option option [String] :Zip5 (Optional)
-				#     - Destination 5-digit ZIP Code. Must be 5-digits. Numeric values (0-9) only. If International, all zeroes.
-				#     @option option [String] :Zip4 (Optional)
-				#     - Destination ZIP+4. Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
-
-				#
-				# @see 
-				def zip_code_lookup(options = {})
+				# @param [Hash] options
+				# @option options [required, Hash] zip_code_lookup_request API = ZipCodeLookupRequest
+				#  * *:address* (Hash) — 
+				#    * *:firm_name* (String) — Up to 5 address verifications can be included per transaction.
+				#    * *:address1* (String) — Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)
+				#    * *:address2* (required, String) — Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
+				#    * *:city* (String) — City name of the destination address. Field is required, unless a verified 11-digit DPV is provided for the mail piece.
+				#    * *:state* (String) — Two-character state code of the destination address.
+				#    * *:zip5* (String) — Destination 5-digit ZIP Code. Must be 5-digits. Numeric values (0-9) only. If International, all zeroes.
+				#    * *:zip4* (String) — Destination ZIP+4. Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
+def zip_code_lookup(options = {})
 					throw ArgumentError.new('Required arguments :zip_code_lookup_request missing') if options[:zip_code_lookup_request].nil?
 
 					request = build_request(:zip_code_lookup, options)

data/lib/usps/api/templates/_options.erb

@@ -1,6 +1,3 @@
-<%= ErubisHelper.tabs(static_indentation) %>#<%= ErubisHelper.spaces(indentation*2) %>@option option [<%= option[:type] %>] :<%= option[:name] %> (<%= option[:required] ? 'Required' : 'Optional' %>)
-<% if option[:description].present? %>
-<%= ErubisHelper.tabs(static_indentation) %>#<%= ErubisHelper.spaces(indentation*2) %>- <%= option[:description] %>
-<% end %>
+<%= ErubisHelper.tabs(static_indentation) %>#<%= ErubisHelper.spaces(indentation*2) %> * *:<%= option[:name].underscore %>* (<%= option[:required] ? 'required, ' : '' %><%= ['(alias)', '(group)'].any?(option[:type].downcase) ? 'Hash' : option[:type] %>)<% if option[:description] %> — <%= option[:description] %><% end %>
 <% option[:children].each do |child_option_name, child_option| %>
 <%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_options.erb')).result(option: child_option, parents: [], indentation: indentation + 1, static_indentation: static_indentation) %><% end %>

data/lib/usps/api/templates/method.erb

@@ -6,18 +6,14 @@ module Usps
 	module Api
 		module Endpoints
 			module <%= data[:group].camelize %>
-				#
-				# <%= data[:title] %>
-				#
 				<% data[:description].to_s.split("\r").each do |line| %>
 				# <%= line.strip %>
 				<% end %>
-				#
+				# @param [Hash] options
+				# @option options [required, Hash] <%= data[:request_descriptions].first[1][:name].underscore %> <%= data[:request_descriptions].first[1][:description] %>
 				<% data[:request_descriptions].each do |option_name, option| %>
-<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_options.erb')).result(option: option, parents: [], indentation: 0, static_indentation: 3) %><% end %>
-				#
-				# @see <%= data[:link] %>
-				def <%= data[:group].underscore %>(options = {})
+					<% option[:children].each do |child_option_name, child_option| %>
+<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_options.erb')).result(option: child_option, parents: [], indentation: 0, static_indentation: 3) %><% end %><% end %>def <%= data[:group].underscore %>(options = {})
 					<% data[:request_descriptions].select{|n,o| o[:required]}.each do |option_name, option| %>
 	<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_throw_argument_error.erb')).result(option: option, parents: [], indentation: 3) %>
 					<% end %>

data/lib/usps/version.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Usps
-  VERSION = '0.1.0'
+  VERSION = '0.1.3'
 end

data/usps-ruby-client.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'activesupport', '~> 6.1'
+  spec.add_dependency 'activesupport', '~> 7.0'
   spec.add_dependency 'builder', '~> 3.2'
   spec.add_dependency 'faraday', '~> 0.17'
   spec.add_dependency 'faraday_middleware', '~> 0.14'
@@ -43,4 +43,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-performance', '~> 1.9'
   spec.add_development_dependency 'rubocop-rspec', '~> 2.1'
   spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: usps-ruby-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - Joey Paris
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-12 00:00:00.000000000 Z
+date: 2022-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: builder
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +206,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: An automatically generated USPS API Client based on the official USPS
   User Guides
 email:
@@ -222,6 +236,7 @@ files:
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -278,6 +293,8 @@ files:
 - lib/usps/faraday/response/raise_error.rb
 - lib/usps/logger.rb
 - lib/usps/version.rb
+- usps-ruby-client-0.1.0.gem
+- usps-ruby-client-0.1.2.gem
 - usps-ruby-client.gemspec
 homepage: https://www.usps.com/business/web-tools-apis/documentation-updates.htm
 licenses:
@@ -285,7 +302,7 @@ licenses:
 metadata:
   homepage_uri: https://www.usps.com/business/web-tools-apis/documentation-updates.htm
   source_code_uri: https://github.com/joeyparis/usps-ruby-client
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -300,8 +317,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.32
+signing_key:
 specification_version: 4
 summary: An automatically generated USPS API Client
 test_files: []