Callbacks service docs updated

api/edge/bff/internal/server/callbacksimp/create.go

@@ -0,0 +1,47 @@
+package callbacksimp
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+
+	"github.com/tech/sendico/pkg/api/http/response"
+	"github.com/tech/sendico/pkg/model"
+	"github.com/tech/sendico/server/interface/api/sresponse"
+	mutil "github.com/tech/sendico/server/internal/mutil/param"
+	"go.uber.org/zap"
+)
+
+func (a *CallbacksAPI) create(r *http.Request, account *model.Account, accessToken *sresponse.TokenData) http.HandlerFunc {
+	organizationRef, err := a.Oph.GetRef(r)
+	if err != nil {
+		a.Logger.Warn("Failed to parse organization reference", zap.Error(err), mutil.PLog(a.Oph, r))
+		return response.BadReference(a.Logger, a.Name(), a.Oph.Name(), a.Oph.GetID(r), err)
+	}
+
+	var callback model.Callback
+	if err := json.NewDecoder(r.Body).Decode(&callback); err != nil {
+		a.Logger.Warn("Failed to decode callback payload", zap.Error(err))
+		return response.BadPayload(a.Logger, a.Name(), err)
+	}
+
+	mutation, err := a.normalizeAndPrepare(r.Context(), &callback, organizationRef, "", true)
+	if err != nil {
+		return response.Auto(a.Logger, a.Name(), err)
+	}
+
+	if _, err := a.tf.CreateTransaction().Execute(r.Context(), func(ctx context.Context) (any, error) {
+		if err := a.DB.Create(ctx, *account.GetID(), organizationRef, &callback); err != nil {
+			return nil, err
+		}
+		if err := a.applySigningSecretMutation(ctx, *account.GetID(), *callback.GetID(), mutation); err != nil {
+			return nil, err
+		}
+		return nil, nil
+	}); err != nil {
+		a.Logger.Warn("Failed to create callback transaction", zap.Error(err))
+		return response.Auto(a.Logger, a.Name(), err)
+	}
+
+	return a.callbackResponse(&callback, accessToken, mutation.Generated, true)
+}

api/edge/bff/internal/server/callbacksimp/rotate.go

