From fc78c6afa4b304612836071ad56adb0cad594936 Mon Sep 17 00:00:00 2001 From: Andres Contreras Date: Wed, 11 Feb 2026 10:13:04 +0100 Subject: [PATCH] docs: add professional README with unified template (#6) Standardize README.md with a consistent template including CI badge, features, installation, quick start, configuration, and documentation sections. Add paths-ignore to ci.yml to skip CI for docs-only changes. --- .github/workflows/ci.yml | 19 ++-- README.md | 183 ++++++++++++++------------------------- 2 files changed, 79 insertions(+), 123 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9093b6..9567aee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,22 @@ name: CI on: push: branches: [develop] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' pull_request: branches: [develop, main] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' workflow_dispatch: inputs: triggered-by: @@ -13,10 +27,5 @@ on: jobs: build: uses: fireflyframework/.github/.github/workflows/java-ci.yml@main - permissions: - packages: read - contents: read - actions: write with: java-version: '25' - secrets: inherit diff --git a/README.md b/README.md index 00df83d..2f39fce 100644 --- a/README.md +++ b/README.md @@ -1,145 +1,92 @@ -# fireflyframework-notifications-twilio +# Firefly Framework - Notifications - Twilio [![CI](https://github.com/fireflyframework/fireflyframework-notifications-twilio/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-notifications-twilio/actions/workflows/ci.yml) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) +[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org) +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot) -Twilio SMS adapter for Firefly Notifications Library. +> Twilio SMS adapter for Firefly Notifications. -## Overview - -This module is an **infrastructure adapter** in the hexagonal architecture that implements the `SMSProvider` port interface. It handles all Twilio-specific integration details, including API authentication, request formatting, and SMS delivery. +--- -### Architecture Role +## Table of Contents -``` -Application Layer (SMSService) - ↓ depends on -Domain Layer (SMSProvider interface) - ↑ implemented by -Infrastructure Layer (TwilioSMSProvider) ← THIS MODULE - ↓ calls -Twilio REST API -``` +- [Overview](#overview) +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Configuration](#configuration) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) -This adapter can be replaced with other SMS providers (AWS SNS, Vonage) without changing your application code. +## Overview -## Installation +Firefly Framework Notifications Twilio implements the `SMSProvider` interface from the Firefly Notifications core module using Twilio as the delivery provider. It provides `TwilioSMSProvider` which handles SMS delivery through the Twilio API. -Add these dependencies to your `pom.xml`: +The module includes auto-configuration for seamless activation when included on the classpath alongside the notifications core module. Configuration properties allow customizing API credentials and provider-specific settings. -```xml path=null start=null - - org.fireflyframework - fireflyframework-notifications-core - 1.0.0-SNAPSHOT - +## Features - - org.fireflyframework - fireflyframework-notifications-twilio - 1.0.0-SNAPSHOT - -``` +- `SMSProvider` implementation using Twilio +- Spring Boot auto-configuration for seamless activation +- Configurable API credentials via application properties +- Standalone provider library (include alongside fireflyframework-notifications) -## Configuration +## Requirements -Add the following to your `application.yml`: +- Java 21+ +- Spring Boot 3.x +- Maven 3.9+ +- Twilio account and API credentials -```yaml path=null start=null -notifications: - sms: - provider: twilio # Enables this adapter +## Installation -twilio: - config: - account-sid: ${TWILIO_ACCOUNT_SID} - auth-token: ${TWILIO_AUTH_TOKEN} - phone-number: "+1234567890" # Your Twilio phone number +```xml + + org.fireflyframework + fireflyframework-notifications-twilio + 26.01.01 + ``` -### Getting Your Credentials - -1. Sign up at [twilio.com](https://www.twilio.com) -2. Get your Account SID and Auth Token from the console dashboard -3. Purchase or verify a phone number -4. Set as environment variables: - ```bash - export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" - export TWILIO_AUTH_TOKEN="your-auth-token" - ``` - -## Usage - -Inject `SMSService` from the core library. Spring automatically wires this adapter: - -```java path=null start=null -@Service -public class VerificationService { - - @Autowired - private SMSService smsService; - - public void sendVerificationCode(String phoneNumber, String code) { - SMSRequestDTO request = SMSRequestDTO.builder() - .phoneNumber(phoneNumber) - .message("Your verification code is: " + code) - .build(); - - smsService.sendSMS(request) - .subscribe(response -> { - if (response.isSuccess()) { - log.info("SMS sent: {}", response.getMessageId()); - } else { - log.error("Failed: {}", response.getError()); - } - }); - } -} +## Quick Start + +```xml + + + org.fireflyframework + fireflyframework-notifications + + + org.fireflyframework + fireflyframework-notifications-twilio + + ``` -## Features - -- **International SMS** - Supports sending to any country Twilio serves -- **Synchronous API** - Returns response immediately -- **Error handling** - Validates phone numbers and handles API errors -- **Delivery tracking** - Returns Twilio message SID for status tracking - -## Switching Providers - -To switch from Twilio to another SMS provider: - -1. Remove this dependency from `pom.xml` -2. Add alternative SMS adapter dependency -3. Update configuration to use different provider - -**No code changes required** in your services—hexagonal architecture ensures provider independence! - -## Implementation Details - -This adapter: -- Implements `SMSProvider` interface from `fireflyframework-notifications-core` -- Uses Twilio Java SDK for API calls -- Transforms `SMSRequestDTO` to Twilio's `Message` format -- Handles authentication via Account SID and Auth Token -- Returns standardized `SMSResponseDTO` - -## Troubleshooting +## Configuration -### Error: "No qualifying bean of type 'SMSProvider'" +```yaml +firefly: + notifications: + twilio: + account-sid: ACxxxxxxxxxx + auth-token: your-auth-token + from-number: +1234567890 +``` -- Ensure `notifications.sms.provider=twilio` is set -- Verify Twilio credentials are configured +## Documentation -### Error: "Invalid phone number" +No additional documentation available for this project. -- Phone numbers must be in E.164 format (e.g., +1234567890) -- Ensure the number includes country code +## Contributing -### Error: "Insufficient balance" +Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests. -- Check your Twilio account balance -- Add funds or use trial credits for testing +## License -## References +Copyright 2024-2026 Firefly Software Solutions Inc. -- [Twilio SMS API Documentation](https://www.twilio.com/docs/sms/api) -- [Firefly Notifications Architecture](../fireflyframework-notifications/ARCHITECTURE.md) +Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.