docs(sdk): expand BulkDecrypt section with options, error handling, and best practices

[marythought]

Summary

• Add a performance tip explaining why BulkDecrypt is preferable to looping LoadTDF (batches KAS rewrap requests to reduce round-trips)
• Document all BulkDecryptOption functions: WithBulkKasAllowlist, WithBulkIgnoreAllowlist, WithTDFType, WithTDF3DecryptOptions
• Expand the error handling section to explain the partial-failure model and FromBulkErrors usage
• Add prose explaining when and why to use PrepareBulkDecrypt (obligations inspection, conditional decryption, monitoring)
• Update vendored OpenAPI specs (namespaces, selectors)

Source material: platform/sdk/bulk.go

Test plan

• Verify the BulkDecrypt section renders correctly in the docs site (tip admonition, options table, prose)
• Confirm no new broken links introduced
• Check dsp-docs build picks up the changes correctly via the remote content plugin

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Improved BulkDecrypt documentation explaining how request batching reduces round-trips
  • Added detailed Options table for all configuration parameters and behaviors
  • Expanded error handling documentation with aggregation and inspection guidance
  • Enhanced PrepareBulkDecrypt guidance with two-phase execution model description

[coderabbitai]

📝 Walkthrough

Walkthrough

This is a documentation update to the TDF SDK docs that enhances explanations for BulkDecrypt and PrepareBulkDecrypt functions, adding a "Why use BulkDecrypt?" tip, an Options table detailing configuration parameters and behaviors, expanded error handling guidance, and refined PrepareBulkDecrypt workflow description distinguishing rewrap and decrypt phases.

Changes

Cohort / File(s)

Summary

TDF SDK Documentation docs/sdks/tdf.mdx

Added "Why use BulkDecrypt?" tip explaining request batching benefits; replaced allowlist sentence with comprehensive Options table for PrepareBulkDecrypt/BulkDecrypt covering WithTDFs, WithBulkKasAllowlist, WithBulkIgnoreAllowlist, WithTDFType, and WithTDF3DecryptOptions; expanded Errors section detailing non-fail-fast behavior, error aggregation, and sdk.FromBulkErrors() semantics; refined PrepareBulkDecrypt guidance to distinguish rewrap (network) and decrypt (CPU) phases with monitoring considerations.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested reviewers

• elizabethhealy
• pflynn-virtru

Poem

🐰 Hops through the docs with glee,
Options tables, clear as can be!
BulkDecrypt batches, rewraps align,
Errors aggregated—oh how they shine! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: expanding the BulkDecrypt documentation with options table, error handling details, and best practices guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DSPX-2625-bulkdecrypt-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request enhances the TDF SDK documentation by adding detailed explanations for BulkDecrypt and PrepareBulkDecrypt, including their performance benefits, configuration options, and error handling mechanisms. Additionally, it updates the OpenAPI specifications for policy namespaces to introduce sorting capabilities for namespace listings, defining new schemas for sort direction and field types. I have no feedback to provide as there are no review comments to address.

[github-actions]

📄 Preview deployed to https://opentdf-docs-pr-271.surge.sh

[coderabbitai]

🧹 Nitpick comments (1)

docs/sdks/tdf.mdx (1)

585-594: Add direct links in WithTDF3DecryptOptions row for faster lookup.

Nice coverage of options. Consider linking readers straight to the detailed option docs from this row.

✏️ Proposed doc tweak

-| `WithTDF3DecryptOptions(opts...)` | Pass additional reader options (e.g., session key, assertion verification) through to each TDF3 decryptor. These are the same options accepted by `LoadTDF`. |
+| `WithTDF3DecryptOptions(opts...)` | Pass additional reader options (e.g., session key, assertion verification) through to each TDF3 decryptor. These are the same options accepted by [`LoadTDF`](`#loadtdf`). See [Decrypt Options](`#decrypt-options`). |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/sdks/tdf.mdx` around lines 585 - 594, Update the table row for
WithTDF3DecryptOptions to include direct hyperlinks to the detailed option docs
for TDF3 decryptors and the LoadTDF function so readers can jump straight to
full option descriptions; specifically add links from the
"WithTDF3DecryptOptions(opts...)" text to the LoadTDF API docs and the TDF3
decryptor/options reference (the same docs that describe session key and
assertion verification), ensuring anchor text still mentions
WithTDF3DecryptOptions and LoadTDF so maintainers can find and verify the change
easily.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/sdks/tdf.mdx`:
- Around line 585-594: Update the table row for WithTDF3DecryptOptions to
include direct hyperlinks to the detailed option docs for TDF3 decryptors and
the LoadTDF function so readers can jump straight to full option descriptions;
specifically add links from the "WithTDF3DecryptOptions(opts...)" text to the
LoadTDF API docs and the TDF3 decryptor/options reference (the same docs that
describe session key and assertion verification), ensuring anchor text still
mentions WithTDF3DecryptOptions and LoadTDF so maintainers can find and verify
the change easily.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5dfd96c4-c1b7-40ef-be52-a2de1fc6c76f

📥 Commits

Reviewing files that changed from the base of the PR and between ae6a207 and 3eff40a.

📒 Files selected for processing (1)

• docs/sdks/tdf.mdx