docs(partner): audit & correct partner-integration docs; fix ratesRefetchInterval prop

[kaladinlight]

Description

Accuracy audit of the partner-integration documentation set, verifying every concrete claim against the actual implementation (swap-widget, public-api, swap-service, affiliate-dashboard) and correcting the discrepancies found. Includes one small code fix uncovered during the review.

Docs reviewed & corrected:

• docs/affiliates.md — partner code is partner-chosen (not "issued"); walletConnectProjectId not strictly required when the host owns AppKit; scoped the endpoints-table heading; clarified partnerBps only appears on attributed quotes.
• packages/public-api/docs/introduction.md — corrected rate-limit description (fixed window + app-wide global limiter on top of per-group limits).
• packages/public-api/docs/rest-api-guide.md — dropped the unobservable pending swap status (binding a txHash immediately moves it to submitted).
• packages/public-api/docs/swap-widget-sdk.md — install command now lists all required peer deps.
• packages/swap-widget/README.md — Bitcoin/Solana AppKit adapters documented as required peers (they're statically imported); documented the literal apiBaseUrl default; dual AppKit-init guidance.
• docs/architecture/affiliate-system.md — verified the attribution model end-to-end (only the total affiliateBps reaches the swapper; the split + partner address are off-chain settlement metadata); removed tangential swapper affiliate-constant references.

Code fix:

• fix(swap-widget): wire ratesRefetchInterval prop through to useSwapRates — the prop was declared on SwapWidgetProps but never threaded to useSwapRates, so it had no effect. Now flows through the component tree like allowedSwapperNames; an unset prop still falls back to the existing 15s default.

Issue (if applicable)

closes #

Risk

Low. Documentation-only except one self-contained swap-widget prop-wiring fix. The fix mirrors the existing allowedSwapperNames threading and preserves prior behavior when the prop is unset (15s refetch default). No new or modified on-chain transactions; no protocol, wallet, or contract interactions affected.

Testing

Engineering

• Every documented claim was verified against source (endpoints, headers, fee fields, types, chain-ID constants, enum values, env vars, middleware/registration flow).
• Code change: pnpm exec eslint on the changed files and tsc --noEmit for the swap-widget package both pass clean. ratesRefetchInterval now propagates SwapWidget → SwapWidgetCore → SwapWidgetContent → useSwapDisplayValues → useSwapRates; verify by passing e.g. ratesRefetchInterval={5000} and observing the rates refetch cadence; omitting it keeps the 15s default.

Operations

• 🏁 My feature is behind a flag and doesn't require operations testing (yet)

Docs-only plus a non-user-facing widget prop default; no operations testing required.

Screenshots (if applicable)

N/A

Summary by CodeRabbit

• New Features

  • Added configurable swap rate refresh timing for the widget.
  • Updated affiliate attribution to use partner codes and the X-Partner-Code header.
  • Expanded REST and widget guidance with clearer swap, quote, and status workflows.

• Documentation

  • Reworked affiliate docs to reflect the current partner-code flow and reporting endpoints.
  • Refreshed public API, widget SDK, and swap-widget README content with setup, error, and rate-limit details.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f90acaf1-9bdc-46c0-8976-4a12763489d0

📥 Commits

Reviewing files that changed from the base of the PR and between 42a0c05 and d667a77.

📒 Files selected for processing (9)

• docs/affiliates.md
• docs/architecture/affiliate-data-model.md
• docs/architecture/affiliate-system.md
• packages/public-api/docs/introduction.md
• packages/public-api/docs/rest-api-guide.md
• packages/public-api/docs/swap-widget-sdk.md
• packages/swap-widget/README.md
• packages/swap-widget/src/components/SwapWidget.tsx
• packages/swap-widget/src/hooks/useSwapDisplayValues.ts

💤 Files with no reviewable changes (1)

• docs/architecture/affiliate-data-model.md

---

📝 Walkthrough

Walkthrough

This PR rewrites affiliate-related documentation across docs/affiliates.md, docs/architecture/affiliate-system.md, and packages/public-api docs to describe a partner-code-based attribution model using the X-Partner-Code header, removes affiliate-data-model.md, updates the swap-widget README, and adds an optional ratesRefetchInterval parameter to SwapWidget and useSwapDisplayValues.

Changes

Affiliate documentation rewrite

Layer / File(s)	Summary
Affiliate quick-start, fees and endpoints doc docs/affiliates.md	Rewrites quick start, headers, fees, revenue attribution, and endpoint sections to use partnerCode/X-Partner-Code instead of affiliate address/bps.
Affiliate system architecture doc rewrite docs/architecture/affiliate-system.md, docs/architecture/affiliate-data-model.md	Reframes architecture doc as "implemented" partner-code attribution flow with middleware, swap-service persistence, dashboard, and endpoints; removes the superseded data-model doc.
Public API REST and intro docs updates packages/public-api/docs/introduction.md, packages/public-api/docs/rest-api-guide.md	Adds base URL/versioning, partner-code attribution guidance, asset discovery, rates/quote/execute/status flow details, status error codes, and affiliate reporting endpoints.
Swap Widget SDK and README documentation packages/public-api/docs/swap-widget-sdk.md, packages/swap-widget/README.md	Shortens the SDK doc to point to the README and rewrites the README's installation, wallet connection, props reference, exported types/hooks, and partner code/affiliate revenue sections.

Swap rates refetch interval

Layer / File(s)	Summary
ratesRefetchInterval threading through widget and hook packages/swap-widget/src/components/SwapWidget.tsx, packages/swap-widget/src/hooks/useSwapDisplayValues.ts	Adds optional ratesRefetchInterval prop threaded from SwapWidget through SwapWidgetCore/SwapWidgetContent into useSwapDisplayValues, which forwards it to useSwapRates as refetchInterval.

Sequence Diagram(s)

sequenceDiagram
  participant Widget
  participant PublicAPI
  participant SwapService
  Widget->>PublicAPI: swap request with X-Partner-Code header
  PublicAPI->>SwapService: resolvePartnerCode(partnerCode)
  SwapService-->>PublicAPI: partnerAddress, partnerBps, shapeshiftBps
  PublicAPI->>PublicAPI: compute affiliateBps
  PublicAPI->>SwapService: register swap with partner split metadata
  PublicAPI-->>Widget: swap response with affiliateBps

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• shapeshift/web#12407: Both PRs modify packages/swap-widget/src/hooks/useSwapDisplayValues.ts, with this PR adding ratesRefetchInterval forwarding into useSwapRates.

Poem

A rabbit hops through docs anew,
Partner codes replace the old, it's true 🐰
X-Partner-Code now leads the way,
Rates refetch faster, come what may,
Hop hop hooray for code so spry! 🥕

🚥 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 summarizes the main doc audit and the ratesRefetchInterval wiring fix, matching the pull request scope.
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 docs/partner-integration-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.}