@@ -2,7 +2,7 @@ package callbacksimp
 
 import (
 	"context"
-	"encoding/json"
+	"errors"
 	"net/http"
 	"net/url"
 	"strings"
@@ -16,68 +16,10 @@ import (
 	"go.uber.org/zap"
 )
 
-type callbackWriteResponse struct {
-	AccessToken            sresponse.TokenData `json:"accessToken"`
-	Callbacks              []model.Callback    `json:"callbacks"`
-	GeneratedSigningSecret string              `json:"generatedSigningSecret,omitempty"`
-}
-
-func (a *CallbacksAPI) create(r *http.Request, account *model.Account, accessToken *sresponse.TokenData) http.HandlerFunc {
-	organizationRef, err := a.Oph.GetRef(r)
-	if err != nil {
-		a.Logger.Warn("Failed to parse organization reference", zap.Error(err), mutil.PLog(a.Oph, r))
-		return response.BadReference(a.Logger, a.Name(), a.Oph.Name(), a.Oph.GetID(r), err)
-	}
-
-	var callback model.Callback
-	if err := json.NewDecoder(r.Body).Decode(&callback); err != nil {
-		a.Logger.Warn("Failed to decode callback payload", zap.Error(err))
-		return response.BadPayload(a.Logger, a.Name(), err)
-	}
-
-	generatedSecret, err := a.normalizeAndPrepare(r.Context(), &callback, organizationRef, true)
-	if err != nil {
-		return response.Auto(a.Logger, a.Name(), err)
-	}
-
-	if err := a.DB.Create(r.Context(), *account.GetID(), organizationRef, &callback); err != nil {
-		a.Logger.Warn("Failed to create callback", zap.Error(err))
-		return response.Auto(a.Logger, a.Name(), err)
-	}
-
-	return a.callbackResponse(&callback, accessToken, generatedSecret, true)
-}
-
-func (a *CallbacksAPI) update(r *http.Request, account *model.Account, accessToken *sresponse.TokenData) http.HandlerFunc {
-	var input model.Callback
-	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
-		a.Logger.Warn("Failed to decode callback payload", zap.Error(err))
-		return response.BadPayload(a.Logger, a.Name(), err)
-	}
-
-	callbackRef := *input.GetID()
-	if callbackRef.IsZero() {
-		return response.Auto(a.Logger, a.Name(), merrors.InvalidArgument("callback id is required", "id"))
-	}
-
-	var existing model.Callback
-	if err := a.db.Get(r.Context(), *account.GetID(), callbackRef, &existing); err != nil {
-		a.Logger.Warn("Failed to fetch callback before update", zap.Error(err))
-		return response.Auto(a.Logger, a.Name(), err)
-	}
-
-	mergeCallbackMutable(&existing, &input)
-	generatedSecret, err := a.normalizeAndPrepare(r.Context(), &existing, existing.OrganizationRef, true)
-	if err != nil {
-		return response.Auto(a.Logger, a.Name(), err)
-	}
-
-	if err := a.DB.Update(r.Context(), *account.GetID(), &existing); err != nil {
-		a.Logger.Warn("Failed to update callback", zap.Error(err))
-		return response.Auto(a.Logger, a.Name(), err)
-	}
-
-	return a.callbackResponse(&existing, accessToken, generatedSecret, false)
+type signingSecretMutation struct {
+	SetSecretRef string
+	Clear        bool
+	Generated    string
 }
 
 func (a *CallbacksAPI) rotateSecret(r *http.Request, account *model.Account, accessToken *sresponse.TokenData) http.HandlerFunc {
@@ -102,10 +44,8 @@ func (a *CallbacksAPI) rotateSecret(r *http.Request, account *model.Account, acc
 		a.Logger.Warn("Failed to rotate callback signing secret", zap.Error(err))
 		return response.Auto(a.Logger, a.Name(), err)
 	}
-	callback.RetryPolicy.SecretRef = secretRef
-
-	if err := a.DB.Update(r.Context(), *account.GetID(), &callback); err != nil {
-		a.Logger.Warn("Failed to persist rotated callback secret reference", zap.Error(err))
+	if err := a.db.SetSigningSecretRef(r.Context(), *account.GetID(), callbackRef, secretRef); err != nil {
+		a.Logger.Warn("Failed to persist rotated callback signing secret reference", zap.Error(err))
 		return response.Auto(a.Logger, a.Name(), err)
 	}
 
@@ -116,29 +56,25 @@ func (a *CallbacksAPI) normalizeAndPrepare(
 	ctx context.Context,
 	callback *model.Callback,
 	organizationRef bson.ObjectID,
+	existingSecretRef string,
 	allowSecretGeneration bool,
-) (string, error) {
+) (signingSecretMutation, error) {
 	if callback == nil {
-		return "", merrors.InvalidArgument("callback payload is required")
+		return signingSecretMutation{}, merrors.InvalidArgument("callback payload is required")
 	}
 	if organizationRef.IsZero() {
-		return "", merrors.InvalidArgument("organization reference is required", "organizationRef")
+		return signingSecretMutation{}, merrors.InvalidArgument("organization reference is required", "organizationRef")
 	}
 
-	callback.SetOrganizationRef(organizationRef)
 	callback.Name = strings.TrimSpace(callback.Name)
 	callback.Description = trimDescription(callback.Description)
-	callback.ClientID = strings.TrimSpace(callback.ClientID)
-	if callback.ClientID == "" {
-		callback.ClientID = organizationRef.Hex()
-	}
 
 	callback.URL = strings.TrimSpace(callback.URL)
 	if callback.URL == "" {
-		return "", merrors.InvalidArgument("url is required", "url")
+		return signingSecretMutation{}, merrors.InvalidArgument("url is required", "url")
 	}
 	if err := validateCallbackURL(callback.URL); err != nil {
-		return "", err
+		return signingSecretMutation{}, err
 	}
 	if callback.Name == "" {
 		callback.Name = callback.URL
@@ -146,15 +82,15 @@ func (a *CallbacksAPI) normalizeAndPrepare(
 
 	status, err := normalizeStatus(callback.Status, a.config.DefaultStatus)
 	if err != nil {
-		return "", err
+		return signingSecretMutation{}, err
 	}
 	callback.Status = status
 	callback.EventTypes = normalizeEventTypes(callback.EventTypes, a.config.DefaultEventTypes)
 
-	callback.RetryPolicy.MinDelayMS = defaultInt(callback.RetryPolicy.MinDelayMS, defaultRetryMinDelayMS)
-	callback.RetryPolicy.MaxDelayMS = defaultInt(callback.RetryPolicy.MaxDelayMS, defaultRetryMaxDelayMS)
-	if callback.RetryPolicy.MaxDelayMS < callback.RetryPolicy.MinDelayMS {
-		callback.RetryPolicy.MaxDelayMS = callback.RetryPolicy.MinDelayMS
+	callback.RetryPolicy.Backoff.MinDelayMS = defaultInt(callback.RetryPolicy.Backoff.MinDelayMS, defaultRetryMinDelayMS)
+	callback.RetryPolicy.Backoff.MaxDelayMS = defaultInt(callback.RetryPolicy.Backoff.MaxDelayMS, defaultRetryMaxDelayMS)
+	if callback.RetryPolicy.Backoff.MaxDelayMS < callback.RetryPolicy.Backoff.MinDelayMS {
+		callback.RetryPolicy.Backoff.MaxDelayMS = callback.RetryPolicy.Backoff.MinDelayMS
 	}
 	callback.RetryPolicy.MaxAttempts = defaultInt(callback.RetryPolicy.MaxAttempts, defaultRetryMaxAttempts)
 	callback.RetryPolicy.RequestTimeoutMS = defaultInt(callback.RetryPolicy.RequestTimeoutMS, defaultRetryRequestTimeoutMS)
@@ -162,36 +98,55 @@ func (a *CallbacksAPI) normalizeAndPrepare(
 
 	mode, err := normalizeSigningMode(callback.RetryPolicy.SigningMode)
 	if err != nil {
-		return "", err
+		return signingSecretMutation{}, err
 	}
 	callback.RetryPolicy.SigningMode = mode
 
-	callback.RetryPolicy.SecretRef = strings.TrimSpace(callback.RetryPolicy.SecretRef)
+	existingSecretRef = strings.TrimSpace(existingSecretRef)
 	switch callback.RetryPolicy.SigningMode {
 	case model.CallbackSigningModeNone:
-		callback.RetryPolicy.SecretRef = ""
-		return "", nil
+		return signingSecretMutation{Clear: existingSecretRef != ""}, nil
 	case model.CallbackSigningModeHMACSHA256:
-		if callback.RetryPolicy.SecretRef != "" {
-			return "", nil
+		if existingSecretRef != "" {
+			return signingSecretMutation{SetSecretRef: existingSecretRef}, nil
 		}
 		if !allowSecretGeneration {
-			return "", merrors.InvalidArgument("secretRef is required for hmac_sha256 callbacks", "retryPolicy.secretRef")
+			return signingSecretMutation{}, merrors.InvalidArgument("signing secret is required for hmac_sha256 callbacks", "retryPolicy.signingMode")
 		}
 		if callback.GetID().IsZero() {
 			callback.SetID(bson.NewObjectID())
 		}
 		secretRef, generatedSecret, err := a.secrets.Provision(ctx, organizationRef, *callback.GetID())
 		if err != nil {
-			return "", err
+			return signingSecretMutation{}, err
 		}
-		callback.RetryPolicy.SecretRef = secretRef
-		return generatedSecret, nil
+		return signingSecretMutation{SetSecretRef: secretRef, Generated: generatedSecret}, nil
 	default:
-		return "", merrors.InvalidArgument("unsupported signing mode", "retryPolicy.signingMode")
+		return signingSecretMutation{}, merrors.InvalidArgument("unsupported signing mode", "retryPolicy.signingMode")
 	}
 }
 
+func (a *CallbacksAPI) applySigningSecretMutation(
+	ctx context.Context,
+	accountRef,
+	callbackRef bson.ObjectID,
+	mutation signingSecretMutation,
+) error {
+	if callbackRef.IsZero() {
+		return merrors.InvalidArgument("callback reference is required", "callbackRef")
+	}
+	if strings.TrimSpace(mutation.SetSecretRef) != "" {
+		return a.db.SetSigningSecretRef(ctx, accountRef, callbackRef, mutation.SetSecretRef)
+	}
+	if mutation.Clear {
+		err := a.db.ClearSigningSecretRef(ctx, accountRef, callbackRef)
+		if err != nil && !errors.Is(err, merrors.ErrNoData) {
+			return err
+		}
+	}
+	return nil
+}
+
 func (a *CallbacksAPI) callbackResponse(
 	callback *model.Callback,
 	accessToken *sresponse.TokenData,
@@ -202,15 +157,7 @@ func (a *CallbacksAPI) callbackResponse(
 		return response.Internal(a.Logger, a.Name(), merrors.Internal("failed to build callback response"))
 	}
 
-	resp := callbackWriteResponse{
-		AccessToken:            *accessToken,
-		Callbacks:              []model.Callback{*callback},
-		GeneratedSigningSecret: generatedSecret,
-	}
-	if created {
-		return response.Created(a.Logger, resp)
-	}
-	return response.Ok(a.Logger, resp)
+	return sresponse.Callback(a.Logger, callback, accessToken, generatedSecret, created)
 }
 
 func normalizeStatus(raw, fallback model.CallbackStatus) (model.CallbackStatus, error) {
@@ -286,16 +233,17 @@ func normalizeHeaders(headers map[string]string) map[string]string {
 }
 
 func mergeCallbackMutable(dst, src *model.Callback) {
+	dst.OrganizationRef = src.OrganizationRef
 	dst.Describable = src.Describable
-	dst.ClientID = src.ClientID
 	dst.Status = src.Status
 	dst.URL = src.URL
 	dst.EventTypes = append([]string(nil), src.EventTypes...)
 	dst.RetryPolicy = model.CallbackRetryPolicy{
-		MinDelayMS:       src.RetryPolicy.MinDelayMS,
-		MaxDelayMS:       src.RetryPolicy.MaxDelayMS,
+		Backoff: model.CallbackBackoff{
+			MinDelayMS: src.RetryPolicy.Backoff.MinDelayMS,
+			MaxDelayMS: src.RetryPolicy.Backoff.MaxDelayMS,
+		},
 		SigningMode:      src.RetryPolicy.SigningMode,
-		SecretRef:        src.RetryPolicy.SecretRef,
 		Headers:          normalizeHeaders(src.RetryPolicy.Headers),
 		MaxAttempts:      src.RetryPolicy.MaxAttempts,
 		RequestTimeoutMS: src.RetryPolicy.RequestTimeoutMS,

api/edge/bff/internal/server/callbacksimp/secrets.go

@@ -81,7 +81,7 @@ func newSigningSecretManager(logger mlogger.Logger, cfg callbacksConfig) (signin
 	}
 
 	if isVaultConfigEmpty(cfg.Vault) {
-		manager.logger.Warn("Callbacks Vault config is not set; secret generation requires explicit secretRef in payloads")
+		manager.logger.Warn("Callbacks Vault config is not set; hmac signing secret generation is disabled")
 		ensureSigningSecretMetrics()
 		return manager, nil
 	}

api/edge/bff/internal/server/callbacksimp/service.go

@@ -5,6 +5,7 @@ import (
 
 	api "github.com/tech/sendico/pkg/api/http"
 	"github.com/tech/sendico/pkg/db/callbacks"
+	"github.com/tech/sendico/pkg/db/transaction"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/model"
 	"github.com/tech/sendico/pkg/mservice"
@@ -16,6 +17,7 @@ import (
 type CallbacksAPI struct {
 	papitemplate.ProtectedAPI[model.Callback]
 	db      callbacks.DB
+	tf      transaction.Factory
 	secrets signingSecretManager
 	config  callbacksConfig
 }
@@ -35,6 +37,7 @@ func CreateAPI(apiCtx eapi.API) (*CallbacksAPI, error) {
 
 	res := &CallbacksAPI{
 		config: newCallbacksConfig(apiCtx.Config().Callbacks),
+		tf:     apiCtx.DBFactory().TransactionFactory(),
 	}
 
 	p, err := papitemplate.CreateAPI(apiCtx, dbFactory, mservice.Organizations, mservice.Callbacks)

api/edge/bff/internal/server/callbacksimp/update.go

@@ -0,0 +1,59 @@
+package callbacksimp
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/tech/sendico/pkg/api/http/response"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/model"
+	"github.com/tech/sendico/server/interface/api/sresponse"
+	"go.uber.org/zap"
+)
+
+func (a *CallbacksAPI) update(r *http.Request, account *model.Account, accessToken *sresponse.TokenData) http.HandlerFunc {
+	var input model.Callback
+	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
+		a.Logger.Warn("Failed to decode callback payload", zap.Error(err))
+		return response.BadPayload(a.Logger, a.Name(), err)
+	}
+
+	callbackRef := *input.GetID()
+	if callbackRef.IsZero() {
+		return response.Auto(a.Logger, a.Name(), merrors.InvalidArgument("callback ref is required", "id"))
+	}
+
+	var existing model.Callback
+	if err := a.db.Get(r.Context(), *account.GetID(), callbackRef, &existing); err != nil {
+		a.Logger.Warn("Failed to fetch callback before update", zap.Error(err))
+		return response.Auto(a.Logger, a.Name(), err)
+	}
+	existingSecretRef, err := a.db.GetSigningSecretRef(r.Context(), *account.GetID(), callbackRef)
+	if err != nil && !errors.Is(err, merrors.ErrNoData) {
+		a.Logger.Warn("Failed to fetch callback signing secret metadata", zap.Error(err))
+		return response.Auto(a.Logger, a.Name(), err)
+	}
+
+	mergeCallbackMutable(&existing, &input)
+	mutation, err := a.normalizeAndPrepare(r.Context(), &existing, existing.OrganizationRef, existingSecretRef, true)
+	if err != nil {
+		return response.Auto(a.Logger, a.Name(), err)
+	}
+
+	if _, err := a.tf.CreateTransaction().Execute(r.Context(), func(ctx context.Context) (any, error) {
+		if err := a.DB.Update(ctx, *account.GetID(), &existing); err != nil {
+			return nil, err
+		}
+		if err := a.applySigningSecretMutation(ctx, *account.GetID(), callbackRef, mutation); err != nil {
+			return nil, err
+		}
+		return nil, nil
+	}); err != nil {
+		a.Logger.Warn("Failed to update callback transaction", zap.Error(err))
+		return response.Auto(a.Logger, a.Name(), err)
+	}
+
+	return a.callbackResponse(&existing, accessToken, mutation.Generated, false)
+}