@minimoth/sdk-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiniMoth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @minimoth/sdk-node
+
+Official Node.js SDK for [MiniMoth](https://minimoth.dev) — SMS and WhatsApp OTP authentication for Indian developers.
+
+## Installation
+
+```bash
+npm install @minimoth/sdk-node
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```ts
+import { MiniMoth } from '@minimoth/sdk-node'
+
+const client = new MiniMoth({
+  apiKey: 'mm_live_...',  // from app.minimoth.dev
+})
+
+// Send OTP
+await client.otp.send({ phone: '919876543210' })
+
+// Verify OTP
+const result = await client.otp.verify({ phone: '919876543210', otp: '123456' })
+if (result.valid) {
+  // Store tokens — SDK auto-stores in memory by default
+  console.log(result.accessToken, result.refreshToken, result.sessionId)
+}
+
+// Validate on every request
+const session = await client.session.validate(req.headers['x-access-token'])
+// session.phone, session.projectId, session.sessionId, session.expiresAt
+// If session.newTokens is set, send new tokens back to client
+
+// Safe variant — never throws
+const safe = await client.session.safeValidate(token)
+if (!safe.valid) {
+  res.status(401).json({ error: safe.code })
+  return
+}
+
+// Refresh — SDK handles this automatically on validate(); call manually only if needed proactively
+const tokens = await client.session.refresh(refreshToken)
+
+// Logout (auto-refreshes if access token is expired)
+await client.session.logout({ accessToken, refreshToken })
+```
+
+## Configuration
+
+```ts
+const client = new MiniMoth({
+  apiKey: 'mm_live_...',        // required
+
+  // Logging
+  logLevel: 'info',             // 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  logger: pinoInstance,         // optional — any { debug, info, warn, error } object
+
+  // Session
+  session: {
+    validateMode: 'instant',    // see validateMode below
+    store: myRedisStore,        // optional — see Session Store below
+  }
+})
+
+client.setLogLevel('warn')      // update at runtime (only affects built-in console logger)
+```
+
+## validateMode
+
+| Mode | What it does | On network error |
+|---|---|---|
+| `instant` (default) | Local JWT verify only — zero network round trip | n/a |
+| `recheck_1m` | JWT verify + revocation check, cached 60s per token | Fail open (warn + allow) |
+| `recheck_3m` | JWT verify + revocation check, cached 180s per token | Fail open (warn + allow) |
+| `strict` | JWT verify + revocation check on every call | Fail closed (throw) |
+
+## Session Store
+
+By default, the SDK uses an in-memory Map. In production with multiple server replicas, provide a shared store (e.g. Redis):
+
+```ts
+const client = new MiniMoth({
+  apiKey: 'mm_live_...',
+  session: {
+    store: {
+      async getRefreshToken(sessionId) {
+        return redis.get(`mm:rt:${sessionId}`)
+      },
+      async setTokens(sessionId, { accessToken, refreshToken }) {
+        await redis.set(`mm:rt:${sessionId}`, refreshToken, 'EX', 30 * 24 * 60 * 60)
+      },
+      async deleteSession(sessionId) {
+        await redis.del(`mm:rt:${sessionId}`)
+      },
+    }
+  }
+})
+```
+
+## Error Handling
+
+```ts
+import { MiniMothError } from '@minimoth/sdk-node'
+
+try {
+  await client.session.validate(token)
+} catch (err) {
+  if (err instanceof MiniMothError) {
+    // err.code: 'TOKEN_EXPIRED' | 'TOKEN_REVOKED' | 'INVALID_TOKEN' | ...
+    // err.statusCode: HTTP status (0 for network errors)
+    res.status(401).json({ error: err.code })
+  }
+}
+```
+
+Use `safeValidate` / `otp.verify` to avoid try/catch:
+
+```ts
+const result = await client.session.safeValidate(token)
+if (!result.valid) return res.status(401).json({ error: result.code })
+const { session } = result
+```
+
+## API Reference
+
+### OtpClient
+
+#### `send(options)`
+
+Send an OTP to the given phone number.
+
+- `phone` (string, required): Indian phone number (e.g. `919876543210`)
+- Returns: Promise<void>
+- Throws: `MiniMothError` on rate limit or network error
+
+#### `verify(options)`
+
+Verify the OTP code and establish a session.
+
+- `phone` (string, required): Indian phone number
+- `otp` (string, required): 6-digit OTP
+- Returns: Promise<{ valid: boolean; accessToken?: string; refreshToken?: string; sessionId?: string }>
+- Does not throw; always returns a result object
+
+### SessionClient
+
+#### `validate(accessToken)`
+
+Validate an access token and return the session.
+
+- `accessToken` (string, required): JWT access token
+- Returns: Promise<Session> where Session includes `phone`, `projectId`, `sessionId`, `expiresAt`, and optionally `newTokens`
+- Throws: `MiniMothError` on invalid, expired, or revoked token
+
+#### `safeValidate(accessToken)`
+
+Non-throwing variant of `validate`.
+
+- `accessToken` (string, required): JWT access token
+- Returns: Promise<{ valid: boolean; session?: Session; code?: string }>
+
+#### `refresh(refreshToken)`
+
+Manually rotate access and refresh tokens ahead of expiry. The SDK handles refresh automatically when `session.validate()` encounters an expired access token — use this method only when you need to refresh proactively (e.g. before a long-running job).
+
+- `refreshToken` (string, required): Refresh token from verify or previous refresh
+- Returns: Promise<{ accessToken: string; refreshToken: string }>
+- Throws: `MiniMothError` on invalid or expired token
+
+#### `logout(options)`
+
+Revoke all tokens for a session.
+
+- `accessToken` (string, required): Current access token (will be auto-refreshed if expired)
+- `refreshToken` (string, required): Current refresh token
+- Returns: Promise<void>
+- Does not throw; logs errors instead
+
+## Error Codes
+
+Common `MiniMothError.code` values:
+
+- `INVALID_OTP`: OTP code does not match
+- `OTP_EXPIRED`: OTP has expired (max 10 minutes)
+- `INVALID_TOKEN`: Token could not be decoded
+- `TOKEN_EXPIRED`: Access token has expired (use refresh to get new token)
+- `TOKEN_REVOKED`: Token was revoked (session logout or theft detected)
+- `RATE_LIMITED`: Too many requests — wait before retrying
+- `INSUFFICIENT_BALANCE`: Account has insufficient credits/balance
+- `NETWORK_ERROR`: Network request failed
+- `UNKNOWN_ERROR`: Unexpected server error
+
+## TypeScript
+
+The SDK is fully typed. All client methods include inline JSDoc and return properly typed objects:
+
+```ts
+import { MiniMoth, MiniMothError } from '@minimoth/sdk-node'
+
+const client = new MiniMoth({ apiKey: 'mm_live_...' })
+
+// All methods are fully typed
+const result = await client.otp.verify({
+  phone: '919876543210',
+  otp: '123456',
+})
+
+const session: Session = await client.session.validate(token)
+```
+
+## License
+
+MIT