feat(skus): add set-linking-limit support endpoint and CLI command

Adds a support operator endpoint and CLI command to set the per-order
TLV2 credential batch limit (max_active_batches_tlv2_creds), enabling
operators to increase the linked device cap for individual orders.

Backend:
- PATCH /v1/orders/{orderID}/credentials/batches/limit (supportMwr)
- SetMaxActiveBatches repo method on order_items
- SetLinkingLimit service method (validates paid + TLV2, runs in tx)
- SetLinkingLimitReq model type

CLI:
- `bat-go skus set-linking-limit` with --order-id or --email lookup,
  --max, optional --item-id, --private-key, and subscriptions service
  flags when using email; shows current limit/active count before
  confirming

Author: Sneagan

services/skus/controllers.go

@@ -125,6 +125,7 @@ func Router(
 		cr.Method(http.MethodGet, "/batches/count", metricsMwr("CountBatches", authMwr(handlers.AppHandler(credh.CountBatches))))
 		cr.Method(http.MethodGet, "/batches", metricsMwr("ListActiveBatches", supportMwr(handlers.AppHandler(credh.ListActiveBatches))))
 		cr.Method(http.MethodDelete, "/batches", metricsMwr("DeleteBatches", supportMwr(handlers.AppHandler(credh.DeleteBatches))))
+		cr.Method(http.MethodPatch, "/batches/limit", metricsMwr("SetLinkingLimit", supportMwr(handlers.AppHandler(credh.SetLinkingLimit))))
 
 		// Handle the old endpoint while the new is being rolled out:
 		// - true: the handler uses itemID as the request id, which is the old mode;

services/skus/datastore.go

@@ -114,6 +114,7 @@ type orderItemStore interface {
 	Get(ctx context.Context, dbi sqlx.QueryerContext, id uuid.UUID) (*model.OrderItem, error)
 	FindByOrderID(ctx context.Context, dbi sqlx.QueryerContext, orderID uuid.UUID) ([]model.OrderItem, error)
 	InsertMany(ctx context.Context, dbi sqlx.ExtContext, items ...model.OrderItem) ([]model.OrderItem, error)
+	SetMaxActiveBatches(ctx context.Context, dbi sqlx.ExecerContext, id uuid.UUID, max int) error
 }
 
 type orderPayHistoryStore interface {

services/skus/handler/cred.go

@@ -19,6 +19,7 @@ type tlv2Svc interface {
 	UniqBatches(ctx context.Context, orderID, itemID uuid.UUID) (int, int, error)
 	ListActiveBatches(ctx context.Context, orderID, itemID uuid.UUID) ([]model.TLV2ActiveBatch, error)
 	DeleteBatches(ctx context.Context, orderID, itemID uuid.UUID, seats int) error
+	SetLinkingLimit(ctx context.Context, orderID, itemID uuid.UUID, max int) error
 }
 
 type Cred struct {
@@ -187,3 +188,65 @@ func (h *Cred) DeleteBatches(w http.ResponseWriter, r *http.Request) *handlers.A
 
 	return handlers.RenderContent(ctx, struct{}{}, w, http.StatusOK)
 }
+
+// SetLinkingLimit updates the maximum number of active TLV2 credential batches (linked devices)
+// for an order. An optional item_id in the request body scopes the change to a specific item.
+//
+// PATCH /v1/orders/{orderID}/credentials/batches/limit
+func (h *Cred) SetLinkingLimit(w http.ResponseWriter, r *http.Request) *handlers.AppError {
+	ctx := r.Context()
+
+	orderID, err := uuid.FromString(chi.URLParamFromCtx(ctx, "orderID"))
+	if err != nil {
+		return handlers.ValidationError("request", map[string]interface{}{"orderID": err.Error()})
+	}
+
+	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, reqBodyLimit10MB))
+	if err != nil {
+		return handlers.WrapError(err, "failed to read request body", http.StatusBadRequest)
+	}
+
+	var req model.SetLinkingLimitReq
+	if err := json.Unmarshal(body, &req); err != nil {
+		return handlers.WrapError(err, "failed to parse request body", http.StatusBadRequest)
+	}
+
+	if req.Max <= 0 {
+		return handlers.ValidationError("request", map[string]interface{}{"max": "must be a positive integer"})
+	}
+
+	itemID := uuid.Nil
+	if req.ItemID != "" {
+		itemID, err = uuid.FromString(req.ItemID)
+		if err != nil {
+			return handlers.ValidationError("request", map[string]interface{}{"item_id": err.Error()})
+		}
+	}
+
+	if err := h.tlv2.SetLinkingLimit(ctx, orderID, itemID, req.Max); err != nil {
+		lg := logging.Logger(ctx, "skus").With().Str("func", "SetLinkingLimit").Logger()
+
+		switch {
+		case errors.Is(err, context.Canceled):
+			return handlers.WrapError(err, "client ended request", model.StatusClientClosedConn)
+
+		case errors.Is(err, context.DeadlineExceeded):
+			return handlers.WrapError(err, "request timed out", http.StatusGatewayTimeout)
+
+		case errors.Is(err, model.ErrOrderNotFound), errors.Is(err, model.ErrInvalidOrderNoItems), errors.Is(err, model.ErrOrderItemNotFound):
+			return handlers.WrapError(err, "order not found", http.StatusNotFound)
+
+		case errors.Is(err, model.ErrOrderNotPaid):
+			return handlers.WrapError(err, "order not paid", http.StatusPaymentRequired)
+
+		case errors.Is(err, model.ErrUnsupportedCredType):
+			return handlers.WrapError(err, "credential type not supported", http.StatusBadRequest)
+
+		default:
+			lg.Error().Err(err).Msg("failed to set linking limit")
+			return handlers.WrapError(model.ErrSomethingWentWrong, "something went wrong", http.StatusInternalServerError)
+		}
+	}
+
+	return handlers.RenderContent(ctx, struct{}{}, w, http.StatusOK)
+}

