beads: add docs task hypercerts-sdk-dii.6

Author: Kzoeps

.beads/issues.jsonl

@@ -25,6 +25,7 @@
 {"id":"hypercerts-sdk-dii.3","title":"Remove hardcoded scope override in buildClientMetadata for loopback","description":"## Files\n- packages/sdk-core/src/auth/OAuthClient.ts (modify)\n\n## What to do\nIn `buildClientMetadata()` (line 231), line 241 currently reads:\n```ts\nconst metadataScope = isLoopback ? \"atproto transition:generic\" : this.config.oauth.scope;\n```\n\nThis has the same hardcoding problem as `buildClientId()`. The loopback branch overrides the user's configured scope with \"atproto transition:generic\".\n\nChange line 241 to simply use the config scope for all cases:\n```ts\nconst metadataScope = this.config.oauth.scope;\n```\n\nOr remove the `metadataScope` variable entirely and use `this.config.oauth.scope` directly on line 257 where it is assigned to `scope: metadataScope`.\n\nEither approach is fine — the key point is that the metadata body scope must match the config scope, which will now also match the scope embedded in the loopback client_id URL (after the sibling task is done).\n\n## Dont\n- Do NOT change `buildClientId()` (that is a separate task)\n- Do NOT change `authorize()` or `validateClientMetadataScope()`\n- Do NOT change test files in this task","acceptance_criteria":"1. Line 241 no longer hardcodes \"atproto transition:generic\" for loopback clients\n2. The metadata scope always uses `this.config.oauth.scope` regardless of loopback vs non-loopback\n3. `pnpm --filter @hypercerts-org/sdk-core build` succeeds","status":"closed","priority":1,"issue_type":"task","assignee":"karma.gainforest.id","owner":"karma.gainforest.id","estimated_minutes":10,"created_at":"2026-02-20T19:39:40.249158586+06:00","created_by":"karma.gainforest.id","updated_at":"2026-02-20T19:39:52.163858806+06:00","closed_at":"2026-02-20T19:39:52.163865039+06:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-sdk-dii.3","depends_on_id":"hypercerts-sdk-dii","type":"parent-child","created_at":"2026-02-20T19:39:40.250479571+06:00","created_by":"karma.gainforest.id"}]}
 {"id":"hypercerts-sdk-dii.4","title":"Use configured scope everywhere instead of hardcoding atproto transition:generic","description":"## Files\n- packages/sdk-core/src/auth/OAuthClient.ts (modify)\n\n## What to do\nTwo changes in the same file, both removing hardcoded \"atproto transition:generic\" in favor of the configured scope:\n\n### Change 1: `buildClientId()` method (starts at line 181)\n1. Rename the `_scope` parameter back to `scope` (remove underscore prefix)\n2. Change line 189 from:\n   ```ts\n   loopbackUrl.searchParams.set(\"scope\", \"atproto transition:generic\");\n   ```\n   to:\n   ```ts\n   loopbackUrl.searchParams.set(\"scope\", scope);\n   ```\n3. Update the info log message (lines 194-195) to be dynamic:\n   ```ts\n   `Development mode: using loopback client_id http://localhost with scope \"${scope}\"`\n   ```\n   Also add `scope` to the log context object alongside `originalClientId` and `generatedClientId`.\n4. Update the JSDoc for the `_scope` param (line 176) — change from \"(ignored - always uses \\\"atproto transition:generic\\\")\" to \"The OAuth scope to embed in the loopback client_id URL\"\n\n### Change 2: `buildClientMetadata()` method (starts at line 231)\nLine 241 currently reads:\n```ts\nconst metadataScope = isLoopback ? \"atproto transition:generic\" : this.config.oauth.scope;\n```\nChange to:\n```ts\nconst metadataScope = this.config.oauth.scope;\n```\nOr remove the `metadataScope` variable entirely and use `this.config.oauth.scope` directly on line 257.\n\n## Dont\n- Do NOT change the `authorize()` method\n- Do NOT change `validateClientMetadataScope()`\n- Do NOT change any test files\n- Do NOT add any new validation logic — scope validation already exists in `validateClientMetadataScope()`","acceptance_criteria":"1. `buildClientId()` uses the `scope` parameter (not `_scope`) to set the scope query param\n2. `buildClientMetadata()` uses `this.config.oauth.scope` for all cases (no loopback ternary)\n3. The string \"atproto transition:generic\" does NOT appear anywhere in `buildClientId()` or in the `metadataScope` assignment\n4. The info log message dynamically includes the actual scope value\n5. `pnpm --filter @hypercerts-org/sdk-core build` succeeds\n6. No lint errors: `pnpm --filter @hypercerts-org/sdk-core lint`","status":"closed","priority":1,"issue_type":"task","assignee":"karma.gainforest.id","owner":"karma.gainforest.id","estimated_minutes":20,"created_at":"2026-02-20T19:40:07.79581627+06:00","created_by":"karma.gainforest.id","updated_at":"2026-02-20T19:42:26.387491921+06:00","closed_at":"2026-02-20T19:42:26.387491921+06:00","close_reason":"bd7b3e7 use configured scope in loopback client_id","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-sdk-dii.4","depends_on_id":"hypercerts-sdk-dii","type":"parent-child","created_at":"2026-02-20T19:40:07.797293453+06:00","created_by":"karma.gainforest.id"}]}
 {"id":"hypercerts-sdk-dii.5","title":"Add changeset for loopback scope fix","description":"## Files\n- .changeset/\u003crandom-name\u003e.md (create)\n\n## What to do\nCreate a changeset for the loopback scope fix. This is a **patch** change to `@hypercerts-org/sdk-core`.\n\nUse the writing-changesets skill to create the changeset. The summary should explain that loopback OAuth clients now use the configured scope instead of hardcoding \"atproto transition:generic\", ensuring the client_id URL, metadata body, and authorize call all use the same scope from config.\n\n## Dont\n- Do NOT create changesets for sdk-react (it is not affected)\n- Do NOT bump to minor — this is a bugfix (patch)","acceptance_criteria":"1. A changeset file exists in .changeset/ with @hypercerts-org/sdk-core as patch\n2. The changeset summary accurately describes the behavioral change","status":"closed","priority":2,"issue_type":"task","assignee":"karma.gainforest.id","owner":"karma.gainforest.id","estimated_minutes":10,"created_at":"2026-02-20T19:40:22.787093098+06:00","created_by":"karma.gainforest.id","updated_at":"2026-02-20T19:44:42.017915418+06:00","closed_at":"2026-02-20T19:44:42.017915418+06:00","close_reason":"0f0de87 add changeset for loopback scope fix","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-sdk-dii.5","depends_on_id":"hypercerts-sdk-dii","type":"parent-child","created_at":"2026-02-20T19:40:22.789681119+06:00","created_by":"karma.gainforest.id"},{"issue_id":"hypercerts-sdk-dii.5","depends_on_id":"hypercerts-sdk-dii.2","type":"blocks","created_at":"2026-02-20T19:40:22.791946031+06:00","created_by":"karma.gainforest.id"}]}
