<?php

namespace Technical\Integrations\Contracts;

use Carbon\CarbonInterface;
use Functional\Users\Models\User;
use Technical\Integrations\Models\Integration;

/**
 * Contrat que doit implémenter toute future couche fournisseur (functional/strava,
 * functional/garmin, ...) pour se brancher sur la couche technical/integrations,
 * sans que celle-ci n'ait besoin de connaître le fournisseur.
 */
interface ActivityProvider
{
    /** Clé unique du fournisseur, ex "strava" (sert d'identifiant dans le registre et la colonne "provider"). */
    public function key(): string;

    /** Libellé humain du fournisseur, ex "Strava". */
    public function label(): string;

    /** URL d'autorisation OAuth vers laquelle rediriger l'utilisateur pour connecter son compte. */
    public function connectUrl(User $user): string;

    /** Traite le retour du flow OAuth (callback) et crée/met à jour l'intégration correspondante. */
    public function handleCallback(User $user, array $payload): Integration;

    /** Récupère les activités du fournisseur pour une intégration donnée, depuis une date optionnelle. */
    public function fetchActivities(Integration $integration, ?CarbonInterface $since = null): iterable;
}
