npm package: @symbioticstar/bark-sdk
Description: TypeScript SDK for Bark API - Send push notifications to iOS devices
Author: SymbioticStar
Latest version: 1.2.0

# @symbioticstar/bark-sdk

> TypeScript SDK for Bark API - Send push notifications to iOS devices

[![npm version](https://img.shields.io/npm/v/@symbioticstar/bark-sdk)](https://www.npmjs.com/package/@symbioticstar/bark-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
[![CI Status](https://github.com/symbioticstar/bark-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/symbioticstar/bark-sdk/actions/workflows/ci.yml)

A comprehensive, type-safe TypeScript SDK for the [Bark](https://bark.day.app) push notification API. Send notifications to iOS devices with full encryption support, batch operations, and enterprise-grade error handling.

## ✨ Features

- **🚀 Full TypeScript Support**: Complete type definitions with IntelliSense
- **🔒 Encryption Ready**: End-to-end encrypted notifications for sensitive content
- **📦 Batch Operations**: Send to multiple devices with a single API call
- **🛡️ Robust Error Handling**: Comprehensive error types with recovery strategies
- **⚡ Modern Tooling**: Built with oxlint, oxfmt, husky, and vitest
- **📚 Extensive Documentation**: Complete API reference and guides
- **🎯 Zero Dependencies**: Lightweight with only axios as runtime dependency
- **🔧 Fully Configurable**: Customizable retries, timeouts, and defaults

## 📦 Installation

```bash
# npm
npm install @symbioticstar/bark-sdk

# pnpm
pnpm add @symbioticstar/bark-sdk

# yarn
yarn add @symbioticstar/bark-sdk
```

## 🚀 Quick Start

### 1. Get Your Device Key

1. Install the [Bark app](https://apps.apple.com/app/id1403753865) on your iOS device
2. Open the app and copy your device key
3. (Optional) Set up encryption in app settings for secure notifications

### 2. Send Your First Notification

```typescript
import { BarkClient } from '@symbioticstar/bark-sdk';

// Create a client with your device key
const client = new BarkClient({
  defaultDeviceKey: 'your-device-key-here',
});

// Send a simple notification
const response = await client.push({
  title: 'Hello from Bark SDK!',
  body: 'This is your first notification 🎉',
  sound: 'bell',
  badge: 1,
});

console.log('Notification sent:', response);
```

### 3. More Examples

**Batch notifications to multiple devices:**

```typescript
const response = await client.batchPush({
  device_keys: ['key1', 'key2', 'key3'],
  title: 'Server Alert',
  body: 'High CPU usage detected',
  level: 'critical',
  sound: 'alarm',
});
```

**Encrypted notifications for sensitive content:**

```typescript
const response = await client.encryptedPush(
  {
    title: '🔐 Secure Message',
    body: 'This content is encrypted',
  },
  {
    publicKey: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----',
  }
);
```

**Update or delete notifications:**

```typescript
// Update an existing notification
await client.updateNotification('notification-id', {
  title: 'Updated Title',
  body: 'New content',
});

// Delete a notification
await client.deleteNotification('notification-id');
```

## 📖 Documentation

Complete documentation is available in the [`docs/`](docs/) directory:

- [**API Reference**](docs/API-REFERENCE.md) - Complete API documentation with examples
- [**TypeScript Guide**](docs/TYPESCRIPT-GUIDE.md) - Advanced TypeScript features and patterns
- [**Encryption Guide**](docs/ENCRYPTION.md) - Secure notification setup and usage
- [**Error Handling Guide**](docs/ERROR-HANDLING.md) - Comprehensive error handling strategies

## 🏗️ Architecture

### Project Structure

```
@symbioticstar/bark-sdk/
├── src/                          # Source code
│   ├── index.ts                  # Main entry point
│   ├── client.ts                 # Bark API client
│   ├── types.ts                  # TypeScript type definitions
│   ├── errors.ts                 # Error handling classes
│   ├── utils.ts                  # Utility functions
│   └── constants.ts              # Constants and defaults
├── tests/                        # Unit tests
├── examples/                     # Usage examples
├── docs/                         # Comprehensive documentation
└── .github/workflows/            # CI/CD workflows
```

### Core Components

- **`BarkClient`**: Main client class with all API methods
- **`BarkPushOptions`**: Type-safe notification options interface
- **`BarkError` hierarchy**: Structured error handling with specific error types
- **Encryption utilities**: RSA-OAEP encryption for secure notifications

## 🔧 Configuration

### Client Configuration

```typescript
const client = new BarkClient({
  // Bark server URL (default: 'https://api.day.app')
  serverUrl: 'https://api.day.app',

  // Request timeout in milliseconds (default: 10000)
  timeout: 15000,

  // Number of retry attempts (default: 3)
  retries: 3,

  // Retry delay in milliseconds (default: 1000)
  retryDelay: 1000,

  // Default device key for all requests
  defaultDeviceKey: 'your-device-key',

  // Default options applied to all pushes
  defaultOptions: {
    sound: 'bell',
    level: 'active',
  },

  // Whether to throw errors on API failure (default: true)
  throwOnError: true,
});
```

### Notification Options

Full options reference available in [API Reference](docs/API-REFERENCE.md#barkpushoptions-reference).

```typescript
const options = {
  // Basic content
  title: 'Notification Title',
  subtitle: 'Subtitle',
  body: 'Main content here',
  markdown: '**Markdown** supported',

  // Device targeting
  device_key: 'single-device-key',
  device_keys: ['multiple', 'device', 'keys'],

  // Behavior
  level: 'critical', // 'critical' | 'active' | 'timeSensitive' | 'passive'
  sound: 'alarm',
  badge: 5,
  volume: 8, // 0-10

  // Appearance
  icon: 'system',
  url: 'https://example.com',

  // Timing
  delivery_time: '2024-12-31T23:59:59Z',

  // And many more options...
};
```

## 🛠️ Development

### Prerequisites

- Node.js 18+
- pnpm (recommended) or npm/yarn

### Setup

```bash
# Clone the repository
git clone https://github.com/symbioticstar/bark-sdk.git
cd bark-sdk

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run linting
pnpm run lint

# Format code
pnpm run format

# Build the project
pnpm run build
```

### Available Scripts

| Script                   | Description              |
| ------------------------ | ------------------------ |
| `pnpm run build`         | Build the project        |
| `pnpm run dev`           | Build in watch mode      |
| `pnpm run test`          | Run unit tests           |
| `pnpm run test:watch`    | Run tests in watch mode  |
| `pnpm run test:coverage` | Run tests with coverage  |
| `pnpm run lint`          | Run linter               |
| `pnpm run lint:fix`      | Fix linting issues       |
| `pnpm run format`        | Format code              |
| `pnpm run format:check`  | Check code formatting    |
| `pnpm run type-check`    | TypeScript type checking |

### Code Quality

- **Linting**: [oxlint](https://oxc.rs/) with TypeScript, import, performance, and security rules
- **Formatting**: [oxfmt](https://oxc.rs/) with consistent code style
- **Testing**: [vitest](https://vitest.dev/) with 100% type coverage
- **Git Hooks**: [husky](https://typicode.github.io/husky/) with pre-commit checks

## 📊 API Coverage

| Bark API Feature    | SDK Support     | Notes                             |
| ------------------- | --------------- | --------------------------------- |
| Single device push  | ✅ Full support | All parameters supported          |
| Batch push          | ✅ Full support | Up to 100 devices per request     |
| Encrypted push      | ✅ Full support | RSA-OAEP with SHA-256             |
| Notification update | ✅ Full support | Update existing notifications     |
| Notification delete | ✅ Full support | Remove notifications              |
| All push parameters | ✅ Full support | 40+ parameters with validation    |
| Error handling      | ✅ Enhanced     | Structured errors with recovery   |
| Retry logic         | ✅ Built-in     | Configurable retries with backoff |
| TypeScript types    | ✅ Complete     | Full IntelliSense support         |

## 🔐 Security

### Encryption

The SDK supports end-to-end encrypted notifications using RSA-OAEP with SHA-256:

```typescript
// Generate key pair
const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

// Send encrypted notification
await client.encryptedPush({ title: 'Secure', body: 'Encrypted content' }, { publicKey });
```

### Security Features

- **No sensitive data in logs**: Device keys and encryption keys are never logged
- **Input validation**: All parameters validated before sending
- **HTTPS enforcement**: All requests use HTTPS
- **Rate limiting**: Built-in handling of API rate limits
- **Error sanitization**: Safe error messages without sensitive data

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details.

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

### Development Workflow

```bash
# 1. Install dependencies
pnpm install

# 2. Run tests to ensure everything works
pnpm test

# 3. Make your changes
# ... edit files ...

# 4. Run tests again
pnpm test

# 5. Check linting and formatting
pnpm run lint
pnpm run format:check

# 6. Build to verify no TypeScript errors
pnpm run build

# 7. Commit with descriptive message
git commit -m "feat: add new feature"
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Bark](https://bark.day.app) for the excellent push notification service
- [TypeScript](https://www.typescriptlang.org/) for type safety
- [Axios](https://axios-http.com/) for HTTP client
- [Vitest](https://vitest.dev/) for testing
- [Oxc](https://oxc.rs/) for linting and formatting

## 📞 Support

- **Documentation**: [docs/](docs/) directory
- **Issues**: [GitHub Issues](https://github.com/symbioticstar/bark-sdk/issues)
- **Examples**: [examples/](examples/) directory

## 🚀 Roadmap

- [ ] WebSocket support for real-time notifications
- [ ] Notification scheduling service
- [ ] Advanced analytics integration
- [ ] Plugin system for custom transports
- [ ] More encryption algorithms (ECC, ChaCha20-Poly1305)

---

Built with ❤️ by [SymbioticStar](https://github.com/symbioticstar) • [Report Bug](https://github.com/symbioticstar/bark-sdk/issues) • [Request Feature](https://github.com/symbioticstar/bark-sdk/issues)