CMB-341: docs to support legal letters (#481)

* CMB-341: docs to support legal letters

* update verbiage

lob-api-public.yml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Lob
-  version: 1.19.24
+  version: 1.19.25
   description: |
     The Lob API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and uses HTTP response codes to indicate any API errors. <p>
   license:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lob/openapi",
-  "version": "1.19.24",
+  "version": "1.19.25",
   "engines": {
     "node": ">=14.16.0",
     "npm": ">=7.9.0"

resources/letters/attributes/extra_service.yml

@@ -9,4 +9,6 @@ description: |
     * `certified` - track and confirm delivery for domestic destinations. An extra sheet (1 PDF page single-sided or 2 PDF pages double-sided) is added to the beginning of your letter for address and barcode information. See here for templates: <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_template.pdf" target="_blank">#10 envelope</a> and <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_flat_template.pdf" target="_blank">flat envelope</a> (used for letters over 6 pages single-sided or 12 pages double-sided). You will not be charged for this extra sheet.
     * `certified_return_receipt` - request an electronic copy of the recipient's signature to prove delivery of your certified letter
     * `registered` - provides tracking and confirmation for international addresses
+    
+  Not available for `us_legal` letter size.
 nullable: true

resources/letters/attributes/ltr_size.yml

@@ -0,0 +1,17 @@
+type: string
+
+enum:
+  - us_letter
+  - us_legal
+
+description: >
+  Specifies the size of the letter. It accepts two values `us_letter` and `us_legal`.
+  If the [Lob-Version header](#tag/Versioning-and-Changelog) in the request is set to `2024-01-01` and above,
+  the `size` property is automatically included with the default value of `us_letter`,
+  unless explicitly specified.
+
+
+  Please note that attempting to include the `size` property in the request with the `Lob-Version` header
+  predating to `2024-01-01` will result in an error.
+
+default: us_letter

resources/letters/letters.yml

@@ -172,6 +172,7 @@ post:
   parameters:
     - $ref: "../../shared/parameters/idempotency.yml#/idem-header"
     - $ref: "../../shared/parameters/idempotency.yml#/idem-query"
+    - $ref: "../../shared/parameters/lob_version.yml#/lob-version"
 
   requestBody:
     required: true

resources/letters/models/letter_editable.yml

@@ -20,7 +20,7 @@ allOf:
         $ref: "../attributes/extra_service.yml"
 
       cards:
-        description: A single-element array containing an existing card id in a string format. See [cards](#tag/Cards) for more information.
+        description: A single-element array containing an existing card id in a string format. See [cards](#tag/Cards) for more information. Not available for `us_legal` letter size.
         type: array
         items:
           $ref: "../../../shared/attributes/model_ids/card_id.yml"
@@ -69,5 +69,8 @@ allOf:
 
       fsc:
         type: boolean
-        description: This is in beta. Contact [email protected] or your account contact to learn more. Not available for `A4` letter size.
+        description: This is in beta. Contact [email protected] or your account contact to learn more. Not available for `A4` and `us_legal` letter size.
         default: false
+
+      size:
+        $ref: "../attributes/ltr_size.yml"

shared/models/qr_code.yml

@@ -1,5 +1,5 @@
 type: object
-description: Customize and place a QR code on the creative at the required position.
+description: Customize and place a QR code on the creative at the required position. Not available for `us_legal` letter size.
 required:
   - position
   - redirect_url

shared/parameters/lob_version.yml

@@ -0,0 +1,15 @@
+lob-version:
+  in: header
+
+  name: Lob-Version
+
+  required: false
+
+  description: >
+    A string representing the version of the API being used. For more information on versioning,
+    refer to our [Versioning and Changelog]((#tag/Versioning-and-Changelog) documentation.
+
+  schema:
+    type: string
+    example: 2024-01-01
+    pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"