Add comprehensive examples and integration guide for third-party SDK consumers

[Just-Bamford]

Summary

The @anonvote/crypto package is feature-complete but has no guide
for third-party developers on how to integrate it or build on top of
AnonVote. The README has API reference but no examples showing real
workflows (create ballot, generate tokens, encrypt votes, verify
results). Without this, a new developer downloading the package has
no clear path to using it productively. Comprehensive examples and an
integration guide unlock the Milestone 3 ecosystem goal.

Background

The js/README.md has a Usage section with a small code snippet but
no end-to-end example. There is no guide on how to:

• Generate a ballot encryption key
• Create tokens for voters
• Encrypt and decrypt votes
• Verify results on-chain
• Handle errors

Scope

Documentation

• Create js/INTEGRATION_GUIDE.md with:

  • Step-by-step walkthrough of a complete ballot lifecycle (create
    ballot → generate key → issue tokens → encrypt votes → tally)
  • Code examples for each step using the SDK
  • Error handling examples (catching AnonVoteCryptoError)
  • Common pitfalls and how to avoid them (e.g., key storage, token
    security)
  • FAQ section covering: key rotation, token reuse, encryption
    performance, type safety

• Create js/examples/ directory with working code samples:

  • examples/basic-ballot.ts — create a ballot and encrypt a vote
  • examples/token-generation.ts — generate and hash tokens
  • examples/error-handling.ts — catch and handle errors
  • examples/type-usage.ts — using exported types

• Add a "Getting Started" section to js/README.md that links to the
  integration guide and examples

• Add TypeDoc comments to all exported functions showing example usage

Tests

• Verify all code examples in examples/ directory compile and run
• Add a test that runs all examples to ensure they don't break on
  future changes

Relevant Files

• js/INTEGRATION_GUIDE.md (new)
• js/examples/ (new directory with samples)
• js/README.md (add Getting Started)
• js/src/crypto.ts (add TypeDoc examples)
• js/tests/examples.test.ts (new, runs examples)

Acceptance Criteria

• INTEGRATION_GUIDE.md created with lifecycle walkthrough
• At least 4 working code examples in examples/ directory
• All examples compile without errors
• All TypeDoc comments include usage examples
• README updated with "Getting Started" section
• Integration guide covers error handling and common pitfalls
• Tests verify examples work and don't break on changes

Out of Scope

• Video tutorials — written guides only
• Framework-specific examples (React, Vue, etc.) — framework-agnostic only

Note for Contributors

This is your chance to show developers how to use AnonVote. Make
examples realistic and production-grade. A developer reading this
guide should feel confident building an integration. Include error
handling, not just happy paths.

[pgreat123]

I'm a full-stack developer with blockchain experience. I care about this issue because a feature-complete SDK that nobody can onboard to is basically a wasted milestone, and I want to fix that gap.

My approach:

1. I'll write js/INTEGRATION_GUIDE.md walking through the full ballot lifecycle end to end: generate a ballot encryption key, create voter tokens, encrypt votes, then tally and verify results on-chain, with working code at every step.
2. I'll build out js/examples/ with four runnable samples: basic-ballot.ts, token-generation.ts, error-handling.ts (showing how to catch AnonVoteCryptoError properly), and type-usage.ts. I want these to feel production-grade, not like toy snippets.
3. I'll add a "Getting Started" section to js/README.md that links to the guide and examples, and I'll add TypeDoc usage examples on all exported functions in js/src/crypto.ts.
4. I'll cover the pitfalls that actually trip people up, like key storage, key rotation, token reuse, and encryption performance, as an FAQ section in the guide.
5. I'll add js/tests/examples.test.ts so the examples compile and run in CI, which keeps them from silently breaking as the SDK evolves. I'll also confirm tsc -b, lint, and format:check all pass before submitting.

I can submit this within 4 days.

[grantfox-oss]

🦊 GrantFox — @pgreat123 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #30)
2. Your PR will be reviewed by the AnonVote maintainers

Good luck! Track your progress on GrantFox.