# 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
│   ├── api-generator/        # OpenAPI TypeScript client generator
│   └── [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
[View SSE Client Documentation](packages/sse-client/README.md)

### API Generator (`@g1/api-generator`)

A command-line tool for generating TypeScript API clients from OpenAPI schemas.

- Downloads OpenAPI schema from a specified URL
- Generates TypeScript interfaces and API client code
- Post-processes generated code to fix common issues
- Supports HTTPS with option to skip TLS verification
[View API Generator Documentation](packages/api-generator/README.md)

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

#### Option 1: Install from the Gitea Registry (Recommended)

```bash
# Configure the Gitea registry in your project
echo "@g1:registry=https://git.generation.one/api/packages/GenerationOne/npm/" > .npmrc

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

#### Option 2: Create and Install a Tarball

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

# Build and pack
pnpm install
pnpm build
pnpm pack  # Creates a tarball like g1-sse-client-0.2.0.tgz

# Install the tarball in your project
cd /path/to/your/project
pnpm add /path/to/g1-sse-client-0.2.0.tgz
```

### Example Usage

#### SSE Client

```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();
```

#### API Generator

```bash
# Generate API client from OpenAPI schema
g1-api-generator https://api.example.com/openapi.json ./src/api
```

```typescript
// Use the generated API client
import { ApiClient } from './src/api';

const api = new ApiClient({
  BASE: 'https://api.example.com',
  TOKEN: 'your-token'
});

// Call API methods
const users = await api.users.getUsers();
console.log(users);
```

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

### For Team Members

If you're a team member 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

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

## CI/CD

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

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

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