{"_id":"@alikhangholi/iran-sms","name":"@alikhangholi/iran-sms","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@alikhangholi/iran-sms","version":"1.0.2","description":"Unified TypeScript SDK for Iranian SMS panels (KavehNegar, SMS.ir, FarazSMS, Ghasedak, and more)","license":"MIT","author":{"name":"alikhangholi"},"repository":{"type":"git","url":"git+https://github.com/alikhangholi/iran-sms.git"},"keywords":["sms","iran","kavenegar","smsir","farazsms","ghasedak","iranian-sms","n8n","typescript"],"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src tests","lint:fix":"eslint src tests --fix","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" --ignore-unknown","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" --ignore-unknown","typecheck":"tsc --noEmit","prepare":"node -e \"if (process.env.CI) process.exit(0)\" || husky"},"devDependencies":{"@changesets/cli":"^2.27.12","@commitlint/cli":"^19.6.1","@commitlint/config-conventional":"^19.6.0","@types/jest":"^29.5.14","@types/node":"^22.10.7","@typescript-eslint/eslint-plugin":"^8.20.0","@typescript-eslint/parser":"^8.20.0","eslint":"^9.18.0","typescript-eslint":"latest","husky":"^9.1.7","jest":"^29.7.0","prettier":"^3.4.2","ts-jest":"^29.2.5","tsup":"^8.3.5","typescript":"^5.7.3"},"engines":{"node":">=18"},"_id":"@alikhangholi/iran-sms@1.0.2","gitHead":"985a4ddf49156c66ea290300a2820426625a6099","bugs":{"url":"https://github.com/alikhangholi/iran-sms/issues"},"homepage":"https://github.com/alikhangholi/iran-sms#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-JX8PysBdGuYnUN7AGunE1qjqANDwDXW1YUGKrBglbpNlRfZDpjCk0XTba6Am8g7WN5SLQMzGI+ZR2ux9rTNRhA==","shasum":"8e181eb232be6b8d23f650b00823e2b346191e15","tarball":"https://registry.npmjs.org/@alikhangholi/iran-sms/-/iran-sms-1.0.2.tgz","fileCount":8,"unpackedSize":65617,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alikhangholi%2firan-sms@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC/3uXc9lgbJBnQNN/PMcWROU8OPIKVFt4JgA8J0TWZ8wIhAPE1zZsK1WZVGJqz9KFOApzjC989l2gfEE6Kcj5l8APp"}]},"_npmUser":{"name":"alikhangholi","email":"alikhangholi@gmail.com"},"directories":{},"maintainers":[{"name":"alikhangholi","email":"alikhangholi@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/iran-sms_1.0.2_1780753523241_0.9712374072617602"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-06T13:45:23.044Z","1.0.2":"2026-06-06T13:45:23.384Z","modified":"2026-06-06T13:45:23.740Z"},"maintainers":[{"name":"alikhangholi","email":"alikhangholi@gmail.com"}],"description":"Unified TypeScript SDK for Iranian SMS panels (KavehNegar, SMS.ir, FarazSMS, Ghasedak, and more)","homepage":"https://github.com/alikhangholi/iran-sms#readme","keywords":["sms","iran","kavenegar","smsir","farazsms","ghasedak","iranian-sms","n8n","typescript"],"repository":{"type":"git","url":"git+https://github.com/alikhangholi/iran-sms.git"},"author":{"name":"alikhangholi"},"bugs":{"url":"https://github.com/alikhangholi/iran-sms/issues"},"license":"MIT","readme":"# @alikhangholi/iran-sms\n\n> Unified TypeScript SDK for Iranian SMS panels.\n> One API. Any provider.\n\n[![npm version](https://img.shields.io/npm/v/@alikhangholi/iran-sms)](https://www.npmjs.com/package/@alikhangholi/iran-sms)\n[![CI](https://github.com/alikhangholi/iran-sms/actions/workflows/ci.yml/badge.svg)](https://github.com/alikhangholi/iran-sms/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Supported Providers\n\n| Provider | Status | Auth | Phone Format |\n|---|---|---|---|\n| KavehNegar | ✅ v1.0 | API Key | `9121234567` |\n| SMS.ir | ✅ v1.0 | API Key | `9121234567` |\n| FarazSMS | ✅ v1.0 | Username + Password | `+989121234567` |\n| Ghasedak | ✅ v1.0 | API Key | `9121234567` |\n| MeliPayamak | 🔜 v1.x | Username + Password | — |\n| IPPanel | 🔜 v1.x | Username + Password | — |\n| RayganSMS | 🔜 v1.x | Username + Password | — |\n| ParsGreen | 🔜 v1.x | API Key | — |\n| PayamResan | 🔜 v1.x | API Key | — |\n\n## Install\n\n```bash\nnpm install @alikhangholi/iran-sms\n```\n\nRequires Node.js ≥ 18.\n\n## Quick Start\n\n```ts\nimport { IranSms } from '@alikhangholi/iran-sms';\n\nconst sms = new IranSms({\n  provider: {\n    provider: 'kavenegar',\n    apiKey: 'your-api-key',\n    lineNumber: '10004346',\n  },\n});\n\n// Send a single SMS\nconst result = await sms.send({\n  to: '09121234567',\n  message: 'Hello from iran-sms!',\n});\nconsole.log(result.messageId);\n\n// Send bulk SMS\nconst results = await sms.send({\n  to: ['09121234567', '09361234567'],\n  message: 'Broadcast message',\n});\n\n// Send OTP / pattern SMS\nawait sms.sendPattern({\n  to: '09121234567',\n  templateId: 'your-template-name',\n  variables: { code: '4821' },\n});\n\n// Check delivery status\nconst status = await sms.getStatus({ messageId: result.messageId });\nconsole.log(status.status); // 'delivered' | 'pending' | 'failed' | 'unknown'\n\n// Check account credit\nconst credit = await sms.getCredit();\nconsole.log(credit.balance, credit.unit); // e.g. 50000 'rial'\n```\n\n## Safe Mode (never throws)\n\n```ts\nconst sms = new IranSms({\n  provider: {\n    provider: 'smsir',\n    apiKey: 'your-api-key',\n    lineNumber: 300000000000,\n  },\n  safe: true, // all methods return SmsResult<T> instead of throwing\n});\n\nconst result = await sms.send({ to: '09121234567', message: 'Hello' });\n\nif (result.success) {\n  console.log(result.data.messageId);\n} else {\n  console.error(result.error.code);    // 'PROVIDER_ERROR' | 'NETWORK_ERROR' | etc.\n  console.error(result.error.message);\n}\n```\n\n## Error Handling (throw mode)\n\n```ts\nimport { IranSms, IranSmsError } from '@alikhangholi/iran-sms';\n\ntry {\n  await sms.send({ to: '09121234567', message: 'Hello' });\n} catch (e) {\n  if (e instanceof IranSmsError) {\n    console.error(e.code);        // 'INVALID_API_KEY' | 'RATE_LIMITED' | 'NETWORK_ERROR' | ...\n    console.error(e.provider);    // 'kavenegar'\n    console.error(e.statusCode);  // HTTP status if applicable\n    console.error(e.rawResponse); // raw provider response\n  }\n}\n```\n\n## Provider Configuration\n\n### KavehNegar\n\n```ts\n{\n  provider: 'kavenegar',\n  apiKey: string,       // from kavenegar.com account settings\n  lineNumber: string,   // your SMS line number e.g. '10004346'\n}\n```\n\n### SMS.ir\n\n```ts\n{\n  provider: 'smsir',\n  apiKey: string,       // from sms.ir account settings\n  lineNumber: number,   // your line number as a number e.g. 300000000000\n}\n```\n\n### FarazSMS\n\n```ts\n{\n  provider: 'farazsms',\n  username: string,\n  password: string,\n  lineNumber: string,   // e.g. '3000XXXXX'\n}\n```\n\n### Ghasedak\n\n```ts\n{\n  provider: 'ghasedak',\n  apiKey: string,       // from ghasedak.me account\n  lineNumber: string,   // e.g. '5000XXXXX'\n}\n```\n\n## API Reference\n\n| Method | Parameters | Returns | Description |\n|---|---|---|---|\n| `send(params)` | `SendParams` | `Promise<SendResult \\| SendResult[]>` | Send single or bulk SMS |\n| `sendPattern(params)` | `PatternParams` | `Promise<SendResult>` | Send OTP or template SMS |\n| `getStatus(params)` | `StatusParams` | `Promise<DeliveryResult>` | Check delivery status of a sent message |\n| `getCredit()` | — | `Promise<CreditResult>` | Get account balance |\n| `getProvider()` | — | `SmsProviderName` | Returns the active provider name |\n\n> In safe mode (`safe: true`), all methods return `Promise<SmsResult<T>>` instead.\n\n### SendParams\n\n```ts\ninterface SendParams {\n  to: string | string[];   // single number or array for bulk\n  message: string;\n  lineNumber?: string;     // override the default line number\n  sendAt?: Date;           // schedule for future delivery (provider-dependent)\n}\n```\n\n### PatternParams\n\n```ts\ninterface PatternParams {\n  to: string;\n  templateId: string;                    // template/pattern ID from your provider panel\n  variables: Record<string, string>;     // template variables\n  lineNumber?: string;\n}\n```\n\n### SmsResult\\<T\\> (safe mode)\n\n```ts\ntype SmsResult<T> =\n  | { success: true;  data: T }\n  | { success: false; error: IranSmsError }\n```\n\n## n8n Usage\n\nThis package works in n8n custom Function nodes. Import it as a regular Node.js module. A dedicated `@alikhangholi/n8n-nodes-iran-sms` community node is in development.\n\n```js\nconst { IranSms } = require('@alikhangholi/iran-sms');\nconst sms = new IranSms({ provider: { provider: 'kavenegar', apiKey: $env.KAVEH_API_KEY, lineNumber: '10004346' } });\nconst result = await sms.send({ to: $json.phone, message: $json.message });\nreturn [{ json: result }];\n```\n\n## License\n\nMIT © alikhangholi\n","readmeFilename":"README.md","_rev":"1-7298052c038eff686db0a75e9ce94827"}