sms-verification-api 0.9.1

package/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/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "sms-verification-api",
+  "version": "0.9.1",
+  "description": "SMS Phone Verification API using AWS SNS HTTP API with Hono server on Cloudflare Workers",
+  "main": "src/verify-phone.js",
+  "type": "module",
+  "types": "./src/verify-phone.d.ts",
+  "module": "./src/verify-phone.js",
+  "exports": {
+    ".": {
+      "types": "./src/verify-phone.d.ts",
+      "import": "./src/verify-phone.js",
+      "require": "./src/verify-phone.js"
+    }
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "ship": "bun run standard-version --release-as patch; bun publish",
+    "deploy": "wrangler deploy",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:production": "wrangler deploy --env production",
+    "deploy:docs": "cd docs && bun run build && wrangler deploy",
+    "deploy:docs:staging": "cd docs && bun run build && wrangler deploy --env staging",
+    "deploy:docs:production": "cd docs && bun run build && wrangler deploy --env production",
+    "deploy:all": "bun run deploy && bun run deploy:docs",
+    "deploy:all:staging": "bun run deploy:staging && bun run deploy:docs:staging",
+    "deploy:all:production": "bun run deploy:production && bun run deploy:docs:production",
+    "build": "echo 'No build step needed for Workers'",
+    "build:docs": "cd docs && bun run build",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:ui": "vitest --ui",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "sms",
+    "verification",
+    "aws",
+    "sns",
+    "phone",
+    "otp",
+    "2fa",
+    "hono",
+    "cloudflare-workers",
+    "wrangler"
+  ],
+  "author": "vtempest",
+  "license": "MIT",
+  "dependencies": {
+    "@hono/swagger-ui": "^0.5.2",
+    "@hono/zod-openapi": "^0.19.9",
+    "grab-api.js": "^0.9.131",
+    "hono": "^3.12.8",
+    "hono-rate-limiter": "^0.2.2",
+    "libphonenumber-js": "^1.12.13"
+  },
+  "devDependencies": {
+    "wrangler": "^4.24.0",
+    "eslint": "^8.55.0",
+    "prettier": "^3.1.0",
+    "vitest": "^1.0.0",
+    "@vitest/ui": "^1.0.0",
+    "supertest": "^6.3.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenSourceAGI/appdemo-dev-tools/tree/master/packages/verify-phone-sms"
+  },
+  "homepage": "https://github.com/OpenSourceAGI/appdemo-dev-tools/tree/master/packages/verify-phone-sms"
+}

package/scripts/deploy.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+
+# Deployment script for SMS Verification API and Docs
+# Usage: ./scripts/deploy.sh [environment] [component]
+
+set -e
+
+ENVIRONMENT=${1:-default}
+COMPONENT=${2:-all}
+
+echo "🚀 Starting deployment..."
+echo "Environment: $ENVIRONMENT"
+echo "Component: $COMPONENT"
+
+# Function to deploy API
+deploy_api() {
+    echo "📡 Deploying API to $ENVIRONMENT..."
+    if [ "$ENVIRONMENT" = "production" ]; then
+        npm run deploy:production
+    elif [ "$ENVIRONMENT" = "staging" ]; then
+        npm run deploy:staging
+    else
+        npm run deploy
+    fi
+    echo "✅ API deployment completed!"
+}
+
+# Function to deploy docs
+deploy_docs() {
+    echo "📚 Building and deploying docs to $ENVIRONMENT..."
+    bun run build:docs
+    
+    if [ "$ENVIRONMENT" = "production" ]; then
+        cd docs && wrangler deploy --env production && cd ..
+    elif [ "$ENVIRONMENT" = "staging" ]; then
+        cd docs && wrangler deploy --env staging && cd ..
+    else
+        cd docs && wrangler deploy && cd ..
+    fi
+    echo "✅ Docs deployment completed!"
+}
+
+# Main deployment logic
+case $COMPONENT in
+    "api")
+        deploy_api
+        ;;
+    "docs")
+        deploy_docs
+        ;;
+    "all")
+        deploy_api
+        deploy_docs
+        ;;
+    *)
+        echo "❌ Invalid component. Use: api, docs, or all"
+        exit 1
+        ;;
+esac
+
+echo "🎉 Deployment completed successfully!"
+echo "Environment: $ENVIRONMENT"
+echo "Component: $COMPONENT"