Ampleo.ApiClient 0.1.0-preview.3

Ampleo API Client

A typed .NET client and code generator for the AmpleoCRM HTTP API.

• Ampleo.ApiClient — the client library. Authentication, CRUD (dynamic and strongly-typed), metadata discovery, a query builder, retries, and typed errors. No runtime dependencies.
• Ampleo.ApiClient.CodeGen (ampleo-apigen) — a dotnet tool that generates strongly-typed entity classes and option-set enums from your tenant's live metadata, so field access is compile-checked (you can't misspell a field).

Pre-release. These packages are published as pre-release (0.1.0-preview.*). The API surface may change before 1.0.

Install

# Client library
dotnet add package Ampleo.ApiClient --prerelease

# Code generator (global tool)
dotnet tool install --global Ampleo.ApiClient.CodeGen --prerelease

Authenticate

Authenticate with a tenant API key — the only method this client supports (create one in AmpleoCRM under Settings → API keys). User/identity-provider sign-in is intentionally not available here; it is reserved for the Outlook add-in.

using Ampleo.ApiClient;

var crm = AmpleoCrmClient.WithApiKey("https://api.ampleo.dk", "ampk_…");

// Confirm auth works — the first thing to call.
var me = await crm.WhoAmIAsync();
Console.WriteLine($"Connected as {me.DisplayName}");

Use it dynamically (no codegen)

var page = await crm.ListAsync("Company", new AmpleoQuery().Eq("status", 2).PageSize(50));
foreach (var c in page.Items)
    Console.WriteLine($"{c.Get<string>("name")} — {c.Label("status")}");

var created = await crm.CreateAsync("Lead", new Dictionary<string, object?>
{
    ["firstName"] = "Thomas",
    ["email"] = "tmb@example.com",
});

Use it strongly-typed (with codegen)

Generate classes from your tenant once (re-run when the schema changes):

ampleo-apigen --url https://api.ampleo.dk --api-key ampk_… \
  --out ./Crm --namespace MyApp.Crm

Then the field names and option values are compile-checked:

using MyApp.Crm;

var company = await crm.GetAsync<Company>(id);
company.Status = CompanyStatus.Active;          // enum, not a magic int
await crm.SaveAsync(company);                    // PATCHes only what changed

var active = await crm.Query<Company>()
    .Eq(Company.Fields.Status, CompanyStatus.Active)
    .OrderBy(Company.Fields.Name)
    .ToListAsync();

The same lists the CRM shows

An entity carries named views, and the server can apply one for you:

var meta = await crm.GetEntityAsync("Opportunity");
foreach (var view in meta.Views)
    Console.WriteLine($"{view.Name}: {view.Label}{(view.IsDefault ? " (default)" : "")}");

// The view's filters and sort, applied server-side, narrowed to one customer.
var page = await crm.Query<Opportunity>()
    .View("openOpportunities")
    .Eq(Opportunity.Fields.CompanyId, companyId)
    .ToPageAsync();

Ask by name rather than copying a view's filters: a view can select "records owned by the calling user or their team", which cannot be written as a filter because only the server knows who is calling.

A record also carries two read-only siblings worth knowing: record.Label("stage") gives an option's localized label, and record.RelationName("companyId") gives the display name of the record a lookup points at, so a list row needs no extra request per row. Write a relation by setting the id (companyId); sending companyId@name sets nothing.

Requests that don't fail

• Typed models — the compiler catches misspelled fields.
• Optional local validation before sending (AmpleoCrmClientOptions.ValidateBeforeSend): required fields, max length, and option membership are checked against cached metadata, so you get a precise AmpleoValidationException without a round trip.
• Typed errors — RFC 9457 Problem Details are mapped to AmpleoValidationException (with field errors), AmpleoAuthException, AmpleoNotFoundException, and AmpleoRateLimitException.
• Automatic retries on 429/5xx honouring Retry-After.

Building

dotnet build Ampleo.ApiClient.slnx -c Release

License

MIT — provided "as is", without warranty of any kind. This client talks to the AmpleoCRM HTTP API; it contains no AmpleoCRM server code.