Skip to content

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

3 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Eskiz SMS - Bun SDK

Zero-dependency, namespaced architecture, fully typed SDK for Eskiz.uz SMS API

CI Test Runtimes Bun TypeScript Zero Dependencies

✨ Features

  • πŸš€ Zero Dependencies - Native Bun only
  • πŸ“¦ Namespaced API - Clean, organized structure
  • πŸ’ͺ Fully Typed - 100% TypeScript with strict mode
  • ⚑ Native Fetch - Built-in fetch API
  • 🎯 DRY Principle - Zero code duplication
  • πŸ”’ Type Safe - Strong typing everywhere
  • πŸ—οΈ Clean Architecture - Separated services
  • πŸ”” Webhook Support - Built-in callback server
  • πŸ“¦ ESM Support - Modern module system

πŸ“‹ Requirements

  • Bun >= 1.3.9

πŸ”§ Compatibility

βœ… ESM (ES Modules) - import syntax
βœ… TypeScript - Full type definitions
βœ… Bun 1.3.9+ - Optimized runtime
βœ… Modern Frameworks - Vite, Hono, Elysia, etc.

Works with:

  • Hono
  • Elysia
  • Bun native HTTP server
  • Any modern Bun/TypeScript project

πŸ“₯ Installation

bun add @joyida/eskiz

πŸš€ Quick Start

import { EskizSMS } from '@joyida/eskiz';

const client = new EskizSMS({
  email: 'your@email.uz',
  password: 'your_password',
});

// Namespaced API - clean and organized!
await client.sms.send({
  mobile_phone: '998901234567',
  message: 'Hello from Eskiz!',
});

πŸ“š API Reference

πŸ” Authentication (client.auth)

// Login (automatic on first API call)
await client.auth.login();

// Get current user
const user = await client.auth.getUser();
console.log(user.name, user.balance);

// Refresh token
await client.auth.refresh();

πŸ“€ SMS Operations (client.sms)

// Send single SMS
await client.sms.send({
  mobile_phone: '998901234567',
  message: 'Test message',
  from: '4546',
  callback_url: 'https://your-domain.com/callback', // optional
});

// Send batch SMS
await client.sms.sendBatch({
  messages: [
    { to: 998901234567, text: 'Message 1' },
    { to: 998901234568, text: 'Message 2' },
  ],
  from: '4546',
  dispatch_id: 12345,
});

// Send international SMS
await client.sms.sendGlobal({
  mobile_phone: '12025550123',
  message: 'Hello!',
  country_code: 'US',
});

// Normalize SMS (check special characters)
const normalized = await client.sms.normalize('Test €100');
console.log(normalized.message);

// Check SMS (price, parts, etc.)
const check = await client.sms.check('Message');
console.log(`Parts: ${check.parts_count}, Price: ${check.info[0].price}`);

πŸ“¨ Messages (client.messages)

// Get message status (by ID or UUID)
const status = await client.messages.getStatus('sms-id');
console.log(status.status); // DELIVERED, REJECTED, etc.

// List messages
const messages = await client.messages.list({
  start_date: '2026-01-01 00:00',
  end_date: '2026-01-31 23:59',
  page_size: 50,
});

// List by dispatch
const dispatchMsgs = await client.messages.listByDispatch({
  dispatch_id: 12345,
});

// Get dispatch status
const dispatchStatus = await client.messages.getDispatchStatus({
  dispatch_id: 12345,
});

// Get system logs
const logs = await client.messages.getLogs('sms-id');

πŸ‘€ User (client.user)

// Get balance
const balance = await client.user.getBalance();
console.log(`Balance: ${balance} UZS`);

// Get sender names
const nicknames = await client.user.getNicknames();
console.log(nicknames);

// Get templates
const templates = await client.user.getTemplates();

// Create template
await client.user.createTemplate('Your template text');

πŸ“Š Reports (client.reports)

// Monthly totals
const monthly = await client.reports.getMonthly(2026);

// Totals by SMSC (operators)
const bySMSC = await client.reports.getBySMSC();

// Totals by date range
const byRange = await client.reports.getByRange({
  start_date: '2026-01-01 00:00',
  to_date: '2026-01-31 23:59',
});

// Totals by dispatch
const byDispatch = await client.reports.getByDispatch({
  dispatch_id: 12345,
});

// Year totals
const yearTotals = await client.reports.getYearTotals({
  year: 2026,
});

// Export messages
await client.reports.export({
  year: 2026,
  month: 1,
  status: 'all',
});

πŸ”‘ Token Management

// Set token (for persistence)
client.setToken('saved_token');

// Get current token
const token = client.getToken();

// Check if expired
const expired = client.isTokenExpired();

// Clear token
client.clearToken();

πŸ”” Webhook / Callbacks

import { createWebhookServer } from '@joyida/eskiz';

const server = createWebhookServer({
  port: 3000,
  path: '/sms-callback',
  onCallback: async (data) => {
    console.log(`SMS ${data.message_id}: ${data.status}`);
    
    // Process callback
    if (data.status === 'DELIVRD') {
      await updateDatabase(data);
    }
  },
});

server.start();

// Send SMS with callback
await client.sms.send({
  mobile_phone: '998901234567',
  message: 'Test',
  callback_url: 'https://your-domain.com/sms-callback',
});

🎯 Complete Example

import { EskizSMS } from '@joyida/eskiz';

const client = new EskizSMS({
  email: process.env.ESKIZ_EMAIL!,
  password: process.env.ESKIZ_PASSWORD!,
});

// Check balance
const balance = await client.user.getBalance();
if (balance < 1000) {
  console.log('Low balance!');
  return;
}

// Check SMS
const check = await client.sms.check('Test message');
if (!check.can_send) {
  console.log('Cannot send SMS');
  return;
}

// Send SMS
const sms = await client.sms.send({
  mobile_phone: '998901234567',
  message: 'Test message',
  from: '4546',
});

console.log(`Sent: ${sms.id}`);

// Wait and check status
await new Promise(r => setTimeout(r, 5000));

const status = await client.messages.getStatus(sms.id);
console.log(`Status: ${status.status}`);

// Get monthly report
const monthly = await client.reports.getMonthly(2026);
console.log('Monthly stats:', monthly);

πŸ—οΈ Architecture

client.auth.*       β†’ Authentication
client.sms.*        β†’ SMS operations
client.messages.*   β†’ Message queries
client.user.*       β†’ User operations
client.reports.*    β†’ Analytics & reports

Benefits:

  • βœ… Clear separation of concerns
  • βœ… Easy to discover methods (autocomplete)
  • βœ… Logical grouping
  • βœ… No code duplication
  • βœ… Easy to extend

πŸ”’ Environment Variables

# .env
ESKIZ_EMAIL=your@email.uz
ESKIZ_PASSWORD=your_password
// Bun (built-in)
const client = new EskizSMS({
  email: Bun.env.ESKIZ_EMAIL!,
  password: Bun.env.ESKIZ_PASSWORD!,
});

πŸ“¦ Bundle Size

  • ~15KB minified (ESM)
  • ~5KB gzipped
  • Zero dependencies!

πŸ§ͺ Testing

bun test

πŸ“„ License

MIT

🀝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

πŸ“ Changelog

See CHANGELOG.md for release history.

πŸ”— Links

πŸ“§ Support

⚠️ Important Notes

  • This package requires Bun 1.3.9+ for native fetch API support
  • Keep your Eskiz credentials secure (use environment variables)
  • Test in development before production use
  • Check your SMS balance before sending bulk messages

Made with ❀️ for Uzbekistan developers

Supports Bun 1.3.9+, ESM

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages