sms-verification-api 0.9.1

package/docs/openapi.json

@@ -0,0 +1,329 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "SMS Verification API",
+    "description": "A comprehensive SMS verification API using AWS SNS HTTP API with Hono server on Cloudflare Workers. **Authentication Required**: All endpoints except `/health`, `/docs`, and `/openapi.json` require API key authentication.",
+    "contact": { "name": "API Support", "email": "support@example.com" },
+    "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }
+  },
+  "servers": [
+    {
+      "url": "https://sms-verification-api.your-subdomain.workers.dev",
+      "description": "Production server"
+    },
+    {
+      "url": "https://sms-verification-api-staging.your-subdomain.workers.dev",
+      "description": "Staging server"
+    }
+  ],
+  "components": { "schemas": {}, "parameters": {} },
+  "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
+  "paths": {
+    "/health": {
+      "get": {
+        "tags": ["health"],
+        "summary": "Health check",
+        "description": "Returns the health status of the API server",
+        "responses": {
+          "200": {
+            "description": "Health check successful",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": { "type": "string", "example": "ok" },
+                    "timestamp": {
+                      "type": "string",
+                      "example": "2024-01-01T00:00:00.000Z"
+                    },
+                    "server": {
+                      "type": "string",
+                      "example": "Hono on Cloudflare Workers"
+                    }
+                  },
+                  "required": ["status", "timestamp", "server"]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/send-verification": {
+      "post": {
+        "tags": ["verification"],
+        "summary": "Send SMS verification code",
+        "description": "Sends a 6-digit verification code to the specified phone number via SMS. Optionally accepts a custom code.",
+        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "phoneNumber": {
+                    "type": "string",
+                    "pattern": "^\\+[1-9]\\d{1,14}$",
+                    "description": "Phone number in E.164 format",
+                    "example": "+1234567890"
+                  },
+                  "code": {
+                    "type": "string",
+                    "minLength": 6,
+                    "maxLength": 6,
+                    "pattern": "^\\d{6}$",
+                    "description": "Optional custom 6-digit verification code. If not provided, a random code will be generated.",
+                    "example": "123456"
+                  }
+                },
+                "required": ["phoneNumber"]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Verification code sent successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": { "type": "boolean", "example": true },
+                    "message": {
+                      "type": "string",
+                      "example": "Verification code sent successfully"
+                    },
+                    "messageId": {
+                      "type": "string",
+                      "example": "aws-message-id-123"
+                    },
+                    "expiresIn": {
+                      "type": "number",
+                      "description": "Expiration time in seconds",
+                      "example": 600
+                    }
+                  },
+                  "required": ["success", "message", "messageId", "expiresIn"]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - invalid phone number or other validation error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "Validation error"
+                    },
+                    "details": {
+                      "type": "string",
+                      "example": "Additional error details"
+                    }
+                  },
+                  "required": ["error"]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Too many requests - rate limited",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "Please wait before requesting another code"
+                    },
+                    "retryAfter": {
+                      "type": "number",
+                      "description": "Seconds to wait before retry",
+                      "example": 30
+                    }
+                  },
+                  "required": ["error", "retryAfter"]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "Validation error"
+                    },
+                    "details": {
+                      "type": "string",
+                      "example": "Additional error details"
+                    }
+                  },
+                  "required": ["error"]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/verify-code": {
+      "post": {
+        "tags": ["verification"],
+        "summary": "Verify SMS code",
+        "description": "Verifies the submitted code against the sent verification code",
+        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "phoneNumber": {
+                    "type": "string",
+                    "pattern": "^\\+[1-9]\\d{1,14}$",
+                    "description": "Phone number in E.164 format",
+                    "example": "+1234567890"
+                  },
+                  "code": {
+                    "type": "string",
+                    "minLength": 6,
+                    "maxLength": 6,
+                    "pattern": "^\\d{6}$",
+                    "description": "6-digit verification code",
+                    "example": "123456"
+                  }
+                },
+                "required": ["phoneNumber", "code"]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Phone number verified successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": { "type": "boolean", "example": true },
+                    "message": {
+                      "type": "string",
+                      "example": "Phone number verified successfully"
+                    },
+                    "verificationToken": {
+                      "type": "string",
+                      "example": "unique-verification-token"
+                    },
+                    "phoneNumber": {
+                      "type": "string",
+                      "pattern": "^\\+[1-9]\\d{1,14}$",
+                      "description": "Phone number in E.164 format",
+                      "example": "+1234567890"
+                    }
+                  },
+                  "required": [
+                    "success",
+                    "message",
+                    "verificationToken",
+                    "phoneNumber"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - invalid code or expired",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error": {
+                          "type": "string",
+                          "example": "Validation error"
+                        },
+                        "details": {
+                          "type": "string",
+                          "example": "Additional error details"
+                        }
+                      },
+                      "required": ["error"]
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error": {
+                          "type": "string",
+                          "example": "Invalid verification code"
+                        },
+                        "attemptsRemaining": { "type": "number", "example": 3 }
+                      },
+                      "required": ["error", "attemptsRemaining"]
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Too many verification attempts",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "Validation error"
+                    },
+                    "details": {
+                      "type": "string",
+                      "example": "Additional error details"
+                    }
+                  },
+                  "required": ["error"]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "Validation error"
+                    },
+                    "details": {
+                      "type": "string",
+                      "example": "Additional error details"
+                    }
+                  },
+                  "required": ["error"]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/docs/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "example-openapi",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "build": "next build",
+    "build:api": "bun run ./scripts/generate-docs.mjs",
+    "dev": "next dev --turbo",
+    "start": "next start --port 3001",
+    "types:check": "fumadocs-mdx && tsc --noEmit",
+    "deploy": "wrangler deploy",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:production": "wrangler deploy --env production"
+  },
+  "dependencies": {
+    "@fumadocs/mdx-remote": "^1.3.4",
+    "fumadocs-core": "15.6.1",
+    "fumadocs-mdx": "11.6.10",
+    "fumadocs-openapi": "^9.1.0",
+    "fumadocs-ui": "15.6.1",
+    "lucide-react": "^0.525.0",
+    "next": "15.3.4",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "shiki": "^3.7.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.11",
+    "@types/mdx": "^2.0.13",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "postcss": "^8.5.6",
+    "rimraf": "^6.0.1",
+    "tailwindcss": "^4.1.11",
+    "typescript": "^5.8.3"
+  }
+}

