OTSSignsOrchestrator/OTSSignsOrchestrator.Core/Services/IInvitationSetupService.cs

namespace OTSSignsOrchestrator.Core.Services;

/// <summary>
/// Orchestrates the complete Authentik invitation infrastructure setup for a customer.
/// Creates a group, enrollment flow with stages, role with invitation permissions,
/// and scoping policies so the customer admin can invite new users without OTS involvement.
/// </summary>
public interface IInvitationSetupService
{
    /// <summary>
    /// Sets up the full invitation infrastructure for a customer in Authentik:
    /// <list type="number">
    ///   <item>Create customer group (e.g. <c>customer-acme</c>).</item>
    ///   <item>Create invitation stage (invite-only, no anonymous enrollment).</item>
    ///   <item>Create enrollment flow with stages: Invitation → Prompt → UserWrite → UserLogin.</item>
    ///   <item>Bind expression policy to UserWrite stage to auto-assign users to the customer group.</item>
    ///   <item>Create invite-manager role with invitation CRUD permissions.</item>
    ///   <item>Assign role to customer group and bind scoping policy to flow.</item>
    /// </list>
    /// All operations are idempotent — safe to call multiple times for the same customer.
    /// </summary>
    /// <param name="customerAbbrev">Short customer identifier (e.g. "acme").</param>
    /// <param name="customerName">Human-readable customer name (e.g. "Acme Corp").</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Result describing what was created and the enrollment flow URL.</returns>
    Task<InvitationSetupResult> SetupCustomerInvitationAsync(
        string customerAbbrev,
        string customerName,
        CancellationToken ct = default);
}

/// <summary>
/// Result of the invitation infrastructure setup.
/// </summary>
public class InvitationSetupResult
{
    /// <summary>Whether the setup completed successfully.</summary>
    public bool Success { get; set; }

    /// <summary>Human-readable status message.</summary>
    public string Message { get; set; } = string.Empty;

    /// <summary>Name of the customer group created in Authentik.</summary>
    public string GroupName { get; set; } = string.Empty;

    /// <summary>Slug of the enrollment flow (used in invite links).</summary>
    public string EnrollmentFlowSlug { get; set; } = string.Empty;

    /// <summary>Name of the role created for invitation management.</summary>
    public string RoleName { get; set; } = string.Empty;

    /// <summary>
    /// Full URL to the Authentik user portal where the customer admin
    /// can manage invitations.
    /// </summary>
    public string? InvitationManagementUrl { get; set; }
}