@bugspotter/sdk 0.3.0 → 1.0.0

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/CHANGELOG.md

@@ -5,176 +5,123 @@ All notable changes to the BugSpotter SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.2.5-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.2.4-alpha.5...sdk-v0.2.5-alpha.5) (2026-01-08)
+## [1.0.0] - 2026-01-17
 
+### Changed
 
-### Features
+- **Stable Release**: First production-ready 1.0.0 release
+- Improved code quality and readability across core modules
+- Enhanced test infrastructure with better Node.js and browser compatibility
+- Optimized transport layer and URL validation logic
 
-* **sdk:** filter SDK internal logs and API calls from bug reports ([#584](https://github.com/apexbridge-tech/bugspotter/issues/584)) ([ab25673](https://github.com/apexbridge-tech/bugspotter/commit/ab25673abe1ac4f71caaffbd74119eedbefaa208))
+### Fixed
 
-## [0.2.4-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.2.3-alpha.5...sdk-v0.2.4-alpha.5) (2026-01-06)
+- E2E test compatibility issues in Playwright test suite
+- Integration test Node.js Buffer API compatibility
+- ESLint configuration for test environment globals
 
+## [0.3.1] - 2026-01-13
 
-### Features
-
-* add upload progress feedback and screenshot proxy endpoint ([#565](https://github.com/apexbridge-tech/bugspotter/issues/565)) ([d0dd05f](https://github.com/apexbridge-tech/bugspotter/commit/d0dd05f96b6006af8f98ae9aab25ad82758bd80f))
-
-## [0.2.3-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.2.2-alpha.5...sdk-v0.2.3-alpha.5) (2026-01-03)
-
-
-### Features
-
-* release SDK 0.3.0 with duplicate prevention system ([#532](https://github.com/apexbridge-tech/bugspotter/issues/532)) ([c61b8c8](https://github.com/apexbridge-tech/bugspotter/commit/c61b8c8e9ed99d0ef9b95e7422ed82b41a93a561))
-
-## [0.2.2-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.2.1-alpha.5...sdk-v0.2.2-alpha.5) (2025-11-24)
-
-
-### Features
-
-* **sdk:** Add mouse event sampling settings support ([#313](https://github.com/apexbridge-tech/bugspotter/issues/313)) ([dd49bd0](https://github.com/apexbridge-tech/bugspotter/commit/dd49bd0fba99be1b3c6043669c9df8c4ae04f8c9))
-
-
-### Bug Fixes
-
-* **ci:** auto-format CHANGELOG in release-please PRs ([#300](https://github.com/apexbridge-tech/bugspotter/issues/300)) ([35a5541](https://github.com/apexbridge-tech/bugspotter/commit/35a5541450d75029964d060587784682f2ac3613))
-
-## [0.2.1-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.2.0-alpha.5...sdk-v0.2.1-alpha.5) (2025-11-21)
-
-### Bug Fixes
-
-- **test:** load rrweb from CDN for replay verification ([#297](https://github.com/apexbridge-tech/bugspotter/issues/297)) ([cbd575f](https://github.com/apexbridge-tech/bugspotter/commit/cbd575f4ab50da7b81df5be13d8a48fd48f391e6))
-
-### Documentation
-
-- **sdk:** update README to mention session replay feature ([#298](https://github.com/apexbridge-tech/bugspotter/issues/298)) ([28535c2](https://github.com/apexbridge-tech/bugspotter/commit/28535c2cf9df4deaebb96a92a4503a7371813142))
-
-## [0.2.0-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.1.3-alpha.5...sdk-v0.2.0-alpha.5) (2025-11-21)
-
-### ⚠ BREAKING CHANGES
-
-- **sdk:** BugSpotter.init() is now async and returns Promise<BugSpotter>. All callers must use `await BugSpotter.init(config)` instead of `BugSpotter.init(config)`. This change enables fetching replay quality settings from the backend before SDK initialization.
-
-### Features
-
-- **sdk:** add backend-controlled replay settings support ([#290](https://github.com/apexbridge-tech/bugspotter/issues/290)) ([0ea7c3b](https://github.com/apexbridge-tech/bugspotter/commit/0ea7c3b1ab456def3fd37c26bca6cf70da0f3ff9))
-
-## [0.1.3-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.1.2-alpha.5...sdk-v0.1.3-alpha.5) (2025-11-13)
+### Added
 
-### Tests
+- Node.js 22 LTS support for long-term stability
+- pnpm 9.15.0 integration with improved dependency resolution
+- Cross-browser E2E test suite (Chromium, Firefox, WebKit)
+- Enhanced CI/CD pipeline with better error handling
+- CDN deployment support in release workflow
 
-- **e2e:** migrate E2E tests from local storage to MinIO ([#229](https://github.com/apexbridge-tech/bugspotter/issues/229)) ([df5247d](https://github.com/apexbridge-tech/bugspotter/commit/df5247dee3a58d49dafe0c60f7f0bf6962c3cfb3))
+### Changed
 
-## [0.1.2-alpha.6](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.1.2-alpha.5...sdk-v0.1.2-alpha.6) (2025-11-13)
+- Updated Firefox large DOM test timeout from 35s to 45s for better compatibility
+- Improved ESLint configuration for test environments
+- Better handling of runtime-injected globals in type checking
 
-### Bug Fixes
+### Fixed
 
-- **sdk:** remove Content-Type header from presigned URL uploads to fix 403 errors - Presigned URLs from S3/B2 are signed with specific headers, and adding additional headers causes signature mismatch and 403 Forbidden errors. This critical fix removes the Content-Type header from both fetch() and XMLHttpRequest uploads to storage.
+- Resolved pnpm version conflict between CI config and package.json
+- Fixed E2E test timeouts for slower browser environments
+- Corrected TypeScript type definitions for test mocks
 
-## [0.1.2-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.1.1-alpha.5...sdk-v0.1.2-alpha.5) (2025-11-12)
+## [0.3.0] - 2025-12-20
 
-### Bug Fixes
+### Added
 
-- **ci:** update SDK publish workflow to support prerelease tags ([#221](https://github.com/apexbridge-tech/bugspotter/issues/221)) ([dc4d7f2](https://github.com/apexbridge-tech/bugspotter/commit/dc4d7f2ef519afcf232704f05295729c6402008c))
+- **Duplicate Prevention System**: Automatic detection and prevention of duplicate bug reports
+- **Backend-Controlled Replay Settings**: Dynamic replay configuration from server
+- **Upload Progress Feedback**: Real-time progress indication for file uploads
+- **Screenshot Proxy Endpoint**: Server-side screenshot proxy support
+- **SDK Internal Log Filtering**: Automatic exclusion of SDK's own logs from reports
 
-## [0.1.1-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.1.0-alpha.5...sdk-v0.1.1-alpha.5) (2025-11-12)
+### Changed
 
-### Features
+- BugSpotter.init() is now async (returns Promise<BugSpotter>)
+- Improved transport layer architecture
+- Enhanced offline queue management
 
-- add exponential backoff retry and offline queue support ([c3c2106](https://github.com/apexbridge-tech/bugspotter/commit/c3c21063b777da37011449b89431a63f987ea777))
-- add FloatingButton widget and fix UMD exports ([b7e170e](https://github.com/apexbridge-tech/bugspotter/commit/b7e170eea47c7883722e59038a0d16b911c59588))
-- add FloatingButton widget with refactored architecture ([87a3d0e](https://github.com/apexbridge-tech/bugspotter/commit/87a3d0e69cea86db01e2847323440f296f045b16))
-- add gzip compression reducing payloads by 70-90% ([489e182](https://github.com/apexbridge-tech/bugspotter/commit/489e182ea072e3ffc43b58700b60288f6a255c22))
-- add gzip compression reducing payloads by 70-90% ([c545acf](https://github.com/apexbridge-tech/bugspotter/commit/c545acf6fe9a973c74a54f63a560b4fd96465e83))
-- add screenshot capture with html-to-image ([fae3eb7](https://github.com/apexbridge-tech/bugspotter/commit/fae3eb70fbf52d5b7c217f4d6d001735b661159d))
-- add session replay with rrweb ([175bd74](https://github.com/apexbridge-tech/bugspotter/commit/175bd74765d7f49b4be681c02eae0d7bbe8b1bc4))
-- add type safety system with shared types, Zod validation, and contract tests ([a3e436a](https://github.com/apexbridge-tech/bugspotter/commit/a3e436a931abda2cf30c85b32e5af2e011b7b3d9))
-- complete BugSpotter v0.1.0 with full documentation ([651153b](https://github.com/apexbridge-tech/bugspotter/commit/651153b2d4c86b9653df6164539991ea92c41942))
-- complete core SDK with all capture modules ([54fe97a](https://github.com/apexbridge-tech/bugspotter/commit/54fe97af32b2ee1aa09f5657b28b89e40454cb0a))
-- fixed bug in NetworkCapture + eslint + prettier ([75e2d92](https://github.com/apexbridge-tech/bugspotter/commit/75e2d9290d82ea3f9b377e3b189ce933f7e3e336))
-- initial project structure ([7109dc2](https://github.com/apexbridge-tech/bugspotter/commit/7109dc2e284ea8692081965e4b5a9cce4dc1b1e0))
-- **sdk:** bump to 0.1.0-alpha.5 with improved release workflow ([#219](https://github.com/apexbridge-tech/bugspotter/issues/219)) ([a191b7b](https://github.com/apexbridge-tech/bugspotter/commit/a191b7b998863f00df4bd24f529057e4c4160a73))
-- vitest configured + unit tests for capture ([381d11e](https://github.com/apexbridge-tech/bugspotter/commit/381d11e8ea45376c56ded0d62c2c37a726002acf))
+## [0.2.0] - 2025-11-21
 
-### Bug Fixes
+### Added
 
-- increase browser test timeout and add GitHub release permissions ([#142](https://github.com/apexbridge-tech/bugspotter/issues/142)) ([301600e](https://github.com/apexbridge-tech/bugspotter/commit/301600e5fa6c01e0a6ef0e3281a0c27206cc00e2))
-- remove await from background queue processing ([174889d](https://github.com/apexbridge-tech/bugspotter/commit/174889d9df5541d0494b736d9b8c44bbcbdfbb7e))
-- **sdk:** remove unused @bugspotter/types workspace dependency ([#146](https://github.com/apexbridge-tech/bugspotter/issues/146)) ([7fed00b](https://github.com/apexbridge-tech/bugspotter/commit/7fed00bafab22f1854b78f861a90069b96a665c1))
+- **Session Replay**: Recording with rrweb (configurable buffer duration up to 30s)
+- **Mouse Event Sampling**: Configurable intervals for mouse tracking
+- **Comprehensive E2E Tests**: Full test suite with Playwright (Chromium, Firefox, WebKit)
+- **Shadow DOM Support**: Complete replay capture for Shadow DOM content
+- **Type Safety Enhancements**: Improved Zod validation and type definitions
 
-### Code Refactoring
+### Changed
 
-- Addressed comments on PR; ([fcb4888](https://github.com/apexbridge-tech/bugspotter/commit/fcb488813cd36147f6292c36f4540b23b7759e20))
-- improve capture classes with options, types, and performance ([616bd35](https://github.com/apexbridge-tech/bugspotter/commit/616bd3502c7620f65494ae813ea39e87781b5a2f))
-- improve transport and offline queue architecture ([01a27f3](https://github.com/apexbridge-tech/bugspotter/commit/01a27f3cc24d1211c65e4f0992fc969f40294e70))
-- optimize demo & documentation structure ([22c2171](https://github.com/apexbridge-tech/bugspotter/commit/22c21712229f19b1280d1406c2fac60655d41c4a))
-- Phase 2 - Extract shared capture architecture ([48d007c](https://github.com/apexbridge-tech/bugspotter/commit/48d007cecfc4651ded10a8c7fd4651fcec499fbd))
-- Phase 2 - Extract shared capture architecture ([ea88dda](https://github.com/apexbridge-tech/bugspotter/commit/ea88dda3cdbb07d72f96d707a3ebb97edf93379c))
-- Phase 2 - Extract shared capture architecture ([72f2425](https://github.com/apexbridge-tech/bugspotter/commit/72f242575c46c3c813bf15234ca95d5624b7d7d4))
-- remove deprecated code and unused variables ([392bbb9](https://github.com/apexbridge-tech/bugspotter/commit/392bbb9c91e3d57a49b9650782b778aea9607d50))
+- Refactored capture classes with better options and performance
+- Improved transport and offline queue architecture
+- Enhanced error handling in retry logic
 
-### Tests
+### Fixed
 
-- Add comprehensive edge case tests for DOM collector ([24b56b3](https://github.com/apexbridge-tech/bugspotter/commit/24b56b3317edd6df656f551c7d22db3cc03df7ac))
+- Content-Type header removal from presigned URL uploads (fixed 403 errors)
+- rrweb CDN loading for reliable replay verification
+- Release workflow prerelease tag support
 
 ## [0.1.0] - 2025-11-01
 
 ### Added
 
-- Initial public release of BugSpotter SDK
-- Screenshot capture with CSP-safe implementation using html-to-image
-- Session replay recording with rrweb (configurable buffer duration)
-- Console log capture (all levels with stack traces)
-- Network request capture (fetch/XHR with timing)
-- Browser metadata capture (browser, OS, viewport detection)
-- Automatic PII detection and sanitization
+#### Core Capture Features
+- **Screenshot Capture**: Full-page screenshots with CSP-safe html-to-image library
+- **Console Logging**: Capture all console messages with stack traces
+- **Network Tracking**: Monitor all HTTP requests (fetch/XHR) with timing
+- **Browser Metadata**: Automatic detection of browser, OS, viewport
+- **DOM Capture**: Complete DOM structure preservation
+
+#### Data Protection & Privacy
+- **PII Sanitization**: Automatic detection and redaction of sensitive data
   - Built-in patterns: email, phone, credit card, SSN, IIN, IP address
-  - Custom pattern support
-  - Configurable exclusion selectors
-- Direct file uploads using presigned URLs (97% memory reduction)
-- Compression utilities for replay data (gzip)
-- Floating widget button with customizable position and styling
-- Bug report modal with form validation
-- Authentication support (API key, Bearer token, Custom headers)
-- Retry logic for failed requests
-- Offline queue for network resilience
-- TypeScript support with full type definitions
-- Multiple module formats: ESM, CommonJS, UMD
-- Framework integration examples for React, Vue, Angular, Next.js, Nuxt, Svelte
-
-### Features
-
-- **Bundle size**: ~99 KB minified (with session replay)
-- **Performance**: Screenshot capture ~500ms, PII sanitization <10ms
-- **Browser support**: Chrome 55+, Firefox 55+, Safari 11+, Edge 79+ (ES2017+)
-- **Memory efficient**: <15 MB for 30s replay buffer
-- **CSP compliant**: No eval, no inline scripts
-
-### Documentation
-
-- Complete API reference
-- Framework integration guide (React, Vue, Angular, Next.js, Nuxt, Svelte)
-- Session replay configuration guide
-- PII sanitization guide
-- Direct upload guide with examples
-
-### Testing
-
-- 345 tests (unit + E2E + Playwright)
-- Full test coverage for core functionality
-
-## [Unreleased]
-
-### Planned Features
-
-- Real-time error tracking
-- Performance monitoring
-- User session tracking
-- Custom event tracking
-- Source map support
-- Analytics dashboard integration
-- Webhooks support
-- Additional integrations (Slack, Discord, Email)
-
----
-
-[0.1.0]: https://github.com/apexbridge-tech/bugspotter/releases/tag/sdk-v0.1.0
+  - Custom regex pattern support
+  - Per-element CSS selector-based exclusion
+- **Content Security Policy (CSP) Compliant**: No eval, no inline scripts
+
+#### Reliability & Performance
+- **Compression**: gzip compression reduces payloads by 70-90%
+- **Direct Upload**: Presigned URL uploads with 97% memory reduction vs base64
+- **Offline Queue**: Store and sync bug reports when network unavailable
+- **Exponential Backoff**: Intelligent retry strategy with configurable delays
+- **Circular Buffering**: Efficient memory usage for long-running sessions
+
+#### User Interface
+- **Floating Widget Button**: Customizable position (corner/edge), styling, and icon
+- **Bug Report Modal**: User-friendly form with validation for manual submission
+- **Responsive Design**: Optimized for both desktop and mobile viewports
+
+#### Authentication & Integration
+- **Multiple Auth Types**: API Key, Bearer token, custom headers
+- **Framework Agnostic**: Works with vanilla JavaScript and all major frameworks
+
+#### Module Formats & TypeScript
+- **ESM, CommonJS, UMD**: Support for all modern module systems
+- **TypeScript Support**: Full type definitions with proper generic types
+- **Source Maps**: Included for debugging and production support
+
+#### Documentation
+- Complete API reference with examples
+- Framework integration guides (React, Vue, Angular, Next.js, Nuxt, Svelte)
+- Session replay configuration and best practices
+- PII sanitization customization guide
+- Direct upload implementation guide

package/CONTRIBUTING.md

@@ -0,0 +1,200 @@
+# Contributing to BugSpotter SDK
+
+Thank you for considering contributing to the BugSpotter SDK! This document outlines the process for contributing to this project.
+
+## Development Setup
+
+### Prerequisites
+- Node.js 18+ (recommended: 18.x or 20.x)
+- pnpm 8+
+- Git
+
+### Getting Started
+
+1. **Fork and Clone**
+   ```bash
+   git clone https://github.com/your-username/bugspotter-sdk.git
+   cd bugspotter-sdk
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   pnpm install
+   ```
+
+3. **Build the Project**
+   ```bash
+   pnpm build
+   ```
+
+4. **Run Tests**
+   ```bash
+   # Unit tests
+   pnpm test
+   
+   # E2E tests (requires browsers)
+   pnpm test:e2e
+   
+   # Watch mode for development
+   pnpm test:watch
+   ```
+
+## Project Structure
+
+```
+bugspotter-sdk/
+├── packages/core/          # Main SDK package
+│   ├── src/               # Source code
+│   ├── tests/             # Unit tests
+│   ├── docs/              # SDK documentation
+│   └── scripts/           # Build scripts
+├── examples/              # Integration examples
+│   ├── react/             # React example
+│   └── vanilla/           # Vanilla JS example
+└── .github/               # GitHub workflows and templates
+```
+
+## Development Workflow
+
+1. **Create a Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make Changes**
+   - Write code in `packages/core/src/`
+   - Add tests in `packages/core/tests/`
+   - Update documentation as needed
+
+3. **Test Your Changes**
+   ```bash
+   pnpm test           # Unit tests
+   pnpm test:e2e       # E2E tests
+   pnpm lint           # Code linting
+   pnpm format:check   # Code formatting
+   ```
+
+4. **Commit Changes**
+   ```bash
+   git add .
+   git commit -m "feat: add your feature"
+   ```
+
+5. **Push and Create PR**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Code Style and Standards
+
+### TypeScript Guidelines
+- Use strict TypeScript settings
+- Provide proper type annotations
+- Avoid `any` types when possible
+- Use interfaces for object shapes
+
+### Code Formatting
+- Use Prettier for formatting (automatic via `pnpm format`)
+- Use ESLint for code quality (check via `pnpm lint`)
+- Follow existing naming conventions
+
+### Testing
+- Write unit tests for all new functionality
+- Maintain test coverage above 80%
+- Add E2E tests for user-facing features
+- Use descriptive test names and organize tests logically
+
+### Commit Messages
+Follow [Conventional Commits](https://conventionalcommits.org/):
+
+- `feat: add new feature`
+- `fix: bug fix`
+- `docs: update documentation`
+- `style: code formatting`
+- `refactor: code refactoring`
+- `test: add or update tests`
+- `chore: maintenance tasks`
+
+## Adding New Features
+
+### Core SDK Features
+1. Create feature in `packages/core/src/`
+2. Add comprehensive tests
+3. Update TypeScript types
+4. Add documentation
+5. Consider browser compatibility (ES2017+)
+
+### Examples
+1. Create new example in `examples/your-framework/`
+2. Include `package.json` with dependencies
+3. Add build configuration (Vite recommended)
+4. Include README with setup instructions
+
+## Testing
+
+### Unit Tests
+- Located in `packages/core/tests/`
+- Use Vitest testing framework
+- Mock external dependencies
+- Test edge cases and error conditions
+
+### E2E Tests
+- Use Playwright for browser testing
+- Test real browser interactions
+- Verify SDK integration works end-to-end
+
+### Test Commands
+```bash
+pnpm test                    # Run unit tests
+pnpm test:watch             # Watch mode
+pnpm test:coverage          # Coverage report
+pnpm test:e2e               # E2E tests
+pnpm test:e2e --headed      # E2E with browser UI
+```
+
+## Building and Publishing
+
+### Local Development
+```bash
+pnpm dev     # Watch mode for development
+pnpm build   # Production build
+```
+
+### Release Process
+1. Update version in `packages/core/package.json`
+2. Update `CHANGELOG.md` with changes
+3. Create git tag: `git tag v0.3.1`
+4. Push tag: `git push origin v0.3.1`
+5. GitHub Actions will automatically publish to npm
+
+## Pull Request Process
+
+1. Fill out the PR template completely
+2. Ensure all CI checks pass:
+   - ✅ Tests pass
+   - ✅ Linting passes
+   - ✅ Build succeeds
+   - ✅ Type checking passes
+3. Request review from maintainers
+4. Address feedback and update PR
+5. Maintainer will merge after approval
+
+## Code Review Criteria
+
+- **Functionality**: Does the code work as intended?
+- **Tests**: Are there adequate tests with good coverage?
+- **Performance**: Does the change impact bundle size or performance?
+- **Compatibility**: Works across supported browsers and Node versions?
+- **Documentation**: Is the change properly documented?
+- **Security**: No security vulnerabilities introduced?
+
+## Getting Help
+
+- **Questions**: Open a [Discussion](https://github.com/apexbridge-tech/bugspotter-sdk/discussions)
+- **Bugs**: Open an [Issue](https://github.com/apexbridge-tech/bugspotter-sdk/issues) with the bug template
+- **Features**: Open an [Issue](https://github.com/apexbridge-tech/bugspotter-sdk/issues) with the feature template
+- **Security**: Email security@apexbridge.tech
+
+## License
+
+By contributing to BugSpotter SDK, you agree that your contributions will be licensed under the MIT License.

package/README.md

@@ -23,7 +23,7 @@ pnpm add @bugspotter/sdk
 
 ```html
 <!-- BugSpotter CDN (versioned - recommended for production) -->
-<script src="https://cdn.bugspotter.io/sdk/bugspotter-0.1.0.min.js"></script>
+<script src="https://cdn.bugspotter.io/sdk/bugspotter-1.0.0.min.js"></script>
 
 <!-- Latest version (for development only) -->
 <script src="https://cdn.bugspotter.io/sdk/bugspotter-latest.min.js"></script>
@@ -89,15 +89,17 @@ const bugSpotter = await BugSpotter.init({
 <script src="https://cdn.bugspotter.io/sdk/bugspotter-latest.min.js"></script>
 <script>
   // Initialize with auto-widget
-  const bugSpotter = BugSpotter.init({
-    endpoint: 'https://api.bugspotter.com/api/v1/reports',
-    auth: {
-      type: 'api-key',
-      apiKey: 'bgs_your_api_key',
-      projectId: 'your-project-uuid',
-    },
-    showWidget: true,
-  });
+  (async () => {
+    const bugSpotter = await BugSpotter.init({
+      endpoint: 'https://api.bugspotter.com/api/v1/reports',
+      auth: {
+        type: 'api-key',
+        apiKey: 'bgs_your_api_key',
+        projectId: 'your-project-uuid',
+      },
+      showWidget: true,
+    });
+  })();
 </script>
 ```
 
@@ -109,7 +111,7 @@ The SDK automatically uses an **optimized presigned URL upload flow** (40% fewer
 import BugSpotter from '@bugspotter/sdk';
 
 // 1. Initialize SDK with required auth
-const bugSpotter = BugSpotter.init({
+const bugSpotter = await BugSpotter.init({
   endpoint: 'https://api.bugspotter.com/api/v1/reports',
   auth: {
     type: 'api-key',
@@ -139,7 +141,7 @@ const bugSpotter = BugSpotter.init({
 
 ```javascript
 // Initialize without widget
-const bugSpotter = BugSpotter.init({
+const bugSpotter = await BugSpotter.init({
   endpoint: 'https://api.bugspotter.com/api/v1/reports',
   auth: {
     type: 'api-key',
@@ -174,7 +176,7 @@ await bugSpotter.submit({
 
 ```javascript
 // Widget appears automatically with showWidget: true
-const bugSpotter = BugSpotter.init({
+const bugSpotter = await BugSpotter.init({
   endpoint: 'https://api.bugspotter.com/api/v1/reports',
   auth: {
     type: 'api-key',
@@ -257,7 +259,7 @@ Automatic detection and masking of sensitive data before submission.
 **Built-in patterns:** Email, phone, credit card, SSN, Kazakhstan IIN, IP address
 
 ```javascript
-BugSpotter.init({
+await BugSpotter.init({
   sanitize: {
     enabled: true, // Default
     patterns: ['email', 'phone', 'creditcard'],
@@ -269,7 +271,7 @@ BugSpotter.init({
 
 **Performance:** <10ms overhead, supports Cyrillic text
 
-## �📋 API Reference
+## 📋 API Reference
 
 ### BugSpotter Class
 
@@ -680,7 +682,7 @@ pnpm test --coverage   # Coverage report
 
 **345 tests** passing (unit + E2E + Playwright)
 
-## �️ Building
+## 🛠️ Building
 
 ```bash
 pnpm run dev    # Development with watch

package/SECURITY.md

@@ -0,0 +1,65 @@
+# Security Policy
+
+## Supported Versions
+
+We provide security updates for the following versions of BugSpotter SDK:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take security seriously. If you discover a security vulnerability in the BugSpotter SDK, please report it to us privately.
+
+### How to Report
+
+1. **Do not** open a public GitHub issue for security vulnerabilities
+2. Send an email to security@apexbridge.tech with:
+   - A description of the vulnerability
+   - Steps to reproduce the issue
+   - Potential impact assessment
+   - Any suggested fixes (optional)
+
+### Response Timeline
+
+- **Acknowledgment**: We'll acknowledge your report within 48 hours
+- **Assessment**: We'll provide an initial assessment within 1 week
+- **Fix Timeline**: Critical vulnerabilities will be patched within 2 weeks
+- **Disclosure**: We'll coordinate responsible disclosure with you
+
+### Security Best Practices
+
+When using the BugSpotter SDK:
+
+1. **API Key Security**:
+   - Never expose API keys in client-side code
+   - Use environment variables for configuration
+   - Rotate API keys regularly
+
+2. **Data Privacy**:
+   - Configure PII detection appropriately
+   - Review captured data for sensitive information
+   - Implement proper data retention policies
+
+3. **Content Security Policy**:
+   - Include appropriate CSP headers
+   - Whitelist necessary domains for the SDK
+
+4. **Dependencies**:
+   - Keep the SDK updated to the latest version
+   - Monitor security advisories for dependencies
+
+## Security Features
+
+The BugSpotter SDK includes several security features:
+
+- **PII Detection**: Automatic detection and sanitization of personally identifiable information
+- **Content Sanitization**: XSS protection in captured content
+- **Secure Uploads**: Encrypted transmission of screenshots and session data
+- **Input Validation**: Strict validation of all user inputs
+
+## Bug Bounty
+
+We currently do not have a formal bug bounty program, but we appreciate responsible disclosure and will acknowledge security researchers who help improve our security.