package/docs/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};

package/docs/scripts/generate-docs.mjs

@@ -0,0 +1,23 @@
+import * as OpenAPI from 'fumadocs-openapi';
+import { rimraf } from 'rimraf';
+
+const out = './content/docs/(api)';
+
+async function generate() {
+  // clean generated files
+  await rimraf(out, {
+    filter(v) {
+      return !v.endsWith('index.mdx') && !v.endsWith('meta.json');
+    },
+  });
+
+  await OpenAPI.generateFiles({
+    // input files
+    input: ['./openapi.json'],
+    output: out,
+    includeDescription: false,
+    
+  });
+}
+
+void generate();

package/docs/source.config.ts

@@ -0,0 +1,5 @@
+import { defineDocs } from 'fumadocs-mdx/config';
+
+export const { docs, meta } = defineDocs({
+  dir: 'content/docs',
+});

package/docs/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "target": "ESNext",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "paths": {
+      "@/*": ["./*"]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/docs/worker.js

@@ -0,0 +1,35 @@
+// Simple worker to serve static Next.js export files
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    let path = url.pathname;
+    
+    // Default to index.html for root
+    if (path === '/') {
+      path = '/index.html';
+    }
+    
+    // Try to serve the file from the out directory
+    try {
+      const file = await env.ASSETS.fetch(new Request(url.origin + path));
+      if (file.status === 200) {
+        return file;
+      }
+    } catch (e) {
+      // File not found, continue to fallback
+    }
+    
+    // Fallback to index.html for SPA routing
+    try {
+      const indexFile = await env.ASSETS.fetch(new Request(url.origin + '/index.html'));
+      if (indexFile.status === 200) {
+        return indexFile;
+      }
+    } catch (e) {
+      // Index file not found
+    }
+    
+    // Return 404
+    return new Response('Not Found', { status: 404 });
+  }
+};

