@gtech_/nando-sdk 1.0.0

package/README.md

@@ -0,0 +1,94 @@
+# @nando/sdk
+
+Official Node & Bun SDK for the [Nando](https://nando.ge) SMS public API. Send messages and verify signed delivery webhooks. Zero dependencies — uses the global `fetch` and `node:crypto`.
+
+## Installation
+
+```bash
+npm install @nando/sdk
+# or
+bun add @nando/sdk
+```
+
+Requires Node 18+ or Bun.
+
+## Quick start
+
+```ts
+import { NandoClient } from '@nando/sdk'
+
+const nando = new NandoClient({ apiKey: 'sk_nando_live...' }) // or set NANDO_API_KEY
+
+const sms = await nando.sendSms({
+  body: 'Your verification code is 123456',
+  recipients: ['+995555123456'],
+  smsSubType: 'transactional', // 'otp' | 'transactional' | 'regular'
+})
+
+console.log('queued', sms.id)
+```
+
+`brandNameId` is optional — your default brand name is used when omitted. Schedule for later with `smsType: 'scheduled'` and `scheduledAt: '2026-06-24T12:00:00Z'`.
+
+## Account info
+
+```ts
+const info = await nando.selfInfo()
+info.sms_balance
+info.brand_names
+
+await nando.test() // boolean — is the API key valid?
+```
+
+## Error handling
+
+Any non-2xx response rejects with `NandoApiError`:
+
+```ts
+import { NandoApiError } from '@nando/sdk'
+
+try {
+  await nando.sendSms({ body: '', recipients: [] })
+} catch (e) {
+  if (e instanceof NandoApiError) {
+    e.status // 400, 401, 403 ...
+    e.errors // { body: 'is required' } or { error: '...' }
+  }
+}
+```
+
+## Webhooks
+
+Nando POSTs a signed JSON event to your webhook URL when an API-originated SMS job changes status. Verify the Ed25519 signature over the **raw** body before parsing — an Express example:
+
+```ts
+import express from 'express'
+import { verifyWebhookSignature } from '@nando/sdk'
+
+const app = express()
+const PUBLIC_KEY = process.env.NANDO_WEBHOOK_PUBLIC_KEY!
+
+// express.raw keeps req.body a Buffer so the signature stays valid.
+app.post('/webhooks/nando', express.raw({ type: '*/*' }), (req, res) => {
+  const ok = verifyWebhookSignature(req.body, req.header('X-Nando-Signature') ?? '', PUBLIC_KEY)
+  if (!ok) return res.sendStatus(401)
+
+  const event = JSON.parse(req.body.toString('utf8'))
+  // deduplicate by event.event_id; check event.summary.failed_count
+  res.sendStatus(200)
+})
+```
+
+Return `200 OK` to acknowledge. Other statuses, timeouts, or errors trigger up to 5 retries with exponential backoff.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run build   # emits dist/ via tsc
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@gtech_/nando-sdk",
+  "version": "1.0.0",
+  "description": "Official Node & Bun SDK for the Nando SMS public API — send messages and verify signed delivery webhooks.",
+  "author": "Gtech",
+  "license": "MIT",
+  "homepage": "https://nando.ge",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "keywords": ["nando", "sms", "otp", "webhooks", "ed25519", "bun"],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}