services/skus/handler/cred_test.go

@@ -24,6 +24,7 @@ type mockTLV2Svc struct {
 	FnUniqBatches       func(ctx context.Context, orderID, itemID uuid.UUID) (int, int, error)
 	FnListActiveBatches func(ctx context.Context, orderID, itemID uuid.UUID) ([]model.TLV2ActiveBatch, error)
 	FnDeleteBatches     func(ctx context.Context, orderID, itemID uuid.UUID, seats int) error
+	FnSetLinkingLimit   func(ctx context.Context, orderID, itemID uuid.UUID, max int) error
 }
 
 func (s *mockTLV2Svc) UniqBatches(ctx context.Context, orderID, itemID uuid.UUID) (int, int, error) {
@@ -50,6 +51,14 @@ func (s *mockTLV2Svc) DeleteBatches(ctx context.Context, orderID, itemID uuid.UU
 	return s.FnDeleteBatches(ctx, orderID, itemID, seats)
 }
 
+func (s *mockTLV2Svc) SetLinkingLimit(ctx context.Context, orderID, itemID uuid.UUID, max int) error {
+	if s.FnSetLinkingLimit == nil {
+		return nil
+	}
+
+	return s.FnSetLinkingLimit(ctx, orderID, itemID, max)
+}
+
 func TestCred_CountBatches(t *testing.T) {
 	type tcGiven struct {
 		ctx context.Context

services/skus/model/model.go

@@ -779,6 +779,12 @@ type DeleteBatchesReq struct {
 	ItemID string `json:"item_id"`
 }
 
+// SetLinkingLimitReq is the request body for the set linking limit endpoint.
+type SetLinkingLimitReq struct {
+	Max    int    `json:"max"`
+	ItemID string `json:"item_id,omitempty"`
+}
+
 // ReceiptRequest represents a receipt submitted by a mobile or web client.
 type ReceiptRequest struct {
 	Type           Vendor `json:"type" validate:"required,oneof=ios android"`

services/skus/service.go

@@ -1374,6 +1374,48 @@ func (s *Service) deleteBatchesTx(ctx context.Context, dbi sqlx.ExecerContext, o
 	return s.tlv2Repo.DeleteOutboxByRequestIDs(ctx, dbi, orderID, requestIDs)
 }
 
+// SetLinkingLimit sets the maximum number of active TLV2 credential batches (linked devices)
+// allowed for an order item. When itemID is uuid.Nil, the first item in the order is used.
+func (s *Service) SetLinkingLimit(ctx context.Context, orderID, itemID uuid.UUID, max int) error {
+	ord, err := s.getOrderFullTx(ctx, s.Datastore.RawDB(), orderID)
+	if err != nil {
+		return err
+	}
+
+	if !ord.IsPaid() {
+		return model.ErrOrderNotPaid
+	}
+
+	if len(ord.Items) == 0 {
+		return model.ErrInvalidOrderNoItems
+	}
+
+	item := &ord.Items[0]
+	if !uuid.Equal(itemID, uuid.Nil) {
+		var ok bool
+		item, ok = ord.HasItem(itemID)
+		if !ok {
+			return model.ErrOrderItemNotFound
+		}
+	}
+
+	if !item.IsCredTLV2() {
+		return model.ErrUnsupportedCredType
+	}
+
+	tx, err := s.Datastore.RawDB().BeginTxx(ctx, nil)
+	if err != nil {
+		return err
+	}
+	defer s.Datastore.RollbackTx(tx)
+
+	if err := s.orderItemRepo.SetMaxActiveBatches(ctx, tx, item.ID, max); err != nil {
+		return err
+	}
+
+	return tx.Commit()
+}
+
 // isValidBatchReq validates that the order contains TLV2 credentials. When itemID is
 // non-nil it checks that the specific item exists and is TLV2; otherwise it requires
 // at least one TLV2 item in the order.

services/skus/storage/repository/mock.go

@@ -152,9 +152,10 @@ func (r *MockOrder) IncrementNumPayFailed(ctx context.Context, dbi sqlx.ExecerCo
 }
 
 type MockOrderItem struct {
-	FnGet           func(ctx context.Context, dbi sqlx.QueryerContext, id uuid.UUID) (*model.OrderItem, error)
-	FnFindByOrderID func(ctx context.Context, dbi sqlx.QueryerContext, orderID uuid.UUID) ([]model.OrderItem, error)
-	FnInsertMany    func(ctx context.Context, dbi sqlx.ExtContext, items ...model.OrderItem) ([]model.OrderItem, error)
+	FnGet                  func(ctx context.Context, dbi sqlx.QueryerContext, id uuid.UUID) (*model.OrderItem, error)
+	FnFindByOrderID        func(ctx context.Context, dbi sqlx.QueryerContext, orderID uuid.UUID) ([]model.OrderItem, error)
+	FnInsertMany           func(ctx context.Context, dbi sqlx.ExtContext, items ...model.OrderItem) ([]model.OrderItem, error)
+	FnSetMaxActiveBatches  func(ctx context.Context, dbi sqlx.ExecerContext, id uuid.UUID, max int) error
 }
 
 func (r *MockOrderItem) Get(ctx context.Context, dbi sqlx.QueryerContext, id uuid.UUID) (*model.OrderItem, error) {
@@ -181,6 +182,14 @@ func (r *MockOrderItem) InsertMany(ctx context.Context, dbi sqlx.ExtContext, ite
 	return r.FnInsertMany(ctx, dbi, items...)
 }
 
+func (r *MockOrderItem) SetMaxActiveBatches(ctx context.Context, dbi sqlx.ExecerContext, id uuid.UUID, max int) error {
+	if r.FnSetMaxActiveBatches == nil {
+		return nil
+	}
+
+	return r.FnSetMaxActiveBatches(ctx, dbi, id, max)
+}
+
 type MockIssuer struct {
 	FnGetByMerchID func(ctx context.Context, dbi sqlx.QueryerContext, merchID string) (*model.Issuer, error)
 	FnGetByPubKey  func(ctx context.Context, dbi sqlx.QueryerContext, pubKey string) (*model.Issuer, error)

services/skus/storage/repository/order_item.go

@@ -53,6 +53,17 @@ func (r *OrderItem) FindByOrderID(ctx context.Context, dbi sqlx.QueryerContext,
 	return result, nil
 }
 
+// SetMaxActiveBatches updates the max_active_batches_tlv2_creds column for the given order item.
+func (r *OrderItem) SetMaxActiveBatches(ctx context.Context, dbi sqlx.ExecerContext, id uuid.UUID, max int) error {
+	const q = `UPDATE order_items SET max_active_batches_tlv2_creds = $2 WHERE id = $1`
+
+	if _, err := dbi.ExecContext(ctx, q, id, max); err != nil {
+		return err
+	}
+
+	return nil
+}
+
 // InsertMany inserts given items and returns the result.
 func (r *OrderItem) InsertMany(ctx context.Context, dbi sqlx.ExtContext, items ...model.OrderItem) ([]model.OrderItem, error) {
 	if len(items) == 0 {