package/docs/wrangler.toml

@@ -0,0 +1,26 @@
+name = "sms-verification-docs"
+main = "worker.js"
+compatibility_date = "2024-01-01"
+
+# Static assets
+[assets]
+directory = "out"
+
+# Build configuration
+[build]
+command = "bun run build"
+watch_dir = "."
+
+# Environment variables
+[vars]
+NODE_ENV = "production"
+
+# Staging environment
+[env.staging]
+name = "sms-verification-docs-staging"
+vars = { ENVIRONMENT = "staging" }
+
+# Production environment
+[env.production]
+name = "sms-verification-docs-production"
+vars = { ENVIRONMENT = "production" }

package/examples/client.js

@@ -0,0 +1,119 @@
+import grab from 'grab-api.js'
+/**
+ * Example client for the SMS Verification API
+ */
+
+const API_BASE_URL = 'http://localhost:8787'; // Change to your deployed URL
+const API_KEY = 'sms_1234567890abcdef1234567890abcdef'; // Change to your API key
+
+class SMSVerificationClient {
+  constructor(baseUrl = API_BASE_URL, apiKey = API_KEY) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+
+  async sendVerificationCode(phoneNumber, options = {}) {
+    await grab(`${this.baseUrl}/api/send`, {
+      headers: {
+        'X-API-Key': this.apiKey
+      },
+      phoneNumber,
+      ...options
+    });
+  }
+
+  async verifyCode(phoneNumber, code) {
+    const response = await fetch(`${this.baseUrl}/api/verify`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this.apiKey
+      },
+      body: JSON.stringify({
+        phoneNumber,
+        code
+      })
+    });
+
+    return response.json();
+  }
+
+  async sendGeneralSMS(phoneNumber, message, options = {}) {
+    const response = await fetch(`${this.baseUrl}/api/sms`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this.apiKey
+      },
+      body: JSON.stringify({
+        phoneNumber,
+        message,
+        ...options
+      })
+    });
+
+    return response.json();
+  }
+
+  async checkHealth() {
+    const response = await fetch(`${this.baseUrl}/health`);
+    return response.json();
+  }
+}
+
+// Example usage
+async function example() {
+  const client = new SMSVerificationClient();
+
+  try {
+    // Check server health
+    console.log('Checking server health...');
+    const health = await client.checkHealth();
+    console.log('Health:', health);
+
+    // Send verification code
+    console.log('\nSending verification code...');
+    const sendResult = await client.sendVerificationCode('+1234567890', {
+      blockVoip: true,
+      senderId: 'MyApp',
+      messageTemplate: 'Your verification code is: {code}. Valid for 10 minutes.'
+    });
+    console.log('Send result:', sendResult);
+
+    if (sendResult.success) {
+      // Verify the code (in real app, user would enter this)
+      console.log('\nVerifying code...');
+      const verifyResult = await client.verifyCode('+1234567890', sendResult.code);
+      console.log('Verify result:', verifyResult);
+    }
+
+    // Send general SMS
+    console.log('\nSending general SMS...');
+    const smsResult = await client.sendGeneralSMS(
+      '+1234567890',
+      'Hello from your app! This is a test message.',
+      { senderId: 'MyApp' }
+    );
+    console.log('SMS result:', smsResult);
+
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+// Node.js usage
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = SMSVerificationClient;
+  
+  // Run example if this file is executed directly
+  if (require.main === module) {
+    example();
+  }
+}
+
+// Browser usage
+if (typeof window !== 'undefined') {
+  window.SMSVerificationClient = SMSVerificationClient;
+}
+
+export default SMSVerificationClient;