@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

``bash


npm

npm install @symbioticstar/bark-sdk

pnpm

pnpm add @symbioticstar/bark-sdk

yarn

yarn add @symbioticstar/bark-sdk
`

🚀 Quick Start

$3

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

$3

`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

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

$3

`
@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
`

$3

- 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

$3

`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,
});
`

$3

Full options reference available in API 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

$3

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

$3

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

$3

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

$3

- 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

$3

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

$3

- 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

$3

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