FD-164: Add Resource Proofs API documentation

[NateWaldschmidt]

Fixes #FD-164

Checklist

• Up to date with main
• All the tests are passing
  • Delete all resources created in tests
• Prettier
• Spectral Lint
• npm run bundle outputs nothing suspect
• npm run postman outputs nothing suspect

Changes

Adds complete OpenAPI specification for the Resource Proofs resource, enabling users to create proofs for reviewing mailpiece creatives. The implementation includes:

New Endpoints:

• POST /resource_proofs - Create a new resource proof
• GET /resource_proofs/{res_prf_id} - Retrieve a resource proof
• PATCH /resource_proofs/{res_prf_id} - Update a resource proof (template_id only)

Resource Types Supported:

• Postcard
• Letter
• Self Mailer

Schema Features:

• Discriminated oneOf pattern for the three resource types
• Proper error handling with detailed issue entries
• Thumbnail support (small, medium, large)
• Complete model composition using allOf for reusability
• Consistent response formats aligned with existing Lob API patterns

Files Added:

• 16 new OpenAPI definition files under resources/resource_proofs/
  • Models (base, editable, updatable, resource-type-specific parameters)
  • Attributes (id, status, resource_type)
  • Responses (resource_proof, post_resource_proof)
  • Endpoint definitions

Files Modified:

• lob-api-public.yml - Added tag definition, tagGroup reference, and path definitions
• docs/index.html - Auto-generated from updated spec

Areas of Concern (optional)

• Response example in resources/resource_proofs/responses/resource_proof.yml is missing resource_parameters and url fields (see code review findings)
• Top-level required in resource_proof_editable.yml may need alignment with how other discriminated schemas handle this constraint
• Some unstaged changes needed (description replacement and example adjustments)

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly expands the API documentation by introducing a comprehensive set of OpenAPI specifications for a new Resource Proofs API. This addition enables users to programmatically create, retrieve, and update proofs for various mailpiece creatives like postcards, letters, and self-mailers, enhancing the platform's capabilities for creative review and management.

Highlights

• New API Endpoints: Introduced three new endpoints for managing Resource Proofs: POST /resource_proofs for creation, GET /resource_proofs/{res_prf_id} for retrieval, and PATCH /resource_proofs/{res_prf_id} for updating (template_id only).
• Supported Resource Types: The Resource Proofs API now supports creating proofs for Postcard, Letter, and Self Mailer mailpiece creatives.
• Comprehensive OpenAPI Specification: A complete OpenAPI specification has been added, including detailed models for resource proofs, their attributes (ID, status, resource type), and responses. This includes discriminated oneOf patterns for different resource types, proper error handling, thumbnail support, and consistent response formats.
• New OpenAPI Definition Files: Sixteen new OpenAPI definition files were added under resources/resource_proofs/ to define models, attributes, responses, and endpoint specifications for the new API.
• API Integration: The main lob-api-public.yml file was updated to include the new 'Resource Proofs' tag, integrate it into x-tagGroups, and reference the new path definitions for the Resource Proofs API.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• lob-api-public.yml
  • Added 'Resource Proofs' as a new tag definition with a description.
  • Included 'Resource Proofs' in the x-tagGroups for better organization.
  • Registered new paths /resource_proofs/{res_prf_id} and /resource_proofs to the API specification.
• resources/resource_proofs/attributes/res_prf_id.yml
  • Defined the res_prf_id attribute, specifying its type, description, and pattern.
• resources/resource_proofs/attributes/res_prf_resource_type.yml
  • Defined the res_prf_resource_type attribute, including its enum values for postcard, letter, and self_mailer.
• resources/resource_proofs/attributes/res_prf_status.yml
  • Defined the res_prf_status attribute, specifying its enum values for processing, completed, and failed.
• resources/resource_proofs/models/issue_entry.yml
  • Created the issue_entry model to define the structure for error details, including code, message, and URLs.
• resources/resource_proofs/models/letter_resource_parameters.yml
  • Defined the letter_resource_parameters model, combining shared form factor inputs and specifying required properties like to, from, file, and color, along with other letter-specific attributes.
• resources/resource_proofs/models/postcard_resource_parameters.yml
  • Defined the postcard_resource_parameters model, combining shared form factor inputs and specifying required properties like to, front, and back, along with other postcard-specific attributes.
• resources/resource_proofs/models/resource_proof.yml
  • Defined the resource_proof model, extending resource_proof_base and adding required properties such as id, resource_type, status, thumbnails, errors, date_created, date_modified, and object.
• resources/resource_proofs/models/resource_proof_base.yml
  • Defined the resource_proof_base model, outlining common properties for resource proofs like template_id, resource_type, status, thumbnails, url, and errors.
• resources/resource_proofs/models/resource_proof_editable.yml
  • Defined the resource_proof_editable model using a oneOf discriminator pattern to support different resource types (postcard, letter, self_mailer) with their respective parameters.
