{"id":28576227,"url":"https://github.com/zauberware/smshog","last_synced_at":"2025-07-18T04:36:35.455Z","repository":{"id":290943506,"uuid":"975796465","full_name":"zauberware/smshog","owner":"zauberware","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-06T13:07:18.000Z","size":336,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-10T23:09:17.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zauberware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-30T23:11:59.000Z","updated_at":"2025-05-06T13:07:22.000Z","dependencies_parsed_at":"2025-05-01T13:51:10.268Z","dependency_job_id":"f0642a50-58ff-495a-8dcf-e64a18ebf5f7","html_url":"https://github.com/zauberware/smshog","commit_stats":null,"previous_names":["zauberware/smshog"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zauberware/smshog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zauberware%2Fsmshog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zauberware%2Fsmshog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zauberware%2Fsmshog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zauberware%2Fsmshog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zauberware","download_url":"https://codeload.github.com/zauberware/smshog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zauberware%2Fsmshog/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265701259,"owners_count":23813751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-10T23:09:15.637Z","updated_at":"2025-07-18T04:36:35.430Z","avatar_url":"https://github.com/zauberware.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SMSHog: AWS SNS SMS Mock and Display Tool\n\nSMSHog mocks the AWS SNS SMS API, allowing clients (using aws-sdk v3) to send SMS via the SNS Publish route to SMSHog. The mock API stores these SMS messages and displays them through a MailHog-like web interface.\n\n![SMSHog](media/demo.png)\n\n## Features\n\n- Mock AWS SNS SMS API with support for the Publish and SetSMSAttributes actions\n- Capture and display SMS messages with sender ID information\n- Web UI to view and manage received messages\n- Delete individual or all SMS messages\n- Docker support for easy setup and deployment\n\n## Motivation\n\nWhile developing and testing applications that send SMS using **AWS SNS SMS**, we identified a need for a straightforward tool to simulate message sending, store messages, and display them in a user-friendly interface—much like how MailHog functions for emails. Existing solutions were either overly complex, not specifically tailored to **AWS SNS SMS**, or lacked a web interface to **view** received SMS messages. To bridge this gap, we developed **SMSHog**: a lightweight tool that can be easily run with Docker, providing a realistic local testing environment for sending SMS via **AWS SNS SMS**. This tool simplifies integration and debugging processes without the need to send actual messages or incur additional costs.\n\n## Getting Started\n\n### Prerequisites\n\n- Docker installed\n\n### Running SMSHog\n\n#### Docker run\n\nTo run SMSHog using Docker, you can use the following command:\n\n```bash\ndocker run  -p 8080:8080 zauberware/smshog\n```\n\nThis command will:\n\n- Pull the latest SMSHog image from Docker Hub\n- Map port 8080 of the container to port 8080 on your host machine\n- Start the SMSHog server\n- Access the web UI at http://localhost:8080\n\n#### Docker Compose\n\nAlternatively, you can use Docker Compose for a more flexible setup. This is especially useful if you want to run SMSHog with additional services or configurations.\n\n1. Clone this repository:\n\n```bash\ngit clone git@github.com:zauberware/smshog.git\ncd smshog\n```\n\n2. Copy the `.env.example` file to `.env` and adjust the settings as needed.\n\n```bash\ncp .env.example .env\n```\n\n2. Start the application:\n\n```bash\ndocker compose up\n```\n\n3. Access the web UI at http://localhost:8080\n\n#### Development Mode\n\nFor development with hot-reloading:\n\n```bash\ndocker compose -f docker-compose.dev.yml up\n```\n\n## Using with AWS SDK\n\nExample of how to use SMSHog with the AWS SDK v3:\n\n```javascript\nimport {\n  SNSClient,\n  PublishCommand,\n  SetSMSAttributesCommand,\n} from '@aws-sdk/client-sns';\n\n// Configure the SNS client to use the local SMSHog server\nconst snsClient = new SNSClient({\n  region: 'us-east-1',\n  endpoint: 'https://localhost:8080', // SMSHog endpoint\n  credentials: {\n    accessKeyId: 'dummy-access-key',\n    secretAccessKey: 'dummy-secret-key',\n  },\n});\n\n// Send an SMS\nasync function sendSMS() {\n  const params = {\n    Message: 'Hello from Javascript!',\n    PhoneNumber: '+491234567890', // Replace with the recipient's phone number\n  };\n\n  try {\n    await snsClient.send(\n      new SetSMSAttributesCommand({\n        attributes: {\n          DefaultSenderID: 'MySenderId',\n          DefaultSMSType: 'Transactional',\n          UsageReportS3Bucket: 'my-s3-bucket',\n        },\n      })\n    );\n    const data = await snsClient.send(new PublishCommand(params));\n    console.log('Success! Message ID:', data.MessageId);\n  } catch (err) {\n    console.error('Error sending message:', err);\n  }\n}\n\nsendSMS();\n```\n\nfurther example usage can be found in the [examples](./examples) directory.\n\n## API Endpoints\n\n### SNS Mock API\n\n- `POST /` or `POST /sms` - Handle SNS Publish requests\n\n### REST API\n\n- `GET /api/v1/health` - Check the health of the server\n- `GET /api/v1/sms` - Get all SMS messages\n- `GET /api/v1/sms/:id` - Get a specific SMS message\n- `DELETE /api/v1/sms/:id` - Delete a specific SMS message\n- `DELETE /api/v1/sms` - Delete all SMS messages\n\n## Architecture\n\nSMSHog consists of two main components:\n\n1. **Backend**: Node.js/Express server with TypeScript that implements the AWS SNS mock API\n2. **Frontend**: React with TypeScript and Vite for displaying and managing SMS messages\n\n## Data Persistence\n\nBy default, SMSHog stores all messages in memory, which means they'll be lost when the server restarts.  \nTo enable data persistence, set the following environment variables:\n\n```bash\n# Enable persistence\nSMSHOG_PERSIST=true\n\n# Optional: Specify a custom path for the data file (default: /data/sms-store.json)\nSMSHOG_PERSIST_PATH=/path/to/your/data/file.json\n```\n\nWhen using Docker, you can enable persistence by:\n\n```bash\ndocker run -e SMSHOG_PERSIST=true -v $(pwd)/data:/data smshog\n```\n\n## Environment Variables\n\n| Variable            | Description                           | Default Value        |\n| ------------------- | ------------------------------------- | -------------------- |\n| SMSHOG_PERSIST      | Enable data persistence (true/false)  | false                |\n| SMSHOG_PERSIST_PATH | Path to the data file for persistence | /data/sms-store.json |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzauberware%2Fsmshog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzauberware%2Fsmshog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzauberware%2Fsmshog/lists"}