@symbioticstar/bark-sdk

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

A comprehensive, type-safe TypeScript SDK for the Bark 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

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

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:

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:

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:

// 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/ directory:

• API Reference - Complete API documentation with examples
• TypeScript Guide - Advanced TypeScript features and patterns
• Encryption Guide - Secure notification setup and usage
• Error Handling Guide - 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

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.

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

# 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 with TypeScript, import, performance, and security rules
• Formatting: oxfmt with consistent code style
• Testing: vitest with 100% type coverage
• Git Hooks: 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:

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

# 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 file for details.

🙏 Acknowledgments

• Bark for the excellent push notification service
• TypeScript for type safety
• Axios for HTTP client
• Vitest for testing
• Oxc for linting and formatting

📞 Support

• Documentation: docs/ directory
• Issues: GitHub Issues
• 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 • Report Bug • Request Feature