feat: add document transfer, set-price, and purchase tutorials

[thephez]

Add three marketplace tutorials covering the general document trading APIs, demonstrated against the DPNS domain document selected by NAME_LABEL. The same calls work with any document type whose contract enables transferable or tradeMode.

Summary by CodeRabbit

• New Features

  • Added tutorials for setting document prices, purchasing documents, and transferring document ownership.
  • Supports removing a document from sale by setting its price to zero.
  • Added configuration options for marketplace pricing, recipients, and secondary identities.
  • Added automated coverage for document pricing, purchasing, and transfers.

• Documentation

  • Clarified setup guidance for identity, data-contract, document-marketplace, and token tutorials.
  • Documented marketplace operations using DPNS domain documents.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 73ba70d5-0dea-465b-818f-24c18b73ef11

📥 Commits

Reviewing files that changed from the base of the PR and between 4c32914 and 93b5e5c.

📒 Files selected for processing (1)

• test/read-write.test.mjs

🚧 Files skipped from review as they are similar to previous changes (1)

• test/read-write.test.mjs

---

📝 Walkthrough

Walkthrough

The PR adds DPNS document pricing, purchase, and transfer tutorials. It adds marketplace configuration, README guidance, and sequential tests for cross-identity document operations.

Changes

Document marketplace workflows

Layer / File(s)	Summary
Marketplace configuration and guidance .env.example, README.md	Adds secondary identity credentials, document recipient, and document pricing configuration. Documents the marketplace APIs.
Document pricing, purchase, and transfer flows 2-Contracts-and-Documents/document-set-price.mjs, 2-Contracts-and-Documents/document-purchase.mjs, 2-Contracts-and-Documents/document-transfer.mjs	Adds authenticated DPNS document workflows with ownership, sale-price, revision, and recipient validation.
Sequential marketplace test coverage test/read-write.test.mjs	Loads configuration and validates document pricing, purchase, and transfer operations across identities.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Tutorial
  participant DashClient
  participant DPNS
  participant DocumentAPI
  Tutorial->>DashClient: initialize authenticated client
  DashClient->>DPNS: query domain document
  DPNS-->>DashClient: return document and ownership
  Tutorial->>DocumentAPI: submit price, purchase, or transfer
  DocumentAPI-->>Tutorial: return operation result

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the three marketplace tutorials added by the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tutorials/add-doc-xfer-sale

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.env.example:
- Line 39: Update the DOCUMENT_RECIPIENT_ID entry in the environment example to
use an unquoted empty value, preserving it as empty while removing the
dotenv-linter warning.

In `@2-Contracts-and-Documents/document-set-price.mjs`:
- Around line 3-12: Wrap all startup operations in the tutorials’ existing
try-catch handlers so failures are logged through console.error: in
2-Contracts-and-Documents/document-set-price.mjs lines 3-12, move
setupDashClient(), keyManager.getAuth(), and DOCUMENT_PRICE parsing into the try
block; in 2-Contracts-and-Documents/document-purchase.mjs lines 3-4 and
2-Contracts-and-Documents/document-transfer.mjs lines 3-4, move client setup and
authentication into their try blocks. Preserve the ESM top-level-await pattern
and existing sdk/keyManager usage.

In `@test/read-write.test.mjs`:
- Around line 167-188: Update the runTutorial invocation for document-set-price
to pass a fixed positive DOCUMENT_PRICE in its env alongside NAME_LABEL. Keep
the existing success assertions and extracted-price flow unchanged so the
listing remains available for dependent purchase and transfer tests.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f71a30f5-d204-4e53-80eb-f1ca8330ab73

📥 Commits

Reviewing files that changed from the base of the PR and between a8e7bf7 and 4c32914.

📒 Files selected for processing (6)

• .env.example
• 2-Contracts-and-Documents/document-purchase.mjs
• 2-Contracts-and-Documents/document-set-price.mjs
• 2-Contracts-and-Documents/document-transfer.mjs
• README.md
• test/read-write.test.mjs