+{"id":"hypercerts-sdk-dii.6","title":"Update docs and JSDoc to remove misleading loopback scope auto-set claims","description":"## Files\n- packages/sdk-core/README.md (modify)\n- packages/sdk-core/src/auth/OAuthClient.ts (modify — JSDoc only)\n- packages/sdk-core/src/core/config.ts (modify — JSDoc only)\n- CERTS_SDK.md (modify)\n\n## What to do\n\nAfter the scope fix (dii.4), the SDK no longer hardcodes \"atproto transition:generic\" for loopback clients — it uses whatever the user configures. Several docs and JSDoc comments still claim otherwise. Fix them:\n\n### 1. `packages/sdk-core/README.md` (line 72-73)\nThe comment says:\n```\n// scope can be blank the sdk will automatically set it to \"atproto transition:generic\" in the client_id config\nscope: \"\",\n```\nThis is wrong on two counts: (a) scope is no longer auto-set to \"atproto transition:generic\", and (b) scope cannot be blank — the Zod schema requires `z.string().min(1)` and the @atproto library requires \"atproto\" in the scope. Change to:\n```\n// Scope must include \"atproto\" — this is the minimum required by the AT Protocol spec\nscope: \"atproto\",\n```\n\n### 2. `packages/sdk-core/src/auth/OAuthClient.ts` (line 51)\nThe JSDoc example shows `scope: \"atproto transition:generic\"`. This is fine as an example (it is a valid scope), but make sure there is no comment suggesting it is auto-set or hardcoded for loopback. Currently it looks fine — just verify no misleading text remains.\n\n### 3. `packages/sdk-core/src/core/config.ts` (lines 112, 244)\nThese are JSDoc examples showing `scope: \"atproto transition:generic\"`. These are fine as examples of valid scope values. No change needed unless there is misleading commentary around them.\n\n### 4. `CERTS_SDK.md` (lines 43, 87, 565, 675)\nThese show `scope: \"atproto transition:generic\"` in example configs. These are fine as examples — they show a valid scope. No change needed unless there is commentary claiming the scope is auto-set or ignored for loopback.\n\n**The main fix is item #1 (README.md).** Items 2-4 are verify-only — change them only if they contain misleading claims about scope being auto-set.\n\n## Dont\n- Do NOT change any runtime code (only docs, comments, JSDoc)\n- Do NOT change test files\n- Do NOT remove \"atproto transition:generic\" from examples where it is used as a valid example scope value — it is still a valid scope, just no longer hardcoded","acceptance_criteria":"1. The README.md no longer claims scope can be blank or will be auto-set\n2. The README.md example uses a valid non-empty scope (e.g. \"atproto\")\n3. No doc or JSDoc comment in the codebase claims the SDK hardcodes or auto-sets scope for loopback clients\n4. `pnpm --filter @hypercerts-org/sdk-core build` succeeds\n5. `pnpm --filter @hypercerts-org/sdk-core lint` passes","status":"open","priority":2,"issue_type":"task","owner":"karma.gainforest.id","estimated_minutes":20,"created_at":"2026-02-20T20:16:39.431509484+06:00","created_by":"karma.gainforest.id","updated_at":"2026-02-20T20:16:39.431509484+06:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-sdk-dii.6","depends_on_id":"hypercerts-sdk-dii","type":"parent-child","created_at":"2026-02-20T20:16:39.433104625+06:00","created_by":"karma.gainforest.id"}]}
 {"id":"hypercerts-sdk-eww","title":"Epic: Resolve CodeRabbit review for PR #131","description":"Resolve remaining open CodeRabbit inline review comment on PR #131. 1 comment in packages/sdk-core/README.md about clientId URL form inconsistency (missing trailing slash).","status":"closed","priority":3,"issue_type":"epic","owner":"karma.gainforest.id","created_at":"2026-02-20T15:19:18.075148138+06:00","created_by":"karma.gainforest.id","updated_at":"2026-02-20T15:21:28.32000638+06:00","closed_at":"2026-02-20T15:21:28.32000638+06:00","close_reason":"45a460d All child tasks complete: trailing slash fix applied","labels":["scope:trivial"]}
 {"id":"hypercerts-sdk-eww.1","title":"Fix clientId URL trailing slash inconsistency in README","description":"## Files\n- packages/sdk-core/README.md (modify)\n\n## What to do\nLine 131 contains a manually-constructed clientId example URL: `http://localhost?scope=...`\nLine 141 recommends using `http://localhost/` (with trailing slash).\n\nThese are inconsistent. `http://localhost?...` resolves to an empty path, while `http://localhost/` has an explicit root path. Some AT Protocol authorization servers may normalize or validate them differently.\n\nFix: On line 131, change `http://localhost?scope=` to `http://localhost/?scope=` (add trailing slash before the query string).\n\nCodeRabbit comment: https://github.com/hypercerts-org/hypercerts-sdk/pull/131#discussion_r2831500873\n\n## Don't\n- Change any other URLs in the README\n- Modify any code files\n- Change the query parameters or their encoding\n- Touch lines 141-142 (they are already correct)","acceptance_criteria":"1. Line 131 of packages/sdk-core/README.md contains `http://localhost/?scope=` (with trailing slash before query string)\n2. Lines 141-142 are unchanged\n3. No other files are modified\n4. pnpm build succeeds","status":"closed","priority":3,"issue_type":"task","assignee":"karma.gainforest.id","owner":"karma.gainforest.id","estimated_minutes":10,"created_at":"2026-02-20T15:19:28.823599913+06:00","created_by":"karma.gainforest.id","updated_at":"2026-02-20T15:21:06.010913316+06:00","closed_at":"2026-02-20T15:21:06.010913316+06:00","close_reason":"45a460d fix clientId URL trailing slash in README","labels":["scope:trivial"],"dependencies":[{"issue_id":"hypercerts-sdk-eww.1","depends_on_id":"hypercerts-sdk-eww","type":"parent-child","created_at":"2026-02-20T15:19:28.825105507+06:00","created_by":"karma.gainforest.id"}]}
 {"id":"hypercerts-sdk-fi6","title":"Add RichText utility for creating facets from text","description":"Create a utility function that uses @atproto/api's RichText class to automatically detect and create facets (mentions, links, hashtags) from plain text. This allows users to write natural text like 'Led by @alice with support from https://example.org #sustainability' and have facets auto-generated. Export this as a helper function from the SDK.","notes":"## Source\nFrom: specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md (Change 2)\nCHANGELOG: PR #91 - Add rich text facet support to activity claim descriptions\n\n## What Changed\n- Added shortDescriptionFacets and descriptionFacets fields to activity lexicon\n- Supports mentions, URLs, hashtags, etc. in activity descriptions\n\n## ✅ COMPLETED\n\n### Implementation\nCreated RichText utility in `src/lib/rich-text.ts`:\n- `createFacetsFromText(text, agent?)` - async, resolves mentions if agent provided\n- `createFacetsFromTextSync(text)` - sync, fast detection without mention resolution\n- Re-exports `RichText` class from @atproto/api for advanced usage\n- Exports `RichTextResult` and `AppBskyRichtextFacet` types\n\n### Exports added to index.ts\n- `createFacetsFromText`\n- `createFacetsFromTextSync`\n- `RichText`\n- `RichTextResult` (type)\n- `AppBskyRichtextFacet` (type)\n\n### Tests\nAdded 11 tests in `tests/lib/rich-text.test.ts`:\n- URL detection\n- Hashtag detection\n- Mention detection (without resolution)\n- Multiple facet types\n- Plain text handling\n- Empty text handling\n- Byte index calculation\n- Async version\n- Hypercert description example\n- RichText class export\n- Segment iteration\n\n## Validation\n- [x] Format check passes\n- [x] Lint passes\n- [x] Typecheck passes\n- [x] Build passes (with unrelated attachment warnings)\n- [x] Tests pass (11/11)\n- [x] RichText utility is exported correctly\n\n## Changeset\n- Type: minor (new feature available)\n- TODO: Create changeset file\n\nIMPORTANT: Keep this issue in sync with the source .md file.","status":"closed","priority":2,"issue_type":"task","owner":"adam@hypercerts.org","created_at":"2026-01-27T16:47:14.717746859+13:00","created_by":"Adam Spiers","updated_at":"2026-01-28T10:48:19.158564312+13:00","closed_at":"2026-01-28T10:48:19.158574762+13:00"}