• resources/resource_proofs/models/resource_proof_updatable.yml
  • Defined the resource_proof_updatable model, allowing updates to the template_id property of a resource proof.
• resources/resource_proofs/models/self_mailer_resource_parameters.yml
  • Defined the self_mailer_resource_parameters model, combining shared form factor inputs and specifying required properties like to, inside, and outside, along with other self-mailer-specific attributes and detailed descriptions for artwork.
• resources/resource_proofs/models/thumbnail.yml
  • Defined the thumbnail model, specifying URLs for small, medium, and large thumbnail images.
• resources/resource_proofs/resource_proof.yml
  • Defined the OpenAPI specification for the GET /resource_proofs/{res_prf_id} endpoint to retrieve a resource proof.
  • Defined the OpenAPI specification for the PATCH /resource_proofs/{res_prf_id} endpoint to update a resource proof's template_id.
• resources/resource_proofs/resource_proofs.yml
  • Defined the OpenAPI specification for the POST /resource_proofs endpoint to create a new resource proof.
• resources/resource_proofs/responses/post_resource_proof.yml
  • Defined the post_resource_proof response, including rate limit headers and content referencing the resource_proof model.
• resources/resource_proofs/responses/resource_proof.yml
  • Defined the resource_proof response content type and provided a detailed example of a resource proof object.

Activity

• The pull request is up to date with the main branch.
• The author noted that tests are not yet passing, and some resources created in tests need to be deleted.
• Prettier and Spectral Lint checks are pending.
• The author indicated that npm run bundle and npm run postman outputs need to be checked for suspicious content.
• The author highlighted that the response example in resources/resource_proofs/responses/resource_proof.yml is missing resource_parameters and url fields.
• A concern was raised regarding the alignment of the top-level required in resource_proof_editable.yml with how other discriminated schemas handle this constraint.
• The author mentioned that some unstaged changes are still needed for description replacement and example adjustments.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces a new API for 'Resource Proofs', enabling the creation, retrieval, and updating of resource proofs for postcards, letters, and self-mailers, along with their corresponding data models and attributes. Review comments suggest two improvements: correcting a missing required 'to' field in the postcard resource proof example within the API documentation to prevent user errors, and simplifying the object property definition in the resource_proof model by removing a redundant single-value enum when a default value is already present.

[KARSE22]

I'm not 100% sure if this will work. Looking at the docs

These discriminator mapping values (#/oneOf/0, #/oneOf/1, #/oneOf/2) aren't valid OpenAPI 3.0 $ref paths. When it gets bundled, it looks like they compile to schemas like this ('0', '1', '2'), and I don't believe those are valid, since they need to be $ref's? I think we'd have to give each oneOf variant its own named schema file.

[NateWaldschmidt]

This is what I see when testing which is what I want. Does this look like you would expect?

[KARSE22]

This looks good, thanks for the screenshot! I didn't test the UI, I was just going off what I noticed in the lob-api-bundled.yml and wasn't sure if it would cause any issues.

[KARSE22]

not a blocker: wondering if we'd like to add tests for resource proofs? It seems like some of the other resources have contract tests. But this might be harder since the status field is low key async and we might need to poll? But maybe we could just verify the initial processing state?

[guardrails]

⚠️ We detected 17 security issues in this pull request:

Vulnerable Libraries (17)

Severity	Details
Critical	pkg:npm/@stoplight/[email protected] (t) upgrade to: > 4.14.1
High	pkg:npm/[email protected] (t) upgrade to: > 1.77.2
High	pkg:npm/[email protected] (t) upgrade to: > 6.5.1
High	pkg:npm/[email protected] (t) upgrade to: > 4.3.3
High	pkg:npm/@actions/[email protected] (t) upgrade to: > 1.10.1
High	pkg:npm/[email protected] (t) upgrade to: > 4.2.2
Medium	pkg:npm/[email protected] (t) upgrade to: 5.2.1
Informational	pkg:npm/[email protected] (t) upgrade to: > 2.9.0
High	pkg:npm/@slack/[email protected] (t) upgrade to: > 6.12.0
High	pkg:npm/[email protected] (t) upgrade to: > 4.10.0
Critical	pkg:npm/@stoplight/[email protected] (t) upgrade to: > 6.11.1
Informational	pkg:npm/[email protected] (t) upgrade to: > 6.11.0
Critical	pkg:npm/[email protected] (t) upgrade to: > 0.13.21
High	pkg:npm/@redocly/[email protected] (t) upgrade to: > 1.12.2
High	pkg:npm/[email protected] (t) upgrade to: > 3.2.1
N/A	pkg:npm/[email protected] (t) upgrade to: 8.18.0
High	pkg:npm/[email protected] (t) upgrade to: 5.104.1

More info on how to fix Vulnerable Libraries in JavaScript.

---

👉 Go to the dashboard for detailed results.

📥 Happy? Share your feedback with us.