Backend Plugin Development

# Create plugin project
dotnet new classlib -n Rasepi.Plugins.MyPlugin -f net8.0
cd Rasepi.Plugins.MyPlugin

# Reference the SDK
dotnet add reference ../Rasepi.Plugins.SDK/Rasepi.Plugins.SDK.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\Rasepi.Plugins.SDK\Rasepi.Plugins.SDK.csproj" />
  </ItemGroup>
</Project>

using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.DependencyInjection;
using Rasepi.Plugins.SDK;

namespace Rasepi.Plugins.MyPlugin;

public sealed class MyPluginModule : IPluginModule
{
    public const string PluginId = "my-plugin";

    public PluginManifest Manifest { get; } = new()
    {
        Id          = PluginId,
        Name        = "My Custom Plugin",
        Version     = "1.0.0",
        Description = "Does something useful",
        Category    = "Integration",
        HasSettings  = false,
        HasEndpoints = true,
    };

    public void RegisterServices(IServiceCollection services)
    {
        // Register your guards, services, repositories
        services.AddScoped<IActionGuard, MyPublishGuard>();
        services.AddScoped<IMyService, MyService>();
    }

    public void MapRoutes(IEndpointRouteBuilder routes)
    {
        // Routes are scoped to /api/plugins/my-plugin/...
        routes.MapGet("/status", () => Results.Ok(new { healthy = true }));
    }
}

// Program.cs — Plugin Registration

// 1. Create the registry
var pluginRegistry = new PluginRegistry();
builder.Services.AddSingleton<IPluginRegistry>(pluginRegistry);

// 2. Core platform services
builder.Services.AddScoped<ITenantPluginResolver, TenantPluginResolver>();
builder.Services.AddScoped<ITenantPluginInstallationService, TenantPluginInstallationService>();
builder.Services.AddScoped<IActionPipeline, ActionPipeline>();

// 3. Register your plugins
pluginRegistry.AddPlugin<MyPluginModule>(builder.Services);

// ... after building the app:

// 4. Map plugin routes (auto-scoped to /api/plugins/{id})
app.MapPluginRoutes(pluginRegistry);

using Rasepi.Plugins.SDK;

namespace Rasepi.Plugins.MyPlugin;

/// <summary>
/// Example: Block publishing entries that contain "TODO" markers.
/// </summary>
public sealed class NoDraftMarkersGuard : IActionGuard
{
    // Must match your plugin module's ID
    public string PluginId => MyPluginModule.PluginId;

    // Which action to intercept (null = ALL actions)
    public string? ActionName => ActionNames.Entry.Publish;

    public Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var content = context.Get<string>("content") ?? "";

        if (content.Contains("TODO", StringComparison.OrdinalIgnoreCase))
        {
            return Task.FromResult(ActionGuardResult.Deny(
                reasonCode: "my-plugin.has-todos",
                message: "Cannot publish: entry still contains TODO markers."));
        }

        return Task.FromResult(ActionGuardResult.Allow());
    }
}

using Rasepi.Plugins.SDK;

namespace Rasepi.Plugins.MyPlugin;

public sealed class SlackNotifierHandler : IPluginEventHandler
{
    public string PluginId => MyPluginModule.PluginId;

    public IReadOnlyList<string> SubscribedEvents => new[]
    {
        "Entry.Published",
        "Entry.Expired"
    };

    public async Task HandleAsync(
        string eventName,
        Guid entityId,
        Guid? tenantId,
        Guid? userId,
        string payloadJson,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var slackClient = services.GetRequiredService<ISlackClient>();

        var message = eventName switch
        {
            "Entry.Published" => $"📣 Entry {entityId} was just published!",
            "Entry.Expired"   => $"⚠️ Entry {entityId} has expired.",
            _ => null
        };

        if (message != null)
            await slackClient.PostAsync("#documentation", message);
    }
}

public void RegisterServices(IServiceCollection services)
{
    services.AddScoped<IPluginEventHandler, SlackNotifierHandler>();
    services.AddHttpClient<ISlackClient, SlackClient>();
}

namespace Rasepi.Plugins.MyPlugin;

public static class MyPluginEndpoints
{
    public static void Map(IEndpointRouteBuilder routes)
    {
        // GET /api/plugins/my-plugin/config
        routes.MapGet("/config", async (IMyService svc) =>
        {
            var config = await svc.GetConfigAsync();
            return Results.Ok(config);
        });

        // POST /api/plugins/my-plugin/webhook
        routes.MapPost("/webhook", async (
            HttpRequest req, IMyService svc) =>
        {
            using var reader = new StreamReader(req.Body);
            var payload = await reader.ReadToEndAsync();
            await svc.ProcessWebhookAsync(payload);
            return Results.Accepted();
        });
    }
}

// In your module:
public void MapRoutes(IEndpointRouteBuilder routes)
{
    MyPluginEndpoints.Map(routes);
}

using Rasepi.Plugins.SDK;

