MealieSharp.Apprise 3.14.1

MealieSharp

A .NET 10 API client and webhook receiver for Mealie, with built-in dependency injection support.

• MealieSharp — Typed API client generated from the OpenAPI spec using Kiota
• MealieSharp.Webhooks — ASP.NET Core library for receiving Mealie's outbound webhook POSTs
• MealieSharp.Apprise — ASP.NET Core library for receiving Mealie's Apprise event notifications via json:// / jsons://

Installation

dotnet add package MealieSharp
dotnet add package MealieSharp.Webhooks
dotnet add package MealieSharp.Apprise

Versioning: The major and minor version track the Mealie API — MealieSharp 3.14.x targets Mealie v3.14.0. The patch version is for library-only changes (bug fixes, new features, improvements). When Mealie releases a new API version, MealieSharp resets to x.y.0.

Setup

With dependency injection

services.AddMealieClient(options =>
{
    options.BaseUrl = new Uri("https://mealie.example.com");
    options.Token = "your-api-token";
});

Or use the shorthand:

services.AddMealieClient(new Uri("https://mealie.example.com"), "your-api-token");

Be a good neighbor: MealieSharp sends MealieSharp/{version} as the default User-Agent. Please set options.UserAgent to something that identifies your application (e.g. "MyApp/1.0") so Mealie server operators can distinguish traffic sources. Set it to null to disable the header entirely.

AddMealieClient returns IHttpClientBuilder, so you can chain additional HttpClient configuration such as Polly retry policies or custom message handlers.

Usage

Inject MealieClient and access the API through the fluent builder:

using MealieSharp.Generated;
using MealieSharp.Generated.Models;

public class RecipeService(MealieClient mealie)
{
    public async Task PrintRecipesAsync()
    {
        // List recipes with pagination
        var recipes = await mealie.Recipes.GetAsync(q =>
        {
            q.QueryParameters.Page = 1;
            q.QueryParameters.PerPage = 25;
        });

        foreach (var recipe in recipes!.Items!)
            Console.WriteLine($"{recipe.Name?.String} ({recipe.Slug?.String})");

        // Get a single recipe by slug
        var detail = await mealie.Recipes["my-recipe-slug"].GetAsync();

        // Create a recipe from a URL
        var slug = await mealie.Recipes.Create.Url.PostAsync(new ScrapeRecipe
        {
            Url = "https://example.com/recipe"
        });
    }
}

Webhook Receiver

MealieSharp.Webhooks lets you receive Mealie's scheduled webhook POSTs (e.g. daily meal plan notifications) in your ASP.NET Core application.

Minimal setup (delegate handler)

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMealieWebhooks(async (webhookEvent, ct) =>
{
    Console.WriteLine($"Received: {webhookEvent.DocumentData?.DocumentType}");
});

var app = builder.Build();
app.MapMealieWebhooks();
app.Run();

Class-based handler with DI

public class MealplanWebhookHandler(ILogger<MealplanWebhookHandler> logger) : IMealieWebhookHandler
{
    public Task HandleAsync(MealieWebhookEvent webhookEvent, CancellationToken ct)
    {
        logger.LogInformation("Mealplan webhook for {Date}",
            webhookEvent.DocumentData?.WebhookStartDt);
        return Task.CompletedTask;
    }
}

// Program.cs
builder.Services.AddMealieWebhooks<MealplanWebhookHandler>();

var app = builder.Build();
app.MapMealieWebhooks("/my/custom/webhook/path");
app.Run();

Combined with the API client

builder.Services.AddMealieClient(new Uri("https://mealie.example.com"), "api-token");
builder.Services.AddMealieWebhooks<MealplanWebhookHandler>();

var app = builder.Build();
app.MapMealieWebhooks();
app.Run();

MapMealieWebhooks returns IEndpointConventionBuilder so you can chain .RequireAuthorization(), .RequireHost(), etc.

Apprise Event Notification Receiver

MealieSharp.Apprise lets you receive Mealie's event-driven notifications (recipe CRUD, meal plan changes, shopping lists, and more — 27 event types) via Apprise's json:// URL scheme.

In Mealie, create an Event Notifier with an Apprise URL like json://yourserver.com/notifications/apprise, then:

Minimal setup (delegate handler)

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAppriseNotifications(async (notification, ct) =>
{
    Console.WriteLine($"[{notification.Type}] {notification.Title}: {notification.Body}");
});

var app = builder.Build();
app.MapAppriseNotifications();
app.Run();

Class-based handler with DI

public class MyAppriseHandler(ILogger<MyAppriseHandler> logger) : IAppriseNotificationHandler
{
    public Task HandleAsync(AppriseNotification notification, CancellationToken ct)
    {
        logger.LogInformation("[{Type}] {Title}", notification.Type, notification.Title);
        return Task.CompletedTask;
    }
}

// Program.cs
builder.Services.AddAppriseNotifications<MyAppriseHandler>();

var app = builder.Build();
app.MapAppriseNotifications("/my/custom/notification/path");
app.Run();

Combined with webhooks and the API client

builder.Services.AddMealieClient(new Uri("https://mealie.example.com"), "api-token");
builder.Services.AddMealieWebhooks<MealplanWebhookHandler>();
builder.Services.AddAppriseNotifications<MyAppriseHandler>();

var app = builder.Build();
app.MapMealieWebhooks();
app.MapAppriseNotifications();
app.Run();

MapAppriseNotifications returns IEndpointConventionBuilder so you can chain .RequireAuthorization(), .RequireHost(), etc.

Testing

A Makefile is provided for convenience:

make test                  # API client unit tests (no network required)
make test-webhooks         # Webhook receiver unit tests (no network required)
make test-apprise          # Apprise receiver unit tests (no network required)
make integration           # Integration tests (requires configuration, see below)
make integration-webhooks  # Webhook integration tests
make integration-apprise   # Apprise integration tests

Unit tests (MealieSharp.Unit) verify DI registration, MealieClientOptions defaults, and that every API group exposes the expected fluent surface — no network required.

Webhook unit tests (MealieSharp.Webhooks.Unit) verify payload deserialization, DI registration, and full endpoint behavior (via TestServer) including all HTTP status code paths — no network required.

Apprise unit tests (MealieSharp.Apprise.Unit) verify Apprise notification deserialization, DI registration, and full endpoint behavior (via TestServer) including all HTTP status code paths — no network required.

Integration tests (MealieSharp.Integration) run against a real Mealie instance and cover all 16 API groups (Admin, App, Auth, Comments, Explore, Foods, Groups, Households, Media, Organizers, Parser, Recipes, Shared, Units, Users, Utils). They require configuration — see below.

Integration tests require a Mealie instance. Configure via user secrets:

cd test/MealieSharp.Integration

# Required
dotnet user-secrets set "Mealie:BaseUrl" "https://your-instance.example.com"

# Authenticate with username/password (token is fetched and cached for the test run)
dotnet user-secrets set "Mealie:Username" "your@email.com"
dotnet user-secrets set "Mealie:Password" "your-password"

# Or authenticate with a static API token
dotnet user-secrets set "Mealie:Token" "your-api-token"

Packaging

make pack                  # Pack all three libraries into artifacts/
make pack VERSION=3.14.1   # Pack with a version override
make push                  # Push to NuGet (requires NUGET_API_KEY)

Code Generation

API client code is generated from the Mealie OpenAPI spec using Kiota. See CODEGEN.md for regeneration instructions.

make generate          # Regenerate Kiota client from OpenAPI spec

Requirements

• .NET 10.0

License

MIT — see LICENSE.