feat(api): Refactor subscription model and add API placeholders

This commit introduces two main changes to improve the robustness of the user subscription feature and prepare for future API expansion.

**Forward-Compatible Subscription Triggers**

To prevent errors when a subscription trigger is deprecated or removed, the data model has been refactored to be forward-compatible.

- The OpenAPI specification now uses a `SubscriptionTriggerResponseItem` schema. This object returns the trigger's `value` and an optional `raw_value`.
- If a trigger stored in the database is no longer a valid API enum, its `value` is now set to 'unknown', and the original database string is preserved in `raw_value`. This ensures the API does not fail when encountering old data.
- The backend adapter and its tests have been updated to handle this new structure.

**API Endpoint Placeholders**

As part of the effort to split up a large pull request (#2041), this commit adds placeholder paths to `openapi.yaml` for future subscription management endpoints. These paths are for planning purposes and do not have functional implementations in this change:
- `/v1/users/me/subscriptions`
- `/v1/users/me/subscriptions/{subscription_id}`

**Other Changes**
- A specific error for unauthorized subscription creation attempts has been added.

Author: jcscottiii

lib/gcpspanner/spanneradapters/backend.go

@@ -1332,18 +1332,75 @@ func (s *Backend) GetIDFromFeatureKey(
 	return id, nil
 }
 
+func backendTriggersToSpannerTriggers(backendTriggers []backend.SubscriptionTriggerWritable) []string {
+	triggers := make([]string, 0, len(backendTriggers))
+	for _, trigger := range backendTriggers {
+		triggers = append(triggers, string(trigger))
+	}
+
+	return triggers
+}
+
+func attemptToStoreSubscriptionTrigger(t backend.SubscriptionTriggerWritable) backend.SubscriptionTriggerResponseValue {
+	ret := backend.SubscriptionTriggerResponseValue{}
+	err := ret.FromSubscriptionTriggerWritable(t)
+	if err != nil {
+		slog.Warn("unable to convert trigger from database. skipping", "err", err, "value", t)
+	}
+
+	return ret
+}
+
+func attemptToStoreSubscriptionTriggerUnknown() backend.SubscriptionTriggerResponseValue {
+	ret := backend.SubscriptionTriggerResponseValue{}
+	err := ret.FromEnumUnknown(backend.EnumUnknownValue)
+	if err != nil {
+		slog.Warn("unable to convert trigger from database. skipping", "err", err)
+	}
+
+	return ret
+}
+
+func spannerTriggersToBackendTriggers(spannerTriggers []string) []backend.SubscriptionTriggerResponseItem {
+	triggers := make([]backend.SubscriptionTriggerResponseItem, 0, len(spannerTriggers))
+	for _, trigger := range spannerTriggers {
+		input := backend.SubscriptionTriggerWritable(trigger)
+		switch input {
+		case backend.SubscriptionTriggerFeatureAnyBrowserImplementationComplete,
+			backend.SubscriptionTriggerFeatureBaselineLimitedToNewly,
+			backend.SubscriptionTriggerFeatureBaselineRegressionNewlyToLimited:
+			triggers = append(triggers, backend.SubscriptionTriggerResponseItem{
+				Value:    attemptToStoreSubscriptionTrigger(input),
+				RawValue: nil,
+			})
+		default:
+			value := trigger
+			triggers = append(triggers, backend.SubscriptionTriggerResponseItem{
+				Value:    attemptToStoreSubscriptionTriggerUnknown(),
+				RawValue: &value,
+			})
+		}
+	}
+
+	return triggers
+}
+
 func (s *Backend) CreateSavedSearchSubscription(ctx context.Context,
 	userID string, req backend.Subscription) (*backend.SubscriptionResponse, error) {
 	createReq := gcpspanner.CreateSavedSearchSubscriptionRequest{
 		UserID:        userID,
 		ChannelID:     req.ChannelId,
 		SavedSearchID: req.SavedSearchId,
-		Triggers:      req.Triggers,
+		Triggers:      backendTriggersToSpannerTriggers(req.Triggers),
 		Frequency:     string(req.Frequency),
 	}
 
 	id, err := s.client.CreateSavedSearchSubscription(ctx, createReq)
 	if err != nil {
+		if errors.Is(err, gcpspanner.ErrMissingRequiredRole) {
+			return nil, errors.Join(err, backendtypes.ErrUserNotAuthorizedForAction)
+		}
+
 		return nil, err
 	}
 
@@ -1415,7 +1472,9 @@ func (s *Backend) UpdateSavedSearchSubscription(ctx context.Context,
 	for _, field := range req.UpdateMask {
 		switch field {
 		case backend.UpdateSubscriptionRequestMaskTriggers:
-			updateReq.Triggers = gcpspanner.OptionallySet[[]string]{Value: *req.Triggers, IsSet: true}
+			updateReq.Triggers = gcpspanner.OptionallySet[[]string]{
+				Value: backendTriggersToSpannerTriggers(*req.Triggers),
+				IsSet: true}
 		case backend.UpdateSubscriptionRequestMaskFrequency:
 			updateReq.Frequency = gcpspanner.OptionallySet[string]{Value: string(*req.Frequency), IsSet: true}
 		}
@@ -1465,8 +1524,8 @@ func toBackendSubscription(sub *gcpspanner.SavedSearchSubscription) *backend.Sub
 		Id:            sub.ID,
 		ChannelId:     sub.ChannelID,
 		SavedSearchId: sub.SavedSearchID,
-		Triggers:      sub.Triggers,
-		Frequency:     backend.SubscriptionResponseFrequency(sub.Frequency),
+		Triggers:      spannerTriggersToBackendTriggers(sub.Triggers),
+		Frequency:     backend.SubscriptionFrequency(sub.Frequency),
 		CreatedAt:     sub.CreatedAt,
 		UpdatedAt:     sub.UpdatedAt,
 	}