import 'package:relationship_saver/integrations/backend/models/backend_models.dart';

/// Domain-level backend boundary independent of HTTP transport.
abstract interface class BackendGateway {
  /// Authenticates user and returns active session.
  Future<AuthSession> signIn(SignInRequest request);

  /// Signs out current user.
  Future<void> signOut();

  /// Returns current user profile.
  Future<UserProfile> me();

  /// Pulls remote changes since optional cursor.
  Future<SyncPullResult> pullChanges({String? cursor, int limit = 200});

  /// Pushes local changes to backend.
  Future<SyncPushResult> pushChanges({
    required List<ChangeEnvelope> changes,
    String? cursor,
  });

  /// Fetches recommendation signals feed.
  Future<SignalsFeed> getSignalsFeed({
    String? cursor,
    DateTime? since,
    int limit = 50,
    Set<String>? personIds,
  });

  /// Acknowledges a signal action.
  Future<void> acknowledgeSignal({
    required String signalId,
    required SignalAction action,
    DateTime? at,
  });

  /// Initializes upload metadata and pre-signed URL.
  Future<UploadInitResult> initUpload({
    required UploadPurpose purpose,
    required String contentType,
    required int sizeBytes,
  });

  /// Resolves a temporary download URL.
  Future<DownloadUrl> getDownloadUrl({required String fileId});
}