g1-ts-common-packages/README.md

# G1 TypeScript Common Packages

This monorepo contains common TypeScript packages used across Generation One projects. The repository is public, making it easier to share and collaborate on common utilities.

## Repository Structure

```
g1-ts-common-packages/
├── packages/                 # All packages are stored here
│   ├── sse-client/           # Server-Sent Events client package
│   └── [future-packages]/    # Additional packages will be added here
├── scripts/                  # Utility scripts for the repository
├── docs/                     # Documentation
└── .github/workflows/        # CI/CD workflows
```

## Available Packages

### SSE Client (`@g1/sse-client`)

A custom Server-Sent Events (SSE) client that supports headers and bypasses certificate issues.

- Supports custom headers for SSE connections
- Handles reconnection with exponential backoff
- Works in both browser and Node.js environments
- Provides connection management utilities

## Getting Started

### Prerequisites

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

### Installation

Clone the repository:

```bash
# No authentication required for cloning the public repository
git clone https://git.generation.one/GenerationOne/g1-ts-common-packages.git
cd g1-ts-common-packages
```

Install dependencies:

```bash
pnpm install
```

Build all packages:

```bash
pnpm build
```

## Using the Packages

### In Another Project

Add the package to your project:

```bash
# If you're a Generation One team member using the private Gitea registry:
# Configure the Gitea registry
echo "@g1:registry=https://git.generation.one/api/packages/GenerationOne/npm/" > .npmrc
echo "//git.generation.one/api/packages/GenerationOne/npm/:_authToken=${GITEA_TOKEN}" >> .npmrc

# Install the package
pnpm add @g1/sse-client

# Alternatively, you can install directly from the public repository:
pnpm add git+https://git.generation.one/GenerationOne/g1-ts-common-packages.git

# Or clone the repository and link it locally:
git clone https://git.generation.one/GenerationOne/g1-ts-common-packages.git
cd g1-ts-common-packages
pnpm install
pnpm build
cd packages/sse-client
pnpm link .

# Another option is to create a tarball and install it directly:
git clone https://git.generation.one/GenerationOne/g1-ts-common-packages.git
cd g1-ts-common-packages/packages/sse-client
pnpm install
pnpm build
pnpm pack  # Creates a tarball like g1-sse-client-0.2.0.tgz
# Then in your project:
pnpm add /path/to/g1-sse-client-0.2.0.tgz
```

### Example Usage

```typescript
import { SSEClient } from '@g1/sse-client';

// Create a new SSE client
const client = new SSEClient('https://api.example.com/events', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

// Connect to the SSE endpoint
client.connect();

// Add event listeners
client.on('message', (event) => {
  console.log('Received message:', event.data);
});

// Close the connection when done
client.close();
```

## Development

### Adding a New Package

1. Create a new directory in the `packages` folder
2. Initialize the package with `pnpm init`
3. Set the package name with the `@g1` scope (e.g., `@g1/your-package-name`)
4. Set the initial version to `0.2.0` (our standard starting version)
5. Add your code and build configuration

### 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

### Prerequisites

- Gitea access token with `packages:write` permission
- Write access to the Generation One Gitea repository

> **Note:** While the repository is public and anyone can clone it, publishing packages to the Gitea registry requires proper authentication and authorization.

### Publishing a Package

Use the provided script:

```bash
# Set your Gitea token
export GITEA_TOKEN="your-token-here"
# Or create a .gitea-token file in the root directory

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

# Publish with a specific version
./scripts/publish-package.sh packages/sse-client version:0.3.0

# Publish without changing the version
./scripts/publish-package.sh packages/sse-client none
```

For more detailed publishing instructions, see [docs/DEPLOY_KEYS.md](docs/DEPLOY_KEYS.md).

## CI/CD

This repository includes GitHub Actions workflows for automated testing and publishing:

- **Publish Package**: Publishes a package to the Gitea registry

To use the workflows, you need to set up the following secrets in your GitHub repository:
- `GITEA_TOKEN`: Your Gitea access token
- `GITEA_DEPLOY_KEY`: SSH deploy key for the repository

## Contributing

Since this repository is public, contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please make sure your code follows the existing style and includes appropriate tests.

## License

MIT