CMB-586: add booklets CRUD documentation (#498)

* CMB-645: add list, get and delete endpoints for snap packs (#495)

* booklet create

* add code samples for create; start on get

* get and delete endpoints

* remove color; update campaign_id verbiage

* remove color from the response examples

lob-api-public.yml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Lob
-  version: 1.19.35
+  version: 1.19.36
   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:
@@ -2347,6 +2347,7 @@ x-tagGroups:
       - Letters
       - Checks
       - Snap Packs
+      - Booklets
       - Bank Accounts
       - Templates
       - Template Versions
@@ -2434,6 +2435,10 @@ paths:
     $ref: resources/billing_groups/billing_group.yml
   /billing_groups:
     $ref: resources/billing_groups/billing_groups.yml
+  /booklets/{booklet_id}:
+    $ref: resources/booklets/booklet.yml
+  /booklets:
+    $ref: resources/booklets/booklets.yml
   /buckslips:
     $ref: resources/buckslips/buckslips.yml
   /buckslips/{buckslip_id}:

package.json

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

resources/booklets/attributes/booklet_file.yml

@@ -0,0 +1,21 @@
+description: >-
+  Notes:
+
+  - HTML merge variables should not include delimiting whitespace.
+
+  - All pages of a supplied PDF file must be sized per the `size` attribute,
+  while supplied HTML will be rendered and trimmed to as many `size` pages
+  as necessary.
+
+  - For design specifications, please see our
+  <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_template.pdf" target="_blank">PDF</a>
+  and [HTML](#section/HTML-Examples) templates.
+
+  See <a href="https://lob.com/pricing/print-mail#compare" target="_blank">pricing</a> for extra costs incurred.
+
+oneOf:
+  - $ref: "../../../shared/attributes/html_string.yml"
+  - $ref: "../../../shared/attributes/model_ids/tmpl_id.yml"
+  - $ref: "../../../shared/attributes/remote_file_url.yml"
+  - type: string
+    pattern: "^(?!https://)[a-zA-Z0-9@:%._+~#=/]{1,256}.(html?|pdf)$"

resources/booklets/attributes/booklet_id.yml

@@ -0,0 +1,5 @@
+type: string
+
+description: Unique identifier prefixed with `ord_`.
+
+pattern: "^ord_[0-9a-f]{26}$"

resources/booklets/attributes/booklet_size.yml

@@ -0,0 +1,10 @@
+type: string
+
+enum:
+  - 9x6
+  - 8.375x5.375
+
+description: >
+  Specifies the size of the booklet.
+
+default: 9x6

resources/booklets/attributes/booklet_use_type.yml

@@ -0,0 +1,7 @@
+description: The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our  [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type).
+type: string
+enum:
+  - marketing
+  - operational
+  - null
+nullable: true

resources/booklets/booklet.yml

@@ -0,0 +1,62 @@
+parameters:
+  - in: path
+    name: booklet_id
+    description: id of the booklet
+    required: true
+    schema:
+      $ref: "attributes/booklet_id.yml"
+
+get:
+  operationId: booklet_retrieve
+
+  summary: Retrieve
+
+  description: >-
+    Retrieves the details of an existing booklet. You need to only supply
+    the unique booklet identifier that was returned upon booklet creation.
+
+  tags:
+    - Booklets
+
+  responses:
+    "200":
+      description: Returns a booklet object
+      content:
+        $ref: responses/booklet.yml
+
+    default:
+      $ref: "../../shared/responses/mailpiece_error.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl -X GET "https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1" \
+          -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
+      label: CURL
+
+delete:
+  operationId: booklet_delete
+
+  summary: Delete
+
+  description: >-
+    Completely removes a booklet from production. This can only be done if the booklet's
+    `send_date` has not yet passed. If the booklet is successfully canceled, you will not
+    be charged for it.
+
+  tags:
+    - Booklets
+
+  responses:
+    "200":
+      $ref: "../../shared/responses/booklet_deleted.yml"
+
+    default:
+      $ref: "../../shared/responses/mailpiece_error.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl -X DELETE https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1 \
+          -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
+      label: CURL