Add informed delivery docs (#505)

lob-api-public.yml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Lob
-  version: 1.19.41
+  version: 1.19.42
   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:
@@ -960,6 +960,10 @@ tags:
     description: |
       Validates whether a given name is associated with an address.
       <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
+  - name: Informed Delivery Campaign
+    description: |
+      The Informed Delivery campaigns API allows you to create and view Informed Delivery campaigns.
+      <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
   - name: Intl Autocompletions
     description: |
       Address autocompletion for non-US addresses. Given partial address information, this endpoint returns up to 10 address suggestions.
@@ -2358,6 +2362,9 @@ x-tagGroups:
       - Campaigns
       - Creatives
       - Uploads
+  - name: Informed Delivery Campaign API
+    tags:
+      - Informed Delivery Campaign
   - name: Address Verification API
     tags:
       - US Verifications
@@ -2471,6 +2478,10 @@ paths:
     $ref: resources/creatives/creative.yml
   /identity_validation:
     $ref: resources/identity_validation/identity_validation.yml
+  /informed_delivery_campaigns:
+    $ref: resources/informed_delivery_campaigns/informed_delivery_campaigns.yml
+  /informed_delivery_campaigns/{usps_campaign_id}:
+    $ref: resources/informed_delivery_campaigns/informed_delivery_campaign.yml
   /intl_autocompletions:
     $ref: resources/intl_autocompletions/intl_autocompletions.yml
   /intl_verifications:

package.json

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

resources/informed_delivery_campaigns/attributes/infd_id.yml

@@ -0,0 +1,9 @@
+# If other resources will need to reference this id, move
+# the id to 'shared/attributes/model_ids/'
+type: string
+
+description: Unique identifier prefixed with `infd_`.
+
+pattern: "^infd_[a-zA-Z0-9]+$"
+
+example: infd_23g423g4234g342

resources/informed_delivery_campaigns/attributes/usps_campaign_id.yml

@@ -0,0 +1,9 @@
+# If other resources will need to reference this id, move
+# the id to 'shared/attributes/model_ids/'
+type: string
+
+description: A numberical string up to 12 characters long.
+
+pattern: "^[0-9]+$"
+
+example: "1200772869"

resources/informed_delivery_campaigns/informed_delivery_campaign.yml

@@ -0,0 +1,74 @@
+parameters:
+  - in: path
+    name: usps_campaign_id
+    description: usps_campaign_id of the Informed Delivery campaign
+    required: true
+    schema:
+      $ref: "attributes/usps_campaign_id.yml"
+
+get:
+  operationId: informed_delivery_campaign_retrieve
+
+  summary: Retrieve
+
+  description: >-
+    Retrieves the details of an existing Informed Delivery campaign. You need only supply
+    the `usps_campaign_id` returned in the campaign creation request.
+
+  tags:
+    - Informed Delivery Campaign
+
+  responses:
+    "200":
+      description: Returns a informed delivery campaign object
+      content:
+        $ref: "responses/informed_delivery_campaign.yml"
+
+    "404":
+      $ref: "responses/404.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl https://api.lob.com/v1/informed_delivery_campaign/1200772869 \
+          -u <YOUR API KEY>:
+      label: CURL
+
+patch:
+  operationId: informed_delivery_campaign_update
+
+  summary: Update
+
+  description: >-
+    Update the details of an existing Informed Delivery campaign.<br>
+    **NOTE:** you can only update a campaign in the `pending_approval` status.
+
+  tags:
+    - Informed Delivery Campaign
+
+  requestBody:
+    required: true
+    content:
+      multipart/form-data:
+        schema:
+          $ref: "models/update.yml"
+
+  responses:
+    "200":
+      description: Returns an Informed Delivery campaign object
+      content:
+        $ref: "responses/informed_delivery_campaign.yml"
+
+    "404":
+      $ref: "responses/404.yml"
+
+    "422":
+      $ref: "responses/writeable_422.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl -X PATCH https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \
+          -u <YOUR API KEY>: \
+          -d '{"status":"approved"}'
+      label: CURL

resources/informed_delivery_campaigns/informed_delivery_campaigns.yml

@@ -0,0 +1,62 @@
+get:
+  operationId: informed_delivery_campaign_list
+
+  summary: List
+
+  description: >-
+    List Informed Delivery campaigns
+
+  tags:
+    - Informed Delivery Campaign
+
+  responses:
+    "200":
+      $ref: "responses/all_informed_delivery_campaigns.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl https://api.lob.com/v1/informed_delivery_campaign \
+          -u <YOUR API KEY>:
+      label: CURL
+
+post:
+  operationId: informed_delivery_campaign_create
+
+  summary: Create
+
+  description: >-
+    Creates a new Informed Delivery campaign
+
+  tags:
+    - Informed Delivery Campaign
+
+  requestBody:
+    required: true
+    content:
+      multipart/form-data:
+        schema:
+          $ref: "models/create.yml"
+
+  responses:
+    "200":
+      description: Creative created successfully
+      content:
+        $ref: "responses/informed_delivery_campaign.yml"
+
+    "422":
+      $ref: "responses/writeable_422.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl --request POST \
+          --url https://api.lob.com/v1/informed_delivery_campaigns \
+          -u <YOUR API KEY>: \
+          --header 'Content-Type: multipart/form-data' \
+          --form ride_along_url=https://www.lob.com \
+          --form 'ride_along_image=@/path/to/ride_along.jpg' \
+          --form quantity=2 \
+          --form start_date=2024-01-01 \
+          --form status=pending_approval
+      label: CURL

resources/informed_delivery_campaigns/models/common.yml

@@ -0,0 +1,40 @@
+allOf:
+  - type: object
+
+    properties:
+      quantity:
+        type: integer
+        minimum: 2
+        maximum: 10000000
+        description: |
+          The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected.
+      status:
+        type: string
+      ride_along_url:
+        type: string
+        minLength: 10
+        maxLength: 255
+        pattern: '^https:\/\/.{5,247}$'
+        description: |
+          To qualify as part of a promotion, the base domain must match the domain used to register the promotion.
+          I.e. If the promo was registered with https://lob.com then you could use any variation of https://lob.com such as
+          https://lob.com/promotions/promo_123
+      start_date:
+        type: string
+        format: date
+        description: |
+          The first date that mail can be handed off to USPS and still included in the informed delivery campaign.
+          The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start.
+          For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now).
+      brand_name:
+        type: string
+        description: The brand name you would like included in the informed delivery email. Will default to the “company” on the users account.
+      usps_title:
+        type: string
+        description: Unique title for the campaign. One will be auto generated if not provided.
+      lob_campaign_id:
+        type: string
+        pattern: "^cmp_[a-zA-Z0-9]+$"
+        nullable: true
+        description: |
+          When sending as part of Lob’s campaign workflow, include the lob_campaign_id as part of the request to associate this Informed Delivery campaign with the Lob campaign

