Docs: SDK alignment, architecture updates, new pages, and quality fixes#31
Open
Docs: SDK alignment, architecture updates, new pages, and quality fixes#31
Conversation
- Align all Get Started pages with develop branch SDK and Lexicon APIs (rights fields, method names, return types, auth config, contributions format) - Update all 5 Architecture pages with cross-references, expanded content, and corrections from develop branch - Redesign architecture-stack.svg with detailed three-layer diagram - Add Hypercerts SDK reference page (tools/sdk.md) - Add new lexicon pages: funding-receipt, acknowledgement, badge-award, badge-definition, badge-response, profile - Rename General Lexicons to Certified Lexicons - Rename why-atproto.md to why-at-protocol.md - Fix CodeRabbit review issues (terminology, verb agreement, capitalization) - Update navigation and index page to match all changes
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR updates site navigation and terminology (ATProto → AT Protocol), adds the Hypercerts SDK docs, introduces Certified Lexicons and several new lexicon pages (badges, profile, funding receipts, acknowledgement), adjusts many getting-started and core docs to new SDK/record shapes, and reorganizes several architecture and indexer pages. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~35 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
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. Comment |
- Rewrite based on actual hyperboards.org product features: treemap layouts, drag-to-resize editing, iframe embedding, ATProto sign-in, dashboard - Add embedding code example, tech stack table - Update navigation and index page references - Rename hyperboard.md → hyperboards.md to match product name
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
pages/getting-started/working-with-evaluations.md (1)
13-34:⚠️ Potential issue | 🟡 MinorInconsistent auth pattern: OAuth config paired with
sdk.restoreSession().The SDK is initialized with an OAuth config (
clientId,redirectUri,scope: "atproto") but then usessdk.restoreSession("did:plc:evaluator123")instead of completing the OAuth flow withsdk.callback(callbackParams). These are distinct authentication flows:
- OAuth flow →
sdk.authorize(identifier)→sdk.callback(callbackParams)to obtain session- Session restore →
sdk.restoreSession(did)to load a previously persisted sessionThe OAuth config will not be used by
restoreSession(), making it misleading. Readers copying this snippet will not understand which authentication method to use, or will not realize thatrestoreSession()requires a persisted session from the SessionStore.Either remove the OAuth config and use app-password/server-side authentication (which works with
restoreSession()), or replacerestoreSession()withsdk.callback(callbackParams)to complete the OAuth flow shown in the config.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/getting-started/working-with-evaluations.md` around lines 13 - 34, The snippet mixes OAuth configuration with a session-restore call: the createATProtoSDK oauth block will not be used if you call sdk.restoreSession("did:plc:evaluator123"); either remove the oauth config and document that restoreSession expects a previously persisted session (SessionStore/app-password style), or keep the oauth config and replace the restoreSession call with the OAuth flow (call sdk.authorize(identifier) then complete with sdk.callback(callbackParams) to obtain the session) so the example consistently uses one authentication method (refer to createATProtoSDK, oauth, sdk.restoreSession, sdk.authorize, and sdk.callback).
🧹 Nitpick comments (4)
pages/lexicons/certified-lexicons/shared-defs.md (1)
23-29: Consider adding a short description for theapp.certified.defssection.The new section drops straight into the table. A one-sentence note explaining the relationship between
app.certified.defsandorg.hypercerts.defs(e.g., that the former is used by Certified-namespace lexicons) would help readers orient.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/certified-lexicons/shared-defs.md` around lines 23 - 29, Add a one-sentence descriptive note under the "Certified Definitions" heading explaining the role of app.certified.defs and its relationship to org.hypercerts.defs (for example: "app.certified.defs defines shared types used by Certified-namespace lexicons and extends/aligns with common types from org.hypercerts.defs"). Place this sentence immediately before the table so readers understand that app.certified.defs contains definitions used by Certified lexicons and how it relates to org.hypercerts.defs.pages/tools/sdk.md (1)
259-272: Missing import forcreateATProtoSDKin the local development example.Unlike the React hooks example above it, this snippet doesn't show the import, so readers don't know which package to import from. Every other runnable snippet in this file shows its imports.
🛠️ Proposed fix
+import { createATProtoSDK } from "@hypercerts-org/sdk-core"; + const sdk = createATProtoSDK({ oauth: {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/tools/sdk.md` around lines 259 - 272, Add the missing import for createATProtoSDK at the top of the example so the snippet is runnable; import the factory from the SDK package (e.g., import { createATProtoSDK } from '@atproto/sdk') and ensure the import style matches the React hooks example and other snippets in the file so readers know which package to import from.pages/lexicons/certified-lexicons/badge-response.md (1)
21-21: Add a note clarifyingweightis only meaningful whenresponseisaccepted.The Comments cell is empty; a rejected badge award with a non-null
weightis semantically ambiguous.✏️ Suggested wording
-| `weight` | `string` | ❌ | Optional relative weight for accepted badges, assigned by the recipient | | +| `weight` | `string` | ❌ | Optional relative weight for accepted badges, assigned by the recipient | Only meaningful when `response` is `accepted`. |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/certified-lexicons/badge-response.md` at line 21, Update the badge-response documentation to clarify that the `weight` field is only meaningful when `response` equals `accepted`; specifically, modify the table row for `weight` (the `weight` column entry) to add a comment noting that `weight` should be set only for accepted responses and is ignored or semantically invalid for `rejected` responses, and ensure the `response` field is referenced so readers understand the conditional relationship between `weight` and `response`.pages/lexicons/hypercerts-lexicons/funding-receipt.md (1)
41-70: Code example uses the low-level@atproto/apirather than the Hypercerts SDK.Every other example in this PR (
quickstart.md,building-on-hypercerts.md, etc.) uses@hypercerts-org/sdk-core. UsingBskyAgentdirectly here is inconsistent and sends mixed signals to readers. If funding receipts aren't yet exposed by the SDK, consider updating the callout to explicitly note that SDK support is coming and this is a temporary raw-API approach, or add the receipt to the SDK surface before publishing.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md` around lines 41 - 70, The example uses the low-level BskyAgent and agent.api.com.atproto.repo.createRecord to publish an org.hypercerts.funding.receipt, which is inconsistent with other docs that use `@hypercerts-org/sdk-core`; either update this sample to call the SDK equivalent (use the SDK client method that publishes receipts—replace BskyAgent usage with the SDK client initializer and its publish/createReceipt method) or, if the SDK does not yet support funding receipts, add a clear callout above the snippet stating this is a temporary raw-API workaround and that SDK support for org.hypercerts.funding.receipt will be added soon. Ensure you reference BskyAgent, agent.api.com.atproto.repo.createRecord, and org.hypercerts.funding.receipt in the change so reviewers can find and update the snippet or add the callout.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/architecture/data-flow-and-lifecycle.md`:
- Line 22: Update the wording in pages/architecture/data-flow-and-lifecycle.md:
replace the phrase "this works today on ATProto" with "this works today on AT
Protocol" to match the PR-wide rename; ensure the surrounding sentence remains
unchanged and only the token "ATProto" in the Funding paragraph is updated.
In `@pages/architecture/indexers-and-discovery.md`:
- Around line 42-44: The current docs recommend Constellation without warning
readers that its API is unstable; edit the paragraph describing Constellation
(the block that begins "Constellation indexes ATProto records...") to add a
short stability caveat noting the API is unstable and may change (e.g., a
one-sentence note or the suggested italicized note "_Note: Constellation's API
is under active development and may change._") so readers know not to rely on it
for production guarantees.
In `@pages/core-concepts/funding-and-value-flow.md`:
- Line 59: Replace the outdated abbreviation "ATProto" with the new canonical
name "AT Protocol" in the sentence that currently reads "the canonical record
remains the ATProto data" — update that phrase to "the canonical record remains
the AT Protocol data" (search for the exact phrase "the canonical record remains
the ATProto data" to locate the change and ensure consistency with other files
using "AT Protocol").
In `@pages/getting-started/creating-your-first-hypercert.md`:
- Around line 125-134: The "What you've built" tree is inconsistent with the
create() call that uses plain DID strings (the contributors:
["did:plc:alice123"] array in the create() invocation); either simplify the
diagram to show Contributors as DID entries (no ContributorInformation child
records) or add explicit creation of ContributorInformation records before the
create() call and replace the plain DID strings with the returned record DIDs;
locate the create() usage and the "What you've built" tree text, then either (A)
update the tree to reflect plain DID contributors, or (B) insert steps to create
contributorInformation records (e.g., createContributorInformation /
contributorInformation.create or similar) and use their DIDs in the contributors
array so the tree matches the actual structure.
In `@pages/getting-started/testing-and-deployment.md`:
- Around line 63-67: Update the prose to use the correct field name shown in the
example logs: replace the backticked `cid` with `hypercertCid` and optionally
mention `result.hypercertCid` to match the code that logs `result.hypercertCid`
(the surrounding example also logs `result.hypercertUri`, so ensure only the CID
reference is renamed to `hypercertCid`).
In `@pages/lexicons/hypercerts-lexicons/acknowledgement.md`:
- Around line 29-62: Update the example to be consistent with the PR: either (A)
replace the `@atproto/api` app-password example (BskyAgent + agent.login) with the
OAuth pattern used elsewhere (use createATProtoSDK / sdk.getRepository /
repo.records.create and the jwkPrivate OAuth flow) and change the callout to
scope the warning to "The Hypercerts SDK is in active development", or (B) if
you must keep the low-level `@atproto/api` snippet, change the callout to clearly
state that the warning applies only to the Hypercerts SDK and not to
`@atproto/api`, and change agent.login(...) to the OAuth flow used across the PR
for consistency; update the callout text accordingly and ensure unique
identifiers (BskyAgent, agent.login, createATProtoSDK, sdk.getRepository,
repo.records.create) are used to locate and modify the snippet.
In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md`:
- Around line 17-19: The table entry for the `from` property currently marks it
as Required (✅) but the comments and examples allow omission for anonymous
funding; update the `from` property row in the lexicon table to mark it as
Optional (change the Required column from ✅ to ❌) so the documentation matches
the anonymous-sender behavior described in the comments and examples for the
`from` field.
In `@pages/tools/sdk.md`:
- Around line 115-130: The snippet places JSX (the
QueryClientProvider/WagmiProvider/atproto.Provider tree) at top-level after
TypeScript statements, causing invalid TSX; wrap the example in a valid React
component or render function (e.g., create a functional component like function
AppRoot() { const queryClient = new QueryClient(); const atproto =
createATProtoReact({ config, queryClient }); return ( <QueryClientProvider
client={queryClient}> <WagmiProvider config={wagmiConfig}> <atproto.Provider>
<App /> </atproto.Provider> </WagmiProvider> </QueryClientProvider> ); } or show
usage via ReactDOM.render/ createRoot) so QueryClient, createATProtoReact,
QueryClientProvider, WagmiProvider, atproto.Provider and App appear inside a
return body rather than at top-level.
---
Outside diff comments:
In `@pages/getting-started/working-with-evaluations.md`:
- Around line 13-34: The snippet mixes OAuth configuration with a
session-restore call: the createATProtoSDK oauth block will not be used if you
call sdk.restoreSession("did:plc:evaluator123"); either remove the oauth config
and document that restoreSession expects a previously persisted session
(SessionStore/app-password style), or keep the oauth config and replace the
restoreSession call with the OAuth flow (call sdk.authorize(identifier) then
complete with sdk.callback(callbackParams) to obtain the session) so the example
consistently uses one authentication method (refer to createATProtoSDK, oauth,
sdk.restoreSession, sdk.authorize, and sdk.callback).
---
Nitpick comments:
In `@pages/lexicons/certified-lexicons/badge-response.md`:
- Line 21: Update the badge-response documentation to clarify that the `weight`
field is only meaningful when `response` equals `accepted`; specifically, modify
the table row for `weight` (the `weight` column entry) to add a comment noting
that `weight` should be set only for accepted responses and is ignored or
semantically invalid for `rejected` responses, and ensure the `response` field
is referenced so readers understand the conditional relationship between
`weight` and `response`.
In `@pages/lexicons/certified-lexicons/shared-defs.md`:
- Around line 23-29: Add a one-sentence descriptive note under the "Certified
Definitions" heading explaining the role of app.certified.defs and its
relationship to org.hypercerts.defs (for example: "app.certified.defs defines
shared types used by Certified-namespace lexicons and extends/aligns with common
types from org.hypercerts.defs"). Place this sentence immediately before the
table so readers understand that app.certified.defs contains definitions used by
Certified lexicons and how it relates to org.hypercerts.defs.
In `@pages/lexicons/hypercerts-lexicons/funding-receipt.md`:
- Around line 41-70: The example uses the low-level BskyAgent and
agent.api.com.atproto.repo.createRecord to publish an
org.hypercerts.funding.receipt, which is inconsistent with other docs that use
`@hypercerts-org/sdk-core`; either update this sample to call the SDK equivalent
(use the SDK client method that publishes receipts—replace BskyAgent usage with
the SDK client initializer and its publish/createReceipt method) or, if the SDK
does not yet support funding receipts, add a clear callout above the snippet
stating this is a temporary raw-API workaround and that SDK support for
org.hypercerts.funding.receipt will be added soon. Ensure you reference
BskyAgent, agent.api.com.atproto.repo.createRecord, and
org.hypercerts.funding.receipt in the change so reviewers can find and update
the snippet or add the callout.
In `@pages/tools/sdk.md`:
- Around line 259-272: Add the missing import for createATProtoSDK at the top of
the example so the snippet is runnable; import the factory from the SDK package
(e.g., import { createATProtoSDK } from '@atproto/sdk') and ensure the import
style matches the React hooks example and other snippets in the file so readers
know which package to import from.
Comment on lines
29
to
62
| {% callout %} | ||
| The SDK is in active development. Package names and API methods may change. | ||
| {% /callout %} | ||
|
|
||
| Acknowledge inclusion in an activity claim: | ||
|
|
||
| ```typescript | ||
| import { BskyAgent } from '@atproto/api' | ||
|
|
||
| const agent = new BskyAgent({ service: 'https://pds.example.com' }) | ||
| await agent.login({ identifier: 'your-handle', password: 'your-app-password' }) | ||
|
|
||
| const response = await agent.api.com.atproto.repo.createRecord({ | ||
| repo: agent.session.did, | ||
| collection: 'org.hypercerts.acknowledgement', | ||
| record: { | ||
| // The record being acknowledged (e.g. your contributor information) | ||
| subject: { | ||
| uri: 'at://did:plc:alice123/org.hypercerts.claim.contributorInformation/tid456', | ||
| cid: 'bafyrei...', | ||
| }, | ||
| // The record that includes it (e.g. the activity claim) | ||
| context: { | ||
| uri: 'at://did:plc:bob789/org.hypercerts.claim.activity/tid123', | ||
| cid: 'bafyrei...', | ||
| }, | ||
| // Acknowledge inclusion | ||
| acknowledged: true, | ||
| // Optional comment | ||
| comment: 'Confirming my contribution to this project.', | ||
| // Timestamp | ||
| createdAt: new Date().toISOString(), | ||
| }, | ||
| }) |
There was a problem hiding this comment.
Misleading callout and auth approach inconsistent with the rest of the PR.
Two issues in the code example section:
-
Callout mismatch: The callout warns that "The SDK is in active development" but the example uses
@atproto/api(BskyAgent) directly — not the Hypercerts SDK. The warning misleads readers into thinking@atproto/apiis unstable, and conversely gives false reassurance about the@hypercerts-org/*SDK to readers using it. Either update the callout to accurately scope its warning, or remove it from this page. -
App-password auth: This new page uses
agent.login({ identifier, password })— the app-password flow — while the PR explicitly migrates all other examples to OAuth (jwkPrivate). This creates a contradictory reference for developers reading adjacent pages.
🛠️ Suggested alignment
Either migrate to the OAuth pattern (consistent with the rest of the PR):
-{% callout %}
-The SDK is in active development. Package names and API methods may change.
-{% /callout %}
-
-Acknowledge inclusion in an activity claim:
-
-```typescript
-import { BskyAgent } from '@atproto/api'
-
-const agent = new BskyAgent({ service: 'https://pds.example.com' })
-await agent.login({ identifier: 'your-handle', password: 'your-app-password' })
-
-const response = await agent.api.com.atproto.repo.createRecord({
+{% callout %}
+The Hypercerts SDK is in active development. Package names and API methods may change.
+{% /callout %}
+
+Alternatively, use the Hypercerts SDK (see [SDK reference](/tools/sdk)):
+
+```typescript
+import { createATProtoSDK } from "@hypercerts-org/sdk-core";
+// ... OAuth setup (see Quickstart) ...
+const repo = sdk.getRepository(session);
+await repo.records.create({
repo: agent.session.did,
collection: 'org.hypercerts.acknowledgement',Or, if keeping the low-level @atproto/api example intentionally, update the callout to accurately reflect the scope:
-{% callout %}
-The SDK is in active development. Package names and API methods may change.
-{% /callout %}
+{% callout type="note" %}
+This example uses the low-level `@atproto/api` with app passwords for brevity. For production, use OAuth — see the [Quickstart](/getting-started/quickstart) and [SDK reference](/tools/sdk).
+{% /callout %}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| {% callout %} | |
| The SDK is in active development. Package names and API methods may change. | |
| {% /callout %} | |
| Acknowledge inclusion in an activity claim: | |
| ```typescript | |
| import { BskyAgent } from '@atproto/api' | |
| const agent = new BskyAgent({ service: 'https://pds.example.com' }) | |
| await agent.login({ identifier: 'your-handle', password: 'your-app-password' }) | |
| const response = await agent.api.com.atproto.repo.createRecord({ | |
| repo: agent.session.did, | |
| collection: 'org.hypercerts.acknowledgement', | |
| record: { | |
| // The record being acknowledged (e.g. your contributor information) | |
| subject: { | |
| uri: 'at://did:plc:alice123/org.hypercerts.claim.contributorInformation/tid456', | |
| cid: 'bafyrei...', | |
| }, | |
| // The record that includes it (e.g. the activity claim) | |
| context: { | |
| uri: 'at://did:plc:bob789/org.hypercerts.claim.activity/tid123', | |
| cid: 'bafyrei...', | |
| }, | |
| // Acknowledge inclusion | |
| acknowledged: true, | |
| // Optional comment | |
| comment: 'Confirming my contribution to this project.', | |
| // Timestamp | |
| createdAt: new Date().toISOString(), | |
| }, | |
| }) | |
| {% callout type="note" %} | |
| This example uses the low-level `@atproto/api` with app passwords for brevity. For production, use OAuth — see the [Quickstart](/getting-started/quickstart) and [SDK reference](/tools/sdk). | |
| {% /callout %} | |
| Acknowledge inclusion in an activity claim: | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pages/lexicons/hypercerts-lexicons/acknowledgement.md` around lines 29 - 62,
Update the example to be consistent with the PR: either (A) replace the
`@atproto/api` app-password example (BskyAgent + agent.login) with the OAuth
pattern used elsewhere (use createATProtoSDK / sdk.getRepository /
repo.records.create and the jwkPrivate OAuth flow) and change the callout to
scope the warning to "The Hypercerts SDK is in active development", or (B) if
you must keep the low-level `@atproto/api` snippet, change the callout to clearly
state that the warning applies only to the Hypercerts SDK and not to
`@atproto/api`, and change agent.login(...) to the OAuth flow used across the PR
for consistency; update the callout text accordingly and ensure unique
identifiers (BskyAgent, agent.login, createATProtoSDK, sdk.getRepository,
repo.records.create) are used to locate and modify the snippet.
- Replace 'ATProto' with 'AT Protocol' in prose (data-flow, funding-and-value-flow, indexers) - Add Constellation API stability caveat in indexers-and-discovery - Fix stale field name: cid → hypercertCid in testing-and-deployment - Fix funding-receipt from field: required → optional (matches lexicon) - Fix Wagmi snippet: wrap JSX in function component, use tsx language tag - Simplify tree diagram in creating-your-first-hypercert to match code - Update all 9 lexicon page callouts to clarify low-level API usage
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Aligns documentation with the develop branch SDK and Lexicon APIs, updates architecture pages, adds new reference pages, and fixes review feedback.
SDK & Lexicon alignment (develop branch)
Updated all 6 Get Started pages to match the develop branch SDK and Lexicon APIs:
rightsName/rightsType/rightsDescription→ SDK'sname/type/description$typediscriminators → SDKcontributionsarray ({ contributors, contributionDetails, weight })repo.evaluations.create()→repo.hypercerts.addEvaluation(),repo.measurements.create()→repo.hypercerts.addMeasurement(),repo.attachments.create()→repo.hypercerts.addAttachment()result.uri/result.cid→result.hypercertUri/result.hypercertCid/result.rightsUri/result.rightsCidcreatedAt: SDK sets this automaticallydescriptionfield: missing from most examplesATPROTO_CLIENT_SECRET→ATPROTO_JWK_PRIVATE; proper OAuth loopback config withhandleResolverArchitecture section updates
Updated all 5 Architecture pages:
Architecture stack diagram redesign
Fully redesigned
architecture-stack.svg:PDS / SDSreferenceHyperboards rewrite
Rewrote and renamed
hyperboard.md→hyperboards.mdbased on the actual hyperboards.org product:New pages
tools/sdk.md) — TypeScript SDK reference (packages, React hooks, Repository API, OAuth, type system)Core Concepts improvements
CodeRabbit review fixes (Round 1)
CodeRabbit review fixes (Round 2)
cid→hypercertCid(matches SDK return type)fromfield changed from required to optional (matches lexicon schema)tsx@atproto/apiusage vs SDKOther