npm package: @opensourcekd/ng-common-libs
Description: Angular 18 shareable utility library with framework-agnostic core and Angular wrappers for event emitter, authorization, storage, and more
Author: Koustubh Desai
Latest version: 2.2.1

# ng-common-libs

Pure TypeScript library with Auth0 authentication service and framework-agnostic event bus.

## 🎯 Simple Architecture

**One import path. Everything you need. Framework-agnostic.**

All services, utilities, and types are exported from a single package:

```typescript
import { 
  AuthService, 
  EventBus, 
  APP_CONFIG,
  UserInfo
} from '@opensourcekd/ng-common-libs';
```

> 📖 **Complete Guide**: See [docs/CONSUMPTION_GUIDE.md](./docs/CONSUMPTION_GUIDE.md) for detailed usage instructions.

## 🚀 Features

- **AuthService**: Complete Auth0 authentication with token management (Pure TypeScript - no Angular dependency)
- **EventBus**: Framework-agnostic event bus using RxJS
- **Logger**: OpenTelemetry-compliant structured logging with observable log streams
- **CSS Tokens**: Shared design tokens (colors, typography, spacing, shadows, and more) as CSS custom properties
- **Works with any framework**: Angular, React, Vue, Svelte, vanilla JS
- **Module Federation Support**: Singleton pattern works across shell + MFEs
- **Zero Framework Lock-in**: Core services are pure TypeScript classes

## 📦 Installation

```bash
npm install @opensourcekd/ng-common-libs
```

> **Note:** `mitt` and `@auth0/auth0-spa-js` are bundled. No separate installation needed.

## 🔧 Quick Start

### Pure TypeScript Usage (Framework-Agnostic)

```typescript
import { AuthService, EventBus } from '@opensourcekd/ng-common-libs';

// Create instances
const eventBus = new EventBus();
const authConfig = {
  domain: 'your-domain.auth0.com',
  clientId: 'your-client-id',
  redirectUri: window.location.origin,
  logoutUri: window.location.origin,
  scope: 'openid profile email'
};
const authService = new AuthService(authConfig, eventBus);

// Use the service
await authService.login();
const user = authService.getUser();
const token = await authService.getToken();

// Subscribe to events
eventBus.on('auth:login_success').subscribe(data => {
  console.log('User logged in:', data);
});
```

### API URL Access

**No configuration needed** - API URL is automatically available:

```typescript
import { APP_CONFIG } from '@opensourcekd/ng-common-libs';

// API URL is baked into the library during build from GitHub repository variables
const apiUrl = APP_CONFIG.apiUrl;
const endpoint = `${apiUrl}/users`;
```

> ℹ️ **Note**: The API URL is configured in GitHub repository variables (API_URL) and baked into the library during the CI/CD build process. No runtime configuration is needed in consuming applications.

## 📚 Documentation

All documentation is in the `/docs` folder:

- **[CONSUMPTION_GUIDE.md](./docs/CONSUMPTION_GUIDE.md)** - Complete setup guide and API reference
- **[AUTH.md](./docs/AUTH.md)** - Authentication with Auth0 (setup, usage, debugging)
- **[INTEGRATION.md](./docs/INTEGRATION.md)** - Angular, Module Federation, auto-deployments
- **[EVENT_BUS_USAGE.md](./docs/EVENT_BUS_USAGE.md)** - Cross-application event patterns
- **[DEPLOYMENT.md](./docs/DEPLOYMENT.md)** - Publishing and deployment
- **[ARCHITECTURE_ANALYSIS.md](./docs/ARCHITECTURE_ANALYSIS.md)** - Architecture overview
- **[MICROAPP_SETUP_REQUIRED.md](./docs/MICROAPP_SETUP_REQUIRED.md)** - Microapp setup
- **[COPILOT_EFFICIENCY.md](./docs/COPILOT_EFFICIENCY.md)** - ⚡ How to use GitHub Copilot efficiently

## 🎨 CSS Design Tokens

Shared CSS custom properties for consistent styling across all micro-frontends.

### Usage

In your global stylesheet (`styles.css` / `styles.scss`):

```css
@import '@opensourcekd/ng-common-libs/styles/tokens.css';
```

### Available Token Categories

| Category | Example Tokens |
|---|---|
| **Colors** | `--color-primary-500`, `--color-success-600`, `--color-error-500` |
| **Semantic Colors** | `--color-brand`, `--color-text-primary`, `--color-bg-surface` |
| **Typography** | `--font-size-md`, `--font-weight-bold`, `--line-height-normal` |
| **Spacing** | `--space-4` (16px), `--space-8` (32px), `--space-16` (64px) |
| **Border Radius** | `--radius-sm`, `--radius-lg`, `--radius-full` |
| **Shadows** | `--shadow-sm`, `--shadow-md`, `--shadow-xl`, `--shadow-focus` |
| **Z-index** | `--z-index-modal`, `--z-index-toast`, `--z-index-tooltip` |
| **Transitions** | `--transition-fast`, `--transition-normal`, `--duration-fast` |
| **Opacity** | `--opacity-50`, `--opacity-75`, `--opacity-100` |
| **Breakpoints** | `--breakpoint-sm` (640px), `--breakpoint-lg` (1024px) |

### Example

```css
.my-button {
  background-color: var(--color-brand);
  color: var(--color-text-on-brand);
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-md);
  font-size: var(--font-size-sm);
  font-weight: var(--font-weight-semibold);
  box-shadow: var(--shadow-sm);
  transition: var(--transition-normal);
}

.my-button:hover {
  background-color: var(--color-brand-hover);
  box-shadow: var(--shadow-md);
}
```

## 📝 What's Exported

Everything you need from one import:

```typescript
import { 
  // Services
  AuthService,
  EventBus,
  Logger,
  
  // Helper Functions
  configureAuth0,
  createAuthService,
  
  // Configuration
  APP_CONFIG,
  AUTH0_CONFIG,
  STORAGE_CONFIG,
  STORAGE_KEYS,
  
  // Utilities
  getStorageItem,
  setStorageItem,
  removeStorageItem,
  
  // Types & Interfaces
  UserInfo,
  UserData,
  TokenPayload,              // Decoded JWT access token payload
  EventPayload,
  Auth0Config,
  Auth0ConfigOptions,
  StorageConfig,
  StorageKeys,
  AppState,
  AuthorizationParams,
  CallbackResult,
  LogRecord,
  LogAttributes,
  LogSeverity,
  LoggerOptions,
} from '@opensourcekd/ng-common-libs';
```

## 🛠️ Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Run linter
npm run lint

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

## 🧪 Testing

This library maintains high test coverage:
- **99.26%** statement coverage
- **83.45%** branch coverage
- **100%** function coverage

All core utilities and services are thoroughly tested using Jest and Angular testing utilities.

## 📄 License

MIT

## 👤 Author

Koustubh Desai <jobs.koustubh@gmail.com>

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!

## ⭐ Show your support

Give a ⭐️ if this project helped you!