docs: fix root README TS and Go quick-start snippets#594
Merged
Conversation
Same paper-cut as the Python snippet in #593: the TS and Go quick-start snippets call non-existent APIs. - TS: `Receipt.create()` / `receipt.sign()` — no `Receipt` symbol is exported from `@agnt-rcpt/sdk-ts`. Real API is `createReceipt({...})` and `signReceipt(unsigned, privateKey, verificationMethod)`. - Go: `receipt.New(receipt.WithAction(...))` / `r.Sign(privateKey)` — no `New` constructor or `WithAction` option exists. Real API is `receipt.Create(receipt.CreateInput{...})` and the package-level `receipt.Sign(unsigned, privateKeyPEM, verificationMethod)`. Both snippets now mirror the Python shape: generate key pair, build a full `Create…Input` struct (Issuer / Principal / Action / Outcome / Chain), then sign with a verification method DID. Verified by compiling each snippet against the in-tree SDK (Go: `go build`; TS: `tsc --strict`).
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes the root README SDK quick-start snippets so they use the actual Go and TypeScript functional APIs instead of nonexistent Receipt class/method-style APIs.
Changes:
- Updates the Go snippet to generate a key pair, create a receipt with
receipt.Create, and sign withreceipt.Sign. - Updates the TypeScript snippet to import and use
createReceipt,generateKeyPair, andsignReceipt. - Aligns the examples with the existing Python quick-start shape.
This was referenced May 26, 2026
ojongerius
added a commit
that referenced
this pull request
May 26, 2026
Adds a release-blocking gate that extracts the SDK quick-start snippets from the user-facing READMEs and compiles / type-checks each one — catching the recurring papercut (#593, #594) where a snippet calls a non-existent API, imports a wrong module path, or drifts behind a published rename. - scripts/readme_snippets/: a dependency-free Python harness. extract.py (pure, unit-tested) parses fenced blocks and assembles compilation units; check.py scaffolds a throwaway project and runs go build / tsc --noEmit / mypy against either the in-tree SDK (--source local) or the published artifact (--source published). - Default-in: every SDK-importing fenced block is checked, so a newly added snippet is covered without annotation. snippet-check directives (continues, skip) handle dependent and illustrative blocks. - readme-snippets.yml runs the in-tree check on every README-touching PR; the publish-* workflows run the published check at release time. Fixes drift the gate caught: - sdk/go/README.md used the stale module path github.com/agent-receipts/sdk-go instead of github.com/agent-receipts/ar/sdk/go (install + imports). - Root README Python quick-start passed action as a dict where CreateReceiptInput expects ActionInput; now uses ActionInput(...). Closes #595 https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu
ojongerius
added a commit
that referenced
this pull request
May 26, 2026
* docs(site): rewrite Quick Start to drive against the daemon (#625) * docs(site): rewrite Quick Start to drive against the daemon (closes #616) Lead every SDK section (Python, TypeScript, Go) with the daemon-mediated signing path per ADR-0022 D1: the SDK emits tool-call events over a Unix socket and the agent-receipts-daemon holds the Ed25519 key. Each section follows Install -> Start the daemon -> Emit -> Verify and ends with `agent-receipts verify` so the reader confirms the receipt landed. In-process signing is demoted to a clearly-labeled tutorial/testing-only appendix carrying the ADR-0022 D2 "Not for production" note. Replaces the stale attest_protocol imports. The page's posture now matches the homepage and daemon-setup, closing SITE-P3. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): address Quick Start review feedback Reorder the intro SDK list to Python/TypeScript/Go to match section order, check the TypeScript emit() return value, and drop the unused receipt_hash from the in-process appendix example. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): address second-round Quick Start review feedback Drop the @Alpha dist-tag from the TypeScript install (DaemonEmitter ships in stable 0.10.0; @Alpha resolves to an older prerelease that still exports the old Emitter name). Wrap the TypeScript example in an async main() with try/finally so it is copy/paste runnable and always closes the socket. Ignore the Go Close() error in the deferred call to stay errcheck-clean. Note AGENTRECEIPTS_CHAIN_ID alongside the DB and public-key overrides in every verify step. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): handle main() rejection in TS Quick Start snippet Adds .catch() with process.exitCode=1 to surface emit() errors deterministically across Node versions (Copilot review on #625). * docs(site): fix stale APIs and macOS socket path in Daemon Setup (#628) * docs(site): fix stale APIs and macOS socket path in Daemon Setup Brings `daemon-setup.mdx` into line with the shipped SDKs and `daemon/README.md`: - TypeScript snippets use `DaemonEmitter` (renamed from `Emitter` in @agnt-rcpt/sdk-ts 0.10.0). - TypeScript install drops `@alpha` — `DaemonEmitter` ships on the default tag; `@alpha` still resolves to the old `Emitter` name. - Go snippets use `emitter.NewDaemon` (current constructor; `emitter.New` no longer exists). - macOS default socket path moves from `$TMPDIR/agentreceipts/...` to `$XDG_DATA_HOME/agent-receipts/events.sock` (matches the daemon's actual resolver; `$TMPDIR` is not inherited by GUI-spawned processes, so the old path made the handshake fail silently on macOS — issue #545). Updates the troubleshooting `ls` example to the new macOS path and fixes one prose reference to `New()` → `NewDaemon()` in the same paragraph as the renamed snippets. Closes #627. * docs(site): address Copilot review on #628 - "Connect your emitters" paragraph: drop the incorrect claim that the Go SDK ignores `AGENTRECEIPTS_SOCKET` on non-macOS/Linux platforms. `emitter.DefaultSocketPath` consults the env var first on every host; `NewDaemon()` only errors when neither the env var nor an explicit socket-path option supplies a path. - Troubleshooting `ls`: switch the macOS example to `~/.local/share/agent-receipts/events.sock` (the absolute default fallback) instead of `${XDG_DATA_HOME:-...}`. The daemon and SDKs ignore a non-absolute `XDG_DATA_HOME` and fall back, so the previous shell expansion could point at the wrong path when the env var is set but invalid — same trap the verify section already avoids. * docs(site): clarify language scope + XDG_DATA_HOME caveat (Copilot round 2) - "Connect your emitters" paragraph: drop the Go-specific `NewDaemon()` reference, since the surrounding text applies to all SDKs. Use "the emitter constructor" and mention `WithSocketPath` only as a Go example so TS/Python readers aren't misdirected. - Troubleshooting: add a one-line caveat noting that the macOS `ls` example assumes the default fallback path; users with a custom `AGENTRECEIPTS_SOCKET` or absolute `XDG_DATA_HOME` should check their own path. Mirrors the caveat the verify section already carries. * ci: verify README code snippets against the SDK artifacts Adds a release-blocking gate that extracts the SDK quick-start snippets from the user-facing READMEs and compiles / type-checks each one — catching the recurring papercut (#593, #594) where a snippet calls a non-existent API, imports a wrong module path, or drifts behind a published rename. - scripts/readme_snippets/: a dependency-free Python harness. extract.py (pure, unit-tested) parses fenced blocks and assembles compilation units; check.py scaffolds a throwaway project and runs go build / tsc --noEmit / mypy against either the in-tree SDK (--source local) or the published artifact (--source published). - Default-in: every SDK-importing fenced block is checked, so a newly added snippet is covered without annotation. snippet-check directives (continues, skip) handle dependent and illustrative blocks. - readme-snippets.yml runs the in-tree check on every README-touching PR; the publish-* workflows run the published check at release time. Fixes drift the gate caught: - sdk/go/README.md used the stale module path github.com/agent-receipts/sdk-go instead of github.com/agent-receipts/ar/sdk/go (install + imports). - Root README Python quick-start passed action as a dict where CreateReceiptInput expects ActionInput; now uses ActionInput(...). Closes #595 https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu * ci: fail loudly on chained Go snippets instead of dropping them Self-review caught a silent gap: a `continues` directive before a Go block would render only the first block in the chain and silently drop the rest, leaving a snippet unchecked — the exact failure this gate exists to prevent. Go snippets are standalone, so raise a clear error instead. https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu * ci: address snippet-harness review feedback - TS check now reads typescript / @types/node from sdk/ts/package.json (the SDK builds on ~6.0.2 / ^25), so the gate matches the published .d.ts instead of an arbitrary pinned major. - Fail fast (exit 2) when a README path doesn't exist, instead of silently dropping it and reporting success — a path typo must not disable the gate. - Pin mypy (==2.1.0) so the gate is deterministic across runs. - Hoist Go imports verbatim so aliases (foo "pkg"), blank imports (_ "pkg"), and inline comments survive the package-shim rewrite. https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu * ci: address second-pass snippet-harness review feedback - Clear a pending snippet-check directive when an unrecognised one follows, so it can't leak onto the next fenced block. - Pin the temp TS project's typescript / @types/node to exact versions (strip the ^/~ range) so resolution is deterministic without a lockfile. - Use a conventional throwaway Go module path (example.com/readme-snippets). https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu
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
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
Same paper-cut as the Python snippet in #593, applied to the TS and Go quick-start snippets in the root README. Both reference a fictional
Receiptclass that does not exist in either SDK.TypeScript — README previously showed:
@agnt-rcpt/sdk-tsexportscreateReceipt,signReceipt,generateKeyPair, etc. There is noReceiptsymbol — the import fails at module-load time.Go — README previously showed:
sdk/go/receiptprovidesCreate(CreateInput) UnsignedAgentReceiptand the package-levelSign(unsigned, privateKeyPEM, verificationMethod) (AgentReceipt, error). There is noNew, noWithActionfunctional option, andSignis not a method on a receipt value — it takes three required args.Both snippets now mirror the Python shape: generate a key pair, build a full
Create…Inputstruct (Issuer / Principal / Action / Outcome / Chain), then sign with a verification method DID.Verification
go build).tsc --strict.Follow-up worth tracking
Three identical bugs slipping through three releases is the signal that there's no gate here. Suggest a release-blocking CI job that extracts every fenced code block from
README.md(and SDK READMEs) and tries to build/type-check it against the published artifact — same idea as the P0-1 item in the audit synthesis. Happy to open a tracking issue if useful.