public sealed class MyTranslationProvider : ITranslationProviderPlugin
{
    public string Id => "my-translator";
    public string Name => "My Translation Engine";
    public string Version => "1.0.0";
    public bool IsEnabled { get; set; } = true;

    private ILogger? _logger;

    public void Initialize(IPluginContext context)
    {
        _logger = context.Logger;
    }

    public string[] GetSupportedLanguages()
    {
        return new[] { "EN", "DE", "FR", "ES", "IT", "JA", "ZH" };
    }

    public async Task<string> TranslateAsync(
        string text, string sourceLanguage, string targetLanguage)
    {
        // Call your translation API
        var client = new HttpClient();
        var result = await client.PostAsJsonAsync(
            "https://api.mytranslator.com/translate",
            new { text, from = sourceLanguage, to = targetLanguage });
        var data = await result.Content.ReadFromJsonAsync<TranslateResponse>();
        return data?.TranslatedText ?? text;
    }

    public async Task<TranslationBatchResult> TranslateBatchAsync(
        Dictionary<string, string> texts,
        string sourceLanguage, string targetLanguage)
    {
        // Batch translate for efficiency
        var results = new Dictionary<string, string>();
        var billed = 0;

        foreach (var (key, text) in texts)
        {
            results[key] = await TranslateAsync(text, sourceLanguage, targetLanguage);
            billed += text.Length;
        }

        return new TranslationBatchResult(results, billed);
    }
}

// Export to custom format
public sealed class MarkdownExporter : IExportPlugin
{
    public string Id => "markdown-export";
    public string Name => "Markdown Exporter";
    public string Version => "1.0.0";
    public bool IsEnabled { get; set; } = true;

    public string ExportFormat => "Markdown";
    public string FileExtension => ".md";

    public void Initialize(IPluginContext context) { }

    public async Task<byte[]> ExportAsync(object entry)
    {
        // Convert entry to Markdown
        var markdown = ConvertToMarkdown(entry);
        return Encoding.UTF8.GetBytes(markdown);
    }
}

// Import from custom format
public sealed class DocxImporter : IImportPlugin
{
    public string Id => "docx-import";
    public string Name => "Word Importer";
    public string Version => "1.0.0";
    public bool IsEnabled { get; set; } = true;

    public string ImportFormat => "Word Document";
    public string[] SupportedFileExtensions => new[] { ".docx" };

    public void Initialize(IPluginContext context) { }

    public async Task<object> ImportAsync(byte[] fileData)
    {
        // Parse .docx and produce TipTap-compatible JSON
        return ParseDocx(fileData);
    }
}

Action Triggered (e.g. Entry.Publish)
  │
  ▼
IActionPipeline.ExecuteAsync()
  │
  ├─ Resolve enabled plugins for tenant (ITenantPluginResolver)
  │
  ├─ Filter IActionGuard implementations:
  │    • Guard.PluginId must be in enabled set
  │    • Guard.ActionName == null (wildcard) OR matches action
  │
  ├─ Evaluate guards sequentially:
  │    ├─ Allow           →  continue
  │    ├─ Allow + Mods    →  collect modifications
  │    ├─ Deny            →  collect denial, stop
  │    └─ Exception       →  log, treat as Allow (fail-open)
  │
  └─ Result:
       ├─ All allowed     →  execute the action
       ├─ With mods       →  execute with modifications applied
       └─ Any denial      →  return 422 with reasonCode + message

Plugin Registration (startup, global)
  ↓
Tenant Installs Plugin (via API /api/tenant/plugins/{id}/install)
  ↓
Tenant Enables Plugin (via API /api/tenant/plugins/{id}/enable)
  ↓
Request arrives → TenantContext resolved from JWT
  ↓
Pipeline queries: "which plugins are enabled for this tenant?"
  ↓
Only those guards execute

[Fact]
public async Task Publish_blocked_when_content_has_todos()
{
    var guard = new NoDraftMarkersGuard();
    var context = new ActionGuardContext(
        ActionName: ActionNames.Entry.Publish,
        TenantId: Guid.NewGuid(),
        UserId: Guid.NewGuid(),
        EntityId: Guid.NewGuid(),
        Properties: new Dictionary<string, object?>
        {
            ["content"] = "This is a TODO item that needs work"
        });

    var result = await guard.EvaluateAsync(context, Mock.Of<IServiceProvider>());

    Assert.False(result.IsAllowed);
    Assert.Equal("my-plugin.has-todos", result.ReasonCode);
}

[Fact]
public async Task Publish_allowed_when_content_is_clean()
{
    var guard = new NoDraftMarkersGuard();
    var context = new ActionGuardContext(
        ActionName: ActionNames.Entry.Publish,
        TenantId: Guid.NewGuid(),
        UserId: Guid.NewGuid(),
        EntityId: Guid.NewGuid(),
        Properties: new Dictionary<string, object?>
        {
            ["content"] = "Clean, publication-ready content"
        });

    var result = await guard.EvaluateAsync(context, Mock.Of<IServiceProvider>());

    Assert.True(result.IsAllowed);
}