# Interview Brief: Lite Entry Point

**Feature Name:** lite-entry-point
**Date:** 2026-03-18

## Problem & Goals

### Problem
The avo-inspector npm package includes dev/staging-only modules (AvoEncryption + @noble/curves, eventSpec/* + safe-regex2) that are never used in production. Customers who bundle the SDK into a single ES5 file for GTM (Google Tag Manager) get ~35 KB gzipped. Dynamic imports and ESM code-splitting help webpack/rollup consumers but don't help customers who use terser standalone or unknown bundlers — the dev code is still physically present in the bundle.

### Solution
Ship a pre-built "lite" entry point at `avo-inspector/lite` that physically excludes all dev/staging-only code. No encryption, no event spec validation, no @noble/curves, no safe-regex2. Works universally with any toolchain — the code simply isn't there.

### Success Criteria
- Lite bundle under 7 KB gzipped (when bundled + terser minified by customer)
- Drop-in replacement: same async API signature as the full version
- Works universally: any bundler, terser standalone, no flags/config needed
- Full entry point ("avo-inspector") stays unchanged
- No breaking changes for existing consumers

## Scope

### In Scope
1. Create a lite version of AvoInspector that excludes:
   - AvoEncryption.ts (and its @noble/curves dependency)
   - eventSpec/ directory (AvoEventSpecCache, AvoEventSpecFetcher, EventValidator)
   - safe-regex2 dependency
   - All event spec validation logic
   - All encryption logic
2. New entry point: `avo-inspector/lite` → `dist/lite/index.js`
3. Update package.json `"exports"` to include the lite path
4. Separate tsconfig for the lite build
5. Tests verifying the lite build works correctly

### Out of Scope
- Changes to the full entry point
- ESM dual build for lite (can be added later)
- CDN/script-tag lite bundle
- Changes to the existing `fester/sdk-size-reduction` branch work

## API Decisions

### Constructor options
- `publicEncryptionKey` is **removed from the types** in the lite build. TypeScript will error if a customer passes it. This makes the lite/full distinction explicit.

### Async behavior
- `trackSchemaFromEvent` remains async (returns `Promise<EventProperty[]>`) — same signature as the full version. Drop-in replacement, no customer code changes needed beyond the import path.

### What lite AvoInspector does
- Schema extraction (AvoSchemaParser without encryption)
- Batched network calls (AvoBatcher + AvoNetworkCallsHandler)
- Deduplication (AvoDeduplicator)
- Storage (AvoStorage)
- Session/installation tracking
- All the same tracking behavior, just no encryption and no validation

### What lite AvoInspector does NOT do
- No property value encryption (canSendEncryptedValues always returns false)
- No event spec fetching
- No event spec validation
- No EventValidator, EventSpecCache, EventSpecFetcher classes
- No @noble/curves or safe-regex2 dependencies

## Implementation Approach

The lite build should be a **separate source entry point** that imports a modified AvoInspector (or the same one with dev code paths removed at the source level). Options:

**Option A: Separate lite source files**
- Create `src/lite/index.ts` that exports a stripped AvoInspector
- Create `src/lite/AvoInspectorLite.ts` that's a copy of AvoInspector without eventSpec imports and with encryption always disabled
- Create `src/lite/AvoSchemaParserLite.ts` without encryption
- Separate tsconfig: `tsconfig.lite.json` compiling `src/lite/` → `dist/lite/`

**Option B: Conditional compilation / build-time stripping**
- Use a build script to strip dev-only code from the full source
- More complex, harder to maintain

**Option C: Re-export with stubs**
- `src/lite/index.ts` re-exports from the main source but with stub modules that replace the dev-only ones
- e.g., AvoSchemaParser.extractSchema never encrypts, AvoInspector constructor never inits eventSpec

The interview suggests Option A or C. The key is that the lite dist/ must physically not contain AvoEncryption, eventSpec/*, or their dependencies.

## Affected Areas

| Area | Files/Modules | Impact |
|------|--------------|--------|
| Package config | package.json | Add "exports" for "./lite", add to "files" |
| Build config | tsconfig.lite.json (new) | Compile lite source to dist/lite/ |
| Lite source | src/lite/ (new directory) | Lite entry point and modified classes |
| Lite schema parser | src/lite/ or shared | extractSchema without encryption |
| Lite inspector | src/lite/ or shared | AvoInspector without eventSpec |
| Tests | src/__tests__/ | New tests for lite build |

## Edge Cases

| Case | Expected Behavior |
|------|------------------|
| Customer passes publicEncryptionKey | TypeScript compile error (removed from lite types) |
| Customer uses dev env with lite build | Works, but no validation or encryption — just schema tracking |
| Customer imports from "avo-inspector/lite" in Node.js | Resolves to dist/lite/index.js via exports map |
| Customer's bundler doesn't support exports map | Falls back — may need documented alternative import path |
| Customer switches from full to lite | Only change is import path; all tracking methods work the same |

## Acceptance Criteria
- [ ] `avo-inspector/lite` resolves to `dist/lite/index.js`
- [ ] Lite build does NOT contain AvoEncryption, eventSpec/*, @noble/curves, or safe-regex2 code
- [ ] `import { AvoInspector, AvoInspectorEnv } from "avo-inspector/lite"` works
- [ ] AvoInspector lite constructor does NOT accept publicEncryptionKey option
- [ ] trackSchemaFromEvent returns Promise<EventProperty[]> (same async signature)
- [ ] trackSchemaFromEvent correctly extracts schema (without encryption)
- [ ] trackSchema works correctly
- [ ] extractSchema works correctly (without encryption)
- [ ] Batching and network calls work correctly
- [ ] Lite gzipped bundle < 7 KB (when customer bundles + terser minifies)
- [ ] Full entry point ("avo-inspector") is unchanged
- [ ] yarn build compiles both full and lite
- [ ] All existing tests still pass
- [ ] New tests verify lite-specific behavior
- [ ] npm pack --dry-run shows lite files included

## Open Questions
- Should AvoStreamId be exported from the lite entry point? (Probably yes, for parity)
- Should we re-use the same AvoSchemaParser but with encryption always disabled, or create a separate lite parser? (Implementation decision — prefer reuse if clean)