INTER-1491: Migrate SDK to APIv4

[erayaydin]

This PR upgrades the Server SDK to the Server API v4. It removes Server APIv3 specific behavior and aligns the SDK with the new events format shared by Server API and Webhooks.
INTER-1491

❓ Why?

• Server API v3 is deprecated on Oct 31, 2025 and will be sunset on Oct 31, 2026.
• v4 standardizes responses (no data/products/result nesting), switches to Bearer auth, unifies Webhooks & Server API event formats, and deprecates /visitors in favor of /v4/events.

⚙️ What Changed?

• Project name changed from FingerprintPro.ServerSdk to Fingerprint.ServerSdk.
• Removed ./bin/swagger-codegen-cli.jar and updated generate.sh to download openapi-generator-cli.jar (if it doesn't exist).
• Bearer auth implemented: Removed Configuration class and implemented Client/BearerToken.cs, Client/TokenBase.cs, Client/TokenContainer`1.cs, Client/TokenProvider`1.cs, RateLimitProvider`1.cs.
• Adds Generic Host extensions and DI support for JsonSerializationOptions.
• <Operation>Async and <Operation>AsyncOrDefault methods to interact with the Server API.
• Callback and hook support for the FingerprintApiEvents.

⚠️ Breaking Changes

• All using directives and type references must change from
  FingerprintPro.ServerSdk to Fingerprint.ServerSdk.
• If you reference project/solution files (or Docker images by name),
  update them to the new names.
• FingerprintApi initialization changed. Prefer Generic Host + ConfigureApi instead of ad-hoc static configuration.
• Auth changed. Use SECRET_API_KEY via DI (see Migration Guide).
• Code that referenced requestId must switch to eventId (e.g., GetEventAsync now expects eventId).
• Removed .toJson() methods in models.

📦 Migration Guide (SDK Consumers)

1) Change package reference to new name

Replace FingerprintPro.ServerSdk package references to new name.

- <PackageReference Include="FingerprintPro.ServerSdk" Version="7.9.0" />
+ <PackageReference Include="Fingerprint.ServerSdk" Version="8.0.0" />

2) Update package/namespace imports

Replace namespace imports: using FingerprintPro.ServerSdk; -> using Fingerprint.ServerSdk;

- using FingerprintPro.ServerSdk;
- using FingerprintPro.ServerSdk.Api;
- using FingerprintPro.ServerSdk.Model;
+ using Fingerprint.ServerSdk;
+ using Fingerprint.ServerSdk.Api;
+ using Fingerprint.ServerSdk.Model;

3) Switch to DI setup Generic Host (Auth and Region)

Before (v7.x, implicit apiKey usage):

...
var configuration = new Configuration("SECRET_API_KEY");
configuration.Region = Region.Eu;
var api = new FingerprintApi(configuration);
var getEvent = await api.GetEventAsync(requestId);

After (v8.x, Bearer + Generic Host):

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Fingerprint.ServerSdk.Api;
using Fingerprint.ServerSdk.Client;

...

var host = Host.CreateDefaultBuilder(args)
  .ConfigureApi((context, services, options) =>
  {
      options.Region = Region.Eu;
      var token = new BearerToken("SECRET_API_KEY");
      options.AddTokens(token);
  })
  .Build();

var api = host.Services.GetRequiredService<IFingerprintApi>();
var getEvent = await api.GetEventAsync(eventId);

4) Replace request IDs with event IDs

const string id = "";

- await api.GetEventAsync(requestId: id);
+ await api.GetEventAsync(eventId: id);

5) Typed API responses

FingerprintApi methods now return a typed response wrapper that models both success and error outcomes.
You can check the outcome with the boolean properties and then safely access the typed payload via helpers:

• Booleans: IsOk, IsNotFound, IsBadRequest, IsForbidden, IsInternalServerError, ...
• Accessors: .Ok(), .NotFound(), .BadRequest(), .Forbidden(), .InternalServerError(), ...
• Try-pattern: .TryOk(out var ok), .TryNotFound(out var err), .TryBadRequest(out var err), ...
• Raw details (if needed): .RawContent, .StatusCode

- var eventsFound = api.SearchEvents(20, paginationKey: "1740815825085", bot: "bad");
+ var searchResponse = await api.SearchEventsAsync(limit: 50, paginationKey: "1740815825085", bot: "bad");
+ var eventsFound = searchResponse.Ok();
+ // var isOk = searchResponse.IsOk;
+ // var isOk = searchResponse.TryOk(out var eventsFound);

6) Remove Tag usage in EventUpdate, use Dictionary<string, object>

- var tag = new Tag
+ var tag = new Dictionary<string, object>
{
    ["key"] = "value"
};

7) Use Tags key instead of Tag when creating EventUpdate model

var body = new EventsUpdateRequest()
{
    Suspect = false,
-   Tag = tag,
+   Tags = tag,
    LinkedId = "<linked_id>"
};

8) Use new JsonConverters instead of .toJson() method

Removed .toJson() method from the models. Use new special JsonConverters for models when converting models to JSON.

- events.toJson()
+ JsonSerializer.Serialize(events);

You can also use our JsonConverters:

var jsonSerializerOptions = new JsonSerializerOptions();
jsonSerializerOptions.Converters.Add(new EventJsonConverter());
...
// or just use your concrete Host:
// var jsonSerializerOptions = jsonSerializerHost.Services.GetService<JsonSerializerOptions>();

9) Docker image and compose changes

If you run examples/tests via Docker-Compose, rebuild with the new image/tag and use the updated docker-compose.yml file.

10) Check new models and types

Please check Migrating from Server API v3 to v4 migration guide.

[changeset-bot]

🦋 Changeset detected

Latest commit: 2148758

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
fingerprint-server-dotnet-sdk	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[ilfa]

What are the pros of downloading it each time and not keeping it in git?

[erayaydin]

It significantly increases the VCS repo size (~30 MB), and since it's a binary file, the only real benefit I see to keeping it in VC is security (if Maven has an outage or the file gets tampered with) and also having a static mirror. Having large files can be problematic for developers. If we're concerned about security, we could host our own remote mirror and keep it up to date instead. I'm also okay to use a static JAR file, but I prefer a small repository size.

P.S. Developers (not CI) will download it once because it doesn't download the file if it exists

[ilfa]

Can we have a complete scenario here and not just the API configuration for the DI?

[erayaydin]

Could you review the README changes in commit #b2ae80e? Let me know if it's enough or if you'd like me to add or remove anything.

[ilfa]

Yes, looks good!

[ilfa]

There are more of them

[erayaydin]

As far as I can tell from reviewing the tests, we're not using the other errors. So I kept only the ones we actually use and updated the sync.sh script accordingly.

[github-actions]

🚀 Following releases will be created using changesets from this PR:

[email protected]

Major Changes

• Rename .NET SDK project and namespaces from FingerprintPro.ServerSdk.* to Fingerprint.ServerSdk.*.

  Breaking changes

  • Update all using directives and fully-qualified type names:
    • FingerprintPro.ServerSdk.* → Fingerprint.ServerSdk.*
  • If you reference solution/project file names or CI paths, update them to the new Fingerprint.ServerSdk.* locations. (7af5781)