resources/informed_delivery_campaigns/models/create.yml

@@ -0,0 +1,20 @@
+allOf:
+  - $ref: "writable_base.yml"
+
+  - type: object
+
+    required:
+      - quantity
+      - ride_along_image
+      - ride_along_url
+      - start_date
+
+    properties:
+      status:
+        type: string
+        enum:
+          - pending_approval
+        description: |
+          If setting a campaign to `pending_approval` the Informed Delivery campaign will not be active, and you can not send mail using it.
+          It will be editable in this status however, and changes can be made until `approved`.
+          **NOTE** that the default status is `approved` which makes the campaign active, but un-editable.

resources/informed_delivery_campaigns/models/response.yml

@@ -0,0 +1,85 @@
+allOf:
+  - $ref: "common.yml"
+
+  - type: object
+
+    required:
+      - id
+      - object
+      - account_id
+      - quantity
+      - usps_campaign_id
+      - usps_title
+      - start_date
+      - end_date
+      - start_serial
+      - end_serial
+      - ride_along_url
+      - ride_along_image_s3_link
+      - representative_image_s3_link
+      - status
+      - date_created
+      - date_modified
+      - mode
+      - lob_campaign_id
+      - deleted
+      - campaign_code
+      - brand_name
+      - service_request_number
+
+    properties:
+      id:
+        $ref: "../attributes/infd_id.yml"
+      object:
+        type: string
+        description: Value is the resource type.
+        enum:
+          - informed_delivery_campaign
+      account_id:
+        type: string
+        description: Your Lob account id.
+      usps_campaign_id:
+        $ref: "../attributes/usps_campaign_id.yml"
+      end_date:
+        type: string
+        format: date-time
+        description: A timestamp in ISO 8601 format of the date the campaign ends.
+      start_serial:
+        type: integer
+        nullable: true
+        description: |
+          The first serial number in the range of serial numbers for this campaign.
+          Only non-null when campaign is approved.
+      end_serial:
+        type: integer
+        nullable: true
+        description: |
+          The last serial number in the range of serial numbers for this campaign.
+          Only non-null when campaign is approved.
+      ride_along_image_s3_link:
+        type: string
+        description: A URL link to the campaigns ride along image.
+      representative_image_s3_link:
+        type: string
+        nullable: true
+        description: A URL link to the campaigns representative image.
+      date_created:
+        $ref: "../../../shared/attributes/timestamps.yml#/date_created"
+      date_modified:
+        $ref: "../../../shared/attributes/timestamps.yml#/date_modified"
+      mode:
+        type: string
+        description: The mode of the Informed Delivery campaign. This is set by the API token you used to create the campaign.
+        enum:
+          - live
+          - test
+      deleted:
+        type: boolean
+        description: Whether the resource has been deleted.
+      campaign_code:
+        type: string
+        description: The campaign code associated with the Informed Delivery campaign.
+      service_request_number:
+        type: string
+        nullable: true
+        description: The USPS promotion service request number used to create this campaign (if there was one used).

resources/informed_delivery_campaigns/models/update.yml

@@ -0,0 +1,11 @@
+allOf:
+  - $ref: "writable_base.yml"
+  - type: object
+    properties:
+      status:
+        type: string
+        enum:
+          - approved
+        description: |
+          After setting an Informed Delivery campaign to “approved” said campaign will activate, and you can start sending mail using it.
+          You will no longer be able to edit an Informed Delivery campaign in this status.

resources/informed_delivery_campaigns/models/writable_base.yml

@@ -0,0 +1,12 @@
+allOf:
+  - $ref: "common.yml"
+
+  - type: object
+
+    properties:
+      ride_along_image:
+        type: object
+        description: JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high
+      representative_image:
+        type: object
+        description: JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high