zk-email-sdk-js Development
You are helping develop the **ZK Email SDK**, a TypeScript library that enables creating zero-knowledge proofs about emails using regex-based blueprints. It supports both local (browser) and remote (server) proof generation, integrates with Gmail/Outlook OAuth, and provides on-chain verification capabilities.
Project Architecture
Core Classes
**`Blueprint`** (`src/types/Blueprint.ts`) - Manages regex patterns and circuit compilation**`Prover`** (`src/prover/`) - Abstract base with SP1 and Circom implementations, NoirProver implementation separate. Used for proof generation.**`Proof`** (`src/types/Proof.ts`) - Represents generated proofs with verification methods**`Gmail`/`Outlook`** (`src/login_for_email/`) - OAuth and email fetching implementationsKey Design Patterns
**Factory Pattern**: SDK initialization via `zkSdk({ baseUrl, auth })`**Strategy Pattern**: Local vs remote proof generation strategiesEntry Points
Main SDK: `src/index.ts`Noir WASM initializer: `src/noir-wasm-initializer.ts`Web Worker: `src/prove-worker.ts`Directory Structure
`src/types/` - TypeScript definitions for all components`src/prover/` - Proof generation logic (abstract and Noir implementations)`src/login_for_email/` - OAuth flows for Gmail/Microsoft`src/chain/` - On-chain verification utilities`src/utils/` - Utility functions (hashing, file operations)`browser_test_proving/` - Browser environment testing`emls/` - Sample email files for testingDevelopment Workflow
1. Making Code Changes
Before modifying any code:
Understand the factory and strategy patterns used throughoutReview existing TypeScript types in `src/types/`Check if changes affect local/remote proving strategies2. Building the Project
```bash
Main build (ESM/CJS bundles)
bun run build
Build Web Worker for local proving
bun run build-prove-worker
Type checking
bun run typecheck
Clean build artifacts
bun run clean
```
**Build Process Details:**
Vite builds worker with inlined dependenciesScript converts to string (`localProverWorkerString.ts`)Generates dual ESM/CommonJS formatsIncludes browser/Node.js polyfills for compatibility3. Managing Changes (CHANGELOG)
When making changes, add entries to the `[Unreleased]` section in `CHANGELOG.md`:
**Categories:**
**Added** - New features**Changed** - Changes in existing functionality**Deprecated** - Soon-to-be removed features**Removed** - Removed features**Fixed** - Bug fixes**Security** - Vulnerability fixes**Breaking Changes:**
Mark with `**BREAKING**` and provide migration examples.
4. Versioning (Semantic Versioning)
**MAJOR** (2.0.0): Breaking changes (e.g., export pattern changes)**MINOR** (1.X.0): New features, backwards compatible**PATCH** (1.0.X): Bug fixesRelease Process
When asked to "release", "publish", or "create a new version":
Step 1: Analyze Changes
Check `CHANGELOG.md` `[Unreleased]` section to determine version type:
Breaking changes → MajorNew features → MinorBug fixes → PatchStep 2: Pre-release Checks
```bash
Verify clean working tree
git status
Confirm on main branch
git branch
Verify changelog has content
grep "\[Unreleased\]" CHANGELOG.md
```
Step 3: Execute Release
**Using release script:**
```bash
./scripts/release.sh [patch|minor|major]
```
**Manual process:**
1. Update `package.json` version
2. Update `CHANGELOG.md` (move `[Unreleased]` to versioned section with date)
3. Commit: `chore: release vX.X.X`
4. Tag: `git tag vX.X.X`
5. Run: `bun run publish`
6. Push: `git push && git push --tags`
7. Create GitHub release
Step 4: Report
Inform user of:
New version numberNPM package linkGitHub release linkImportant Notes
Testing
Tests are currently not working due to API changesDO NOT use test commands until they are fixedPublishing
DO NOT publish yourself without authorization**Nightly releases**: Version with suffix (e.g., 1.4.0-18), keep changes in `[Unreleased]`**Production releases**: Update version, move `[Unreleased]` to dated sectionBuild Artifacts
Dual bundle support (ESM/CommonJS)Web Worker bundled as string for cross-bundler compatibilityMultiple entry points for different use casesCommon Tasks
Adding a New Feature
1. Implement in appropriate `src/` directory
2. Update TypeScript types in `src/types/` if needed
3. Add entry to `CHANGELOG.md` under `[Unreleased] - Added`
4. Run `bun run typecheck`
5. Run `bun run build`
Fixing a Bug
1. Locate and fix the issue
2. Add entry to `CHANGELOG.md` under `[Unreleased] - Fixed`
3. Run `bun run typecheck`
4. Run `bun run build`
Breaking Change
1. Make the change
2. Add `**BREAKING**` entry to `CHANGELOG.md` with migration guide
3. Prepare for major version bump
4. Update documentation
Resources
Repository: https://github.com/zkemail/zk-email-sdk-jsBlueprint Registry: Integration with ZK Email circuit registry