Documentation
¶
Overview ¶
Package controllers is the HTTP handler layer, built on Fiber. Each controller is a thin adapter for one group of routes: it parses and validates the incoming request, calls a service, and maps the result or error onto an HTTP response. Business logic stays in the services below; controllers only translate between HTTP and those services.
Every controller is constructed with its dependencies injected (NewAuthController, NewWebhookController, and so on), so handlers hold interfaces rather than reaching for globals. The doc comments carry Swagger annotations, which drive the generated API reference.
The controllers ¶
AuthController serves the challenge-response endpoints: it issues a Stellar challenge and, on a valid signed response, returns a JWT (see the auth package).
WebhookController receives inbound payment-provider webhooks. It verifies the provider's HMAC signature against the configured secret before handing the event to the webhook layer, and rejects anything unsigned or mismatched.
USSDController and SMSCallbackController handle the mobile-gateway callbacks. The USSD handler takes the provider from the URL path, forwards the session to the USSD service, and returns the CON/END string the gateway expects; the SMS handler ingests delivery-report callbacks and passes them to the SMS layer.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthController ¶
type AuthController struct {
// contains filtered or unexported fields
}
AuthController handles authentication endpoints including challenge generation and verification.
func NewAuthController ¶
func NewAuthController(challengeService auth.ChallengeService, jwtService *auth.JWTService, adminPublicKey string, validationService *validation.ValidatorService) *AuthController
NewAuthController creates a new AuthController with the provided services.
func (*AuthController) GetChallenge ¶
func (ctrl *AuthController) GetChallenge(c *fiber.Ctx) error
GetChallenge generates a new authentication challenge. @Description Generate a Stellar transaction challenge for authentication @Summary Get Authentication Challenge @Tags Authentication @Accept json @Produce json @Success 200 {object} ChallengeResponse "Challenge generated successfully" @Failure 500 {object} middleware.Response "Failed to generate challenge" @Router /api/v1/auth/challenge [get]
func (*AuthController) VerifyChallenge ¶
func (ctrl *AuthController) VerifyChallenge(c *fiber.Ctx) error
VerifyChallenge verifies a signed challenge and returns a JWT token. @Description Verify a signed Stellar transaction challenge and receive a JWT token @Summary Verify Challenge @Tags Authentication @Accept json @Produce json @Param body body VerifyRequest true "Signed challenge verification" @Success 200 {object} VerifyResponse "Challenge verified successfully" @Failure 400 {object} middleware.Response "Invalid request body or transaction" @Failure 401 {object} middleware.Response "Challenge verification failed" @Failure 404 {object} middleware.Response "Challenge not found" @Failure 500 {object} middleware.Response "Failed to generate token" @Router /api/v1/auth/verify [post]
type ChallengeResponse ¶
type ChallengeResponse struct {
ChallengeID string `json:"challenge_id"`
Transaction string `json:"transaction"`
ExpiresAt int64 `json:"expires_at"`
}
ChallengeResponse represents the authentication challenge response.
type SMSCallbackController ¶
type SMSCallbackController struct {
// contains filtered or unexported fields
}
SMSCallbackController handles SMS callback endpoints.
func NewSMSCallbackController ¶
func NewSMSCallbackController(handler *sms.DeliveryReportHandler) *SMSCallbackController
NewSMSCallbackController creates a new SMSCallbackController.
func (*SMSCallbackController) HandleDeliveryReport ¶
func (ctrl *SMSCallbackController) HandleDeliveryReport(c *fiber.Ctx) error
HandleDeliveryReport processes incoming SMS delivery report callbacks from Africa's Talking. AT sends form-encoded POST requests with delivery status updates. @Description Handle incoming SMS delivery report callbacks from Africa's Talking @Summary Process SMS Delivery Report @Tags Mobile @Accept application/x-www-form-urlencoded @Produce plain @Param id formData string true "AT message ID" @Param status formData string true "Delivery status" @Param phoneNumber formData string false "Recipient phone number" @Param networkCode formData string false "Network code" @Param failureReason formData string false "Failure reason (if applicable)" @Success 200 {string} string "ok" @Failure 400 {object} fiber.Error "Invalid callback payload" @Router /api/v1/mobile/sms/{provider}/delivery [post]
type USSDController ¶
type USSDController struct {
// contains filtered or unexported fields
}
USSDController handles USSD callback endpoints.
func NewUSSDController ¶
func NewUSSDController(ussdService *ussd.USSDService) *USSDController
NewUSSDController creates a new USSDController with the provided USSD service.
func (*USSDController) HandleCallback ¶
func (ctrl *USSDController) HandleCallback(c *fiber.Ctx) error
HandleCallback handles incoming USSD callback requests from any registered provider. @Description Handle USSD callback requests from the USSD gateway. The provider is specified in the URL path. @Summary USSD Callback Handler @Tags USSD @Accept application/x-www-form-urlencoded @Produce plain @Param provider path string true "USSD provider name (e.g. africastalking)" @Param sessionId formData string true "Session ID" @Param phoneNumber formData string true "User's phone number" @Param text formData string false "User input text" @Param serviceCode formData string true "USSD service code" @Param networkCode formData string false "Network code" @Success 200 {string} string "USSD response (CON/END)" @Failure 500 {string} string "END An error occurred. Please try again." @Router /api/v1/mobile/ussd/{provider} [post]
type VerifyRequest ¶
type VerifyRequest struct {
ChallengeID string `json:"challenge_id" validate:"required,base64url"`
SignedTransaction string `json:"signed_transaction" validate:"required,stellar_xdr"`
}
VerifyRequest represents the challenge verification request body.
type VerifyResponse ¶
VerifyResponse represents the challenge verification response.
type WebhookController ¶
type WebhookController struct {
// contains filtered or unexported fields
}
WebhookController handles webhook endpoints for payment providers.
func NewWebhookController ¶
func NewWebhookController(eventHandler webhook.WebhookEventHandler, apiKey, secretKey string) *WebhookController
NewWebhookController creates a new WebhookController with the provided dependencies. apiKey and secretKey are the YellowCard API credentials.
func (*WebhookController) HandleYellowCardWebhook ¶
func (ctrl *WebhookController) HandleYellowCardWebhook(c *fiber.Ctx) error
HandleYellowCardWebhook processes incoming webhooks from YellowCard. @Description Handle incoming webhooks from YellowCard payment service @Summary Process YellowCard Payment Webhook @Tags Webhooks @Accept json @Produce json @Param X-YC-Signature header string true "HMAC signature for verification" @Param body body yellowcard.WebhookEvent true "Webhook event data" @Success 200 {string} string "ok" @Failure 400 {object} fiber.Error "Invalid webhook payload" @Failure 401 {object} fiber.Error "Signature verification failed" @Failure 500 {object} fiber.Error "Failed to process webhook" @Router /api/v1/webhooks/yellowcard [post]
Source Files