Stop typing the same client into three systems

// ClioTokenStore.cs — refresh before expiry, never on 401
// Clio access tokens are short-lived; the refresh token is the asset.
// Persist it encrypted, and treat a failed refresh as an alert, not a retry.
public class ClioTokenStore(IDbContextFactory<AppDb> dbFactory, IHttpClientFactory http)
{
    private static readonly TimeSpan Skew = TimeSpan.FromMinutes(5);

    public async Task<string> GetAccessTokenAsync(int firmId, CancellationToken ct)
    {
        await using var db = await dbFactory.CreateDbContextAsync(ct);
        var creds = await db.OAuthCredentials
            .SingleAsync(c => c.FirmId == firmId && c.Provider == "clio", ct);

        if (DateTimeOffset.UtcNow < creds.ExpiresAt - Skew)
            return creds.AccessToken;

        var client = http.CreateClient("clio");
        var res = await client.PostAsync("/oauth/token", new FormUrlEncodedContent(new
            Dictionary<string, string>
            {
                ["grant_type"]    = "refresh_token",
                ["refresh_token"] = creds.RefreshToken,
                ["client_id"]     = _opts.ClientId,
                ["client_secret"] = _opts.ClientSecret,
            }), ct);

        // A dead refresh token means the firm must re-authorise — surface it,
        // don't silently swallow it into a retry loop.
        if (!res.IsSuccessStatusCode)
            throw new ReauthorisationRequiredException(firmId, "clio");

        var token = await res.Content.ReadFromJsonAsync<TokenResponse>(ct);
        creds.AccessToken  = token!.AccessToken;
        creds.RefreshToken = token.RefreshToken ?? creds.RefreshToken;
        creds.ExpiresAt    = DateTimeOffset.UtcNow.AddSeconds(token.ExpiresIn);
        await db.SaveChangesAsync(ct);

        return creds.AccessToken;
    }
}

// Program.cs — one recurring job per firm, per direction.
// Separate jobs mean one firm's rate limit never stalls another's sync.
RecurringJob.AddOrUpdate<ContactSyncJob>(
    recurringJobId: $"clio-to-lawmatics-{firm.Id}",
    job:            j => j.RunAsync(firm.Id, CancellationToken.None),
    cronExpression: Cron.Hourly,
    new RecurringJobOptions { TimeZone = firm.TimeZone });

// ContactSyncJob.cs — cursor-based, so a restart resumes instead of replaying
[DisableConcurrentExecution(timeoutInSeconds: 300)]
[AutomaticRetry(Attempts = 3, DelaysInSeconds = [60, 300, 900])]
public class ContactSyncJob(ClioClient clio, LawmaticsClient lawmatics, ISyncCursor cursor)
{
    public async Task RunAsync(int firmId, CancellationToken ct)
    {
        var since = await cursor.GetAsync(firmId, "contacts", ct);
        var page  = await clio.GetContactsUpdatedSinceAsync(firmId, since, ct);

        foreach (var contact in page.Items)
        {
            await lawmatics.UpsertContactAsync(firmId, contact, ct);
            // Advance per record, not per page — a mid-page failure resumes
            // exactly where it stopped rather than reprocessing the page.
            await cursor.SetAsync(firmId, "contacts", contact.UpdatedAt, ct);
        }
    }
}

// LawmaticsClient.cs — the rule that prevents duplicate client records.
// Never "create if search returns nothing" — two overlapping runs both search,
// both find nothing, and the firm ends up with two of every contact.
// Key on a stable external id instead.
public async Task UpsertContactAsync(int firmId, ClioContact src, CancellationToken ct)
{
    var externalKey = $"clio:{src.Id}";

    await using var db = await _dbFactory.CreateDbContextAsync(ct);
    var map = await db.ContactMappings
        .SingleOrDefaultAsync(m => m.FirmId == firmId && m.ExternalKey == externalKey, ct);

    if (map is not null)
    {
        await PatchAsync(map.LawmaticsId, src, ct);
        return;
    }

    var created = await CreateAsync(src, ct);

    // Unique index on (FirmId, ExternalKey) is what actually enforces this —
    // the check above is an optimisation, the constraint is the guarantee.
    db.ContactMappings.Add(new ContactMapping
    {
        FirmId      = firmId,
        ExternalKey = externalKey,
        LawmaticsId = created.Id,
    });
    await db.SaveChangesAsync(ct);
}