VMelnalksnis.PaperlessDotNet 1.1.0

PaperlessDotNet

.NET client for the Paperless-ngx API.

Usage

A separate NuGet package is provided for ASP.NET Core (IConfiguration and IServiceCollection) . For use outside of ASP.NET Core, see the example in tests.

1. Add configuration (see options)

   "Paperless": {
       "BaseAddress": "",
       "Token": ""
   }
   

2. Register required services (see tests)

   serviceCollection
       .AddSingleton<IClock>(SystemClock.Instance)
       .AddSingleton(DateTimeZoneProviders.Tzdb)
       .AddPaperlessDotNet();
   

3. Use IPaperlessClient to access all endpoints, or one of the specific clients defined in IPaperlessClient

Custom fields

Paperless supports adding custom fields to documents. In order to use custom fields, first define a class with a property for each field:

internal sealed class CustomFields
{
    public string? Field1 { get; set; }

    public Uri? Field2 { get; set; }

    public LocalDate? Field3 { get; set; }

    public bool? Field4 { get; set; }

    public int? Field5 { get; set; }

    public float? Field6 { get; set; }

    public float? Field7 { get; set; }

    public int[]? Field8 { get; set; }
}

Then create a JsonSerializerContext with all the API models that use custom fields:

[JsonSerializable(typeof(PaginatedList<Document<CustomFields>>))]
[JsonSerializable(typeof(DocumentUpdate<CustomFields>))]
internal sealed partial class SerializerContext : JsonSerializerContext;

And configure JSON serialization for the client:

serviceCollection.AddPaperlessDotNet(
    configuration,
    options =>
    {
        options.Options.Converters.Add(new CustomFieldsConverter<CustomFields>(options));
        options.Options.TypeInfoResolverChain.Add(SerializerContext.Default);
    });

For a working example see unit tests and integration tests.

Select custom fields

Version 2.11.0 introduced select custom fields, which require additional setup in order to serialize/deserialize properly. First, you'll need to define SmartEnum class for each select custom field:

public sealed class SelectOptions : SmartEnum<SelectOptions>
{
    public static readonly SelectOptions Option1 = new("First option", 0);
    public static readonly SelectOptions Option2 = new("Second option", 1);

    private SelectOptions(string name, int value)
        : base(name, value)
    {
    }
}

NOTE: the values MUST be sequential and start at 0 in order to match how they are stored in paperless.

Then you can add the property to your CustomFields class

    public SelectOptions? Field9 { get; set; }

and add the SmartEnumValueConverter<TEnum, TValue> in one of the possible ways:

    [JsonConverter(typeof(SmartEnumValueConverter<SelectOptions, int>))]
    public SelectOptions? Field9 { get; set; }

or

serviceCollection.AddPaperlessDotNet(
    configuration,
    options =>
    {
        options.Options.Converters.Add(new SmartEnumValueConverter<SelectOptions, int>())
        options.Options.Converters.Add(new CustomFieldsConverter<CustomFields>(options));
        options.Options.TypeInfoResolverChain.Add(SerializerContext.Default);
    });

In order to create a select custom field, you also need to use either SelectCustomFieldCreation<TEnum, TValue> or SelectCustomFieldCreation<TEnum> and add it to the JsonSerializerContext.