# Technical Context

This document outlines the technologies used, development setup, technical constraints, and dependencies for the G1 TypeScript Common Packages repository.

## Technologies Used

### Core Technologies

| Technology | Purpose | Version |
|------------|---------|---------|
| TypeScript | Static typing for JavaScript | ^5.0.0 |
| Node.js    | JavaScript runtime | 16+ |
| pnpm       | Package manager | Latest |

### Build & Development Tools

| Tool | Purpose |
|------|---------|
| TypeScript Compiler | Compiles TypeScript to JavaScript |
| Jest | Testing framework |
| ESLint | Code linting |
| GitHub Actions | CI/CD workflows |

### Dependencies

#### SSE Client Package

| Dependency | Purpose |
|------------|---------|
| event-source-polyfill | Polyfill for EventSource with custom headers support |

## Development Setup

### Prerequisites

- Node.js 16+
- pnpm (recommended) or npm

### Installation

```bash
# Clone the repository
git clone https://git.generation.one/GenerationOne/g1-ts-common-packages.git
cd g1-ts-common-packages

# Install dependencies
pnpm install

# Build all packages
pnpm build
```

### Repository Structure

```
g1-ts-common-packages/
├── packages/                 # All packages are stored here
│   ├── sse-client/           # Server-Sent Events client package
│   │   ├── src/              # Source code
│   │   ├── dist/             # Compiled output (generated)
│   │   ├── examples/         # Example usage
│   │   ├── __tests__/        # Tests
│   │   ├── package.json      # Package configuration
│   │   └── tsconfig.json     # TypeScript configuration
│   └── [future-packages]/    # Additional packages will be added here
├── scripts/                  # Utility scripts for the repository
│   ├── publish-package.sh    # Script for publishing packages
│   └── setup-deploy-key.sh   # Script for setting up deploy keys
├── docs/                     # Documentation
│   └── DEPLOY_KEYS.md        # Documentation for deploy keys
└── .github/workflows/        # CI/CD workflows
```

### Package Structure (SSE Client)

```
sse-client/
├── src/                      # Source code
│   ├── index.ts              # Main entry point
│   ├── sseClient.ts          # SSE client implementation
│   └── utils/                # Utility functions
│       └── debug.ts          # Debug utilities
├── examples/                 # Example usage
│   ├── angular-order-tracking.component.ts
│   ├── browser-script.html
│   ├── express-sse-proxy.js
│   ├── fastify-sse-proxy.js
│   ├── nextjs-sse-proxy.ts
│   ├── nodejs-sse-client.js
│   ├── order-tracking.ts
│   ├── react-order-tracking.tsx
│   └── vue-order-tracking.vue
├── __tests__/                # Tests
│   └── sseClient.test.ts     # SSE client tests
├── dist/                     # Compiled output (generated)
├── package.json              # Package configuration
├── tsconfig.json             # TypeScript configuration
├── jest.config.js            # Jest configuration
├── LICENSE                   # License file
├── README.md                 # Package documentation
├── PUBLISHING.md             # Publishing instructions
└── SUMMARY.md                # Package summary
```

## Development Workflow

### Building Packages

To build a specific package:

```bash
cd packages/package-name
pnpm build
```

To build all packages:

```bash
pnpm -r build
```

### Testing Packages

To run tests for a specific package:

```bash
cd packages/package-name
pnpm test
```

To test all packages:

```bash
pnpm -r test
```

### Publishing Packages

For team members with write access to the repository:

```bash
# Set your access token
export GITEA_TOKEN="your-token-here"

# Publish with a version bump
./scripts/publish-package.sh packages/sse-client patch
```

Version options:
- `patch` - Increment the patch version (0.2.0 → 0.2.1)
- `minor` - Increment the minor version (0.2.0 → 0.3.0)
- `major` - Increment the major version (0.2.0 → 1.0.0)
- `version:x.y.z` - Set a specific version
- `none` - Keep the current version

## Technical Constraints

### Browser Compatibility

- The SSE client package is designed to work in modern browsers and Node.js environments
- For older browsers, the event-source-polyfill is used to provide EventSource functionality

### Node.js Compatibility

- Packages are designed to work with Node.js 16+
- SSL certificate validation bypass is only available in Node.js environments

### Package Size

- Packages should be kept as small as possible to minimize bundle size
- Dependencies should be carefully chosen to avoid bloating the package

### API Design

- APIs should be designed to be intuitive and consistent
- Breaking changes should be avoided when possible, especially after reaching version 1.0.0
- When breaking changes are necessary, they should be clearly documented

## Tool Usage Patterns

### pnpm Workspace Commands

- `pnpm -r <command>` - Run a command in all packages
- `pnpm -r --filter <package> <command>` - Run a command in a specific package

### Publishing Workflow

1. Make changes to a package
2. Update tests and documentation
3. Run tests to ensure everything works
4. Use the publish script to publish the package with a version bump
5. The script will:
   - Build the package
   - Update the version
   - Publish to the Gitea registry
   - Create a git tag

### CI/CD Workflow

The repository uses GitHub Actions for CI/CD:

1. On push to main or pull request:
   - Build all packages
   - Run tests for all packages
2. On release:
   - Publish packages to the Gitea registry

## Environment Variables

| Variable | Purpose |
|----------|---------|
| GITEA_TOKEN | Access token for publishing packages to the Gitea registry |
| GITEA_DEPLOY_KEY | SSH deploy key for CI/CD workflows |

## Documentation Standards

- Each package should have:
  - A README.md with usage examples
  - JSDoc comments for all public APIs
  - A SUMMARY.md with a brief overview
  - A PUBLISHING.md with publishing instructions (if applicable)