npm package: @ircg/sdk
Description: Complete SDK for IRCG services - includes TES, IOS, and USS clients
Author: Isar Ramses
Latest version: 1.23.7

# @ircg/sdk

Complete SDK for all IRCG services. This package includes clients for:
- **TES** (Transactional Email Service)
- **IOS** (Image Optimization Service)
- **USS** (URL Shortener Service)

## Installation

```bash
pnpm add @ircg/sdk
```

This single package includes everything you need to use all IRCG services.

## Usage

### Import all clients

```typescript
import { TESClient, IOSClient, USSClient } from '@ircg/sdk';

const apiKey = 'your-api-key';

// Initialize clients
const tes = new TESClient({ apiKey });
const ios = new IOSClient({ apiKey });
const uss = new USSClient({ apiKey });

// Use them
await tes.sendText('user@example.com', 'from@yourdomain.com', 'Hello', 'Message');
const image = await ios.upload({ image: file });
const url = await uss.create({ url: 'https://example.com' });
```

### Import only what you need

```typescript
// Only email client
import { TESClient } from '@ircg/sdk';

// Only types
import type { SendEmailRequest, OptimizedImageComplete } from '@ircg/sdk';

// Errors
import { IRCGError, IRCGAuthenticationError } from '@ircg/sdk';
```

## What's Included

### Clients
- `TESClient` - Transactional Email Service
- `IOSClient` - Image Optimization Service
- `USSClient` - URL Shortener Service

### Types
All TypeScript types from all services are re-exported.

### Errors
- `IRCGError` - Base error class
- `IRCGAuthenticationError` - Authentication failures
- `IRCGValidationError` - Validation errors
- `IRCGRateLimitError` - Rate limit exceeded
- `IRCGServerError` - Server errors

## Examples

### Send an email

```typescript
import { TESClient } from '@ircg/sdk';

const tes = new TESClient({ apiKey: 'your-key' });

await tes.sendHtml(
  'user@example.com',
  'noreply@yourdomain.com',
  'Welcome!',
  '<h1>Welcome to our service!</h1>'
);
```

### Optimize an image

```typescript
import { IOSClient } from '@ircg/sdk';

const ios = new IOSClient({ apiKey: 'your-key' });

const result = await ios.upload({
  image: file,
  requireSignedURLs: false
}, 'complete');

console.log(result.optimizedImage.currentVariants);
```

### Shorten a URL

```typescript
import { USSClient } from '@ircg/sdk';

const uss = new USSClient({ apiKey: 'your-key' });

const result = await uss.create({
  url: 'https://example.com/very/long/url'
});

console.log(`Short URL: https://ircg.dev/l/${result.shortenedUrl.urlKey}`);
```

### Use all services together

```typescript
import { TESClient, IOSClient, USSClient } from '@ircg/sdk';

const apiKey = 'your-api-key';

const tes = new TESClient({ apiKey });
const ios = new IOSClient({ apiKey });
const uss = new USSClient({ apiKey });

// Upload image
const imageResult = await ios.upload({ image: file });

// Shorten URL
const urlResult = await uss.create({ url: 'https://example.com' });

// Send email with both
await tes.sendHtml(
  'user@example.com',
  'noreply@yourdomain.com',
  'Check this out!',
  `
    <img src="${ios.getImageUrl(imageResult.optimizedImage.imageId, 'thumbnail')}">
    <a href="https://ircg.dev/l/${urlResult.shortenedUrl.urlKey}">Click here</a>
  `
);
```

## Error Handling

```typescript
import { 
  TESClient, 
  IRCGError, 
  IRCGAuthenticationError,
  IRCGValidationError 
} from '@ircg/sdk';

const tes = new TESClient({ apiKey: 'your-key' });

try {
  await tes.sendText('invalid-email', 'from@domain.com', 'Test', 'Message');
} catch (error) {
  if (error instanceof IRCGAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof IRCGValidationError) {
    console.error('Validation error:', error.details);
  } else if (error instanceof IRCGError) {
    console.error('IRCG error:', error.message);
  }
}
```

## Individual Packages

If you only need one service, you can install individual packages:

```bash
pnpm add @ircg/tes  # Only email service
pnpm add @ircg/ios  # Only image optimization
pnpm add @ircg/uss  # Only URL shortener
```

## Documentation

- [TES Documentation](../tes/README.md) - Transactional Email Service
- [IOS Documentation](../ios/README.md) - Image Optimization Service
- [USS Documentation](../uss/README.md) - URL Shortener Service
- [Examples](../../EXAMPLES.md) - Complete examples

## TypeScript

This package is written in TypeScript and includes full type definitions.

```typescript
import type { 
  SendEmailRequest,
  OptimizedImageComplete,
  ShortenedUrlMinimal 
} from '@ircg/sdk';

const emailData: SendEmailRequest = {
  sender: 'from@domain.com',
  recipients: ['to@example.com'],
  subject: 'Hello',
  html: '<p>Message</p>'
};
```

## License

MIT