VoliMaconomyClient 1.1.17

VoliNuget

A .NET client library for interacting with the Deltek Maconomy API. It wraps authentication, reconnect or cookie token handling, payload creation, and common container operations so other C# applications can talk to Maconomy with less boilerplate.

NuGet package: https://www.nuget.org/packages/VoliMaconomyClient

Features

• Automatic authentication and token reuse
• Helpers for building Maconomy payloads from POCO classes
• Filter, Card, CardAction, CardPrint, CardTable, and Table operations
• Automatic handling of Maconomy container API v1 vs v2 during authentication
• CLI tooling for generating strongly typed C# models from container metadata
• NuGet package targeting .NET 8

Installation

Install the package into your project:

dotnet add package VoliMaconomyClient

Then import the runtime namespace:

using VoldeligClient;

Configuration

The default configuration contract is:

{
  "VoldeligClient": {
    "connection": {
      "baseurl": "https://maconomy.example.com",
      "username": "apiuser",
      "password": "apipass",
      "shortname": "MCO"
    }
  }
}

new Voldelig(IConfiguration) expects exactly those keys.

Usage

Basic filter query

using Microsoft.Extensions.Configuration;
using VoldeligClient;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var client = new Voldelig(configuration);
var result = await client.Filter<Jobs>(null, limit: 100);

List<Jobs> jobs = result.Match(
    list => list,
    error =>
    {
        Console.WriteLine($"Request failed: {error.MaconomyErrorMessage}");
        return new List<Jobs>();
    });

Main operations

The main entry point is Voldelig, with extension methods for:

• Filter<T>() and FilterAll<T>() for list and search queries
• Card<T>() for create, get, update, and delete of a single entity
• CardAction<T>() for workflow actions such as post or approve
• CardPrint<T>() for actions that return downloadable files
• CardTable<TCard, TRow>() for fetching a card plus its related table rows
• Table<TCard, TRow>() for create, get, update, and delete on table rows

Results are returned as Either<TSuccess, VoldeligHttpResponseMessage>:

• IsLeft means success
• IsRight means error
• MaconomyErrorMessage contains the error details

Model Generation

This repository also contains VoldeligCLI, which generates strongly typed models from Maconomy container metadata.

Examples:

dotnet run --project VoldeligCLI -- fields --container jobs --object-type filter --json
dotnet run --project VoldeligCLI -- generate --container jobs --object-type filter --dry-run

Generated classes are intended to be used as the generic type arguments passed into the client methods.

Repository Structure

• VoldeligClient/: the NuGet library consumed by other projects
• VoldeligCLI/: CLI for model generation
• VoldeligTest/: integration tests and usage examples
• voliext/: VS Code extension for the CLI
• Tools/PublishNuget/: NuGet publishing helper

AI and Tooling Notes

If other projects use Codex or similar tools, point them to AGENTS.md in this repository. It defines the canonical package name, namespace, configuration contract, entry points, and source files to read first.

Deploying to NuGet

The repository includes a helper tool that bumps the package version, validates the build, packs, and pushes to NuGet.

1. Make sure .env in the repo root contains NUGET_API_KEY=<your-api-key> and optionally NUGET_SOURCE=<custom-feed-url>.
2. Run:

dotnet run --project Tools/PublishNuget -- 1.0.17

3. The tool restores the previous version automatically if any step fails.

License

Distributed under the MIT License. See LICENSE for details.