ajsuth / ordercloud-dotnet-catalyst

Starter middleware, extensions, and tools to get developers running with OrderCloud faster.

ordercloud-dotnet-catalyst

A foundational library for building OrderCloud middleware, plugins and extensions with .NET. A toolbox of helpers for authentication, performant bulk requests, error handling, jobs, project setup, ect.

See dotnet-catalyst-examples for a starter template of a middleware project that uses this library. Targeted guides are found there.

If you're building solutions for OrderCloud using .NET and find a particular task difficult or tedious, we welcome you to suggest a feature for inclusion in this library.

⚠️ Version 1.x.x has known security holes. Please only use version 2.0.1 and later.

Features

3rd Party Integrations

Contributing Guide For Integrations -> CONTRIBUTING.md

Name	README	Nuget Library	Contributed By	Interfaces
BlueSnap	OrderCloud.Integrations.Payment.BlueSnap		OrderCloud Team	ICreditCardProcessor, ICreditCardSaver
CardConnect	OrderCloud.Integrations.Payment.CardConnect		OrderCloud Team	ICreditCardProcessor, ICreditCardSaver
Stripe	OrderCloud.Integrations.Payment.Stripe		OrderCloud Team	ICreditCardProcessor, ICreditCardSaver
EasyPost	OrderCloud.Integrations.Shipping.EasyPost		OrderCloud Team	IShippingRatesCalculator
Fedex	OrderCloud.Integrations.Shipping.Fedex		OrderCloud Team	IShippingRatesCalculator
UPS	OrderCloud.Integrations.Shipping.UPS		OrderCloud Team	IShippingRatesCalculator
Avalara	OrderCloud.Integrations.Tax.Avalara		OrderCloud Team	ITaxCalculator, ITaxCodeProvider
Vertex	OrderCloud.Integrations.Tax.Vertex		OrderCloud Team	ITaxCalculator
TaxJar	OrderCloud.Integrations.Tax.TaxJar		OrderCloud Team	ITaxCalculator, ITaxCodeProvider

User Authentication

Use Ordercloud's authentication scheme in your own APIs.

[HttpGet("hello"), OrderCloudUserAuth(ApiRole.Shopper)]
public string SayHello() {
    return $"Hello {UserContext.Username}";  // UserContext is a property on CatalystController
}

Webhook Authentication

Securely receive push notifications of events from the Ordercloud platform.

[HttpPost("webhook"), OrderCloudWebhookAuth]
public object HandleAddressSave([FromBody] WebhookPayloads.Addresses.Save<MyConfigData> payload) {
    ...
}

Listing All Pages

If OrderCloud's limit of 100 records per page is a pain point.

var orders = new OrderCloudClient(...).Orders.ListAllAsync();

Proxying Platform List Calls

Receive list requests to your API with user defined filters, search, paging, and sorting.

[HttpGet("orders"), OrderCloudUserAuth(ApiRole.Shopper)]
public async Task<ListPage<Order>> ListOrders(IListArgs args)
{
    var user = await _oc.Me.GetAsync(UserContext.AccessToken); // get user details
    args.Filters.Add(new ListFilter("FromCompanyID", user.MeUser.Buyer.ID)) // filter using the user's buyer organization ID 
    args.Filters.Add(new ListFilter("LineItemCount", ">5"))
    // list orders from an admin endpoint
    var orders = await _oc.Orders.ListAsync(OrderDirection.Incoming, null, null, null, null, args); // apply list args with an extension version of ListAsync()
    return orders;
}

Caching

Use Redis or LazyCache. Or, define your own implementation of ISimpleCache.

private ISimpleCache _cache;

[HttpGet("thing")]
public Thing GetThing(string thingID) {
    var key = $"thing-{thingID}";
    var timeToLive = TimeSpan.FromMinutes(10);
    var thing = await _cache.GetOrAddAsync(key, timeToLive, () database.GetThing(thingID));
    return thing;
}

[HttpPut("thing")]
public Thing EditThing(string thingID) {
    var key = $"thing-{thingID}";
    await _cache.RemoveAsync(thingID);
    return await database.EditThing(thingID);
}

Throttler

A perfomance helper for multiple async function calls.

var cars = new List<Car>();

var maxConcurency = 20;
var minPause = 100 // ms
var carOwners = await Throttler.RunAsync(cars, minPause, maxConcurency, car => apiClient.GetCarOwner(car.ID);

Error Handling

Handle API errors, including unexpected ones, with a standard JSON response structure. Define your own errors.

public class AgeLimit21Exception : CatalystBaseException
{
    public AgeLimit21Exception() : base("AgeLimit21", 403, "You must be 21 years of age or older to buy this product.") { }
}

....

Require.That(user.xp.Age >= 21, new AgeLimit21Exception());

Model Validation

Take advantage of DataAnnotation attributes to specify validation requirements for your own custom models.

[Required(ErrorMessage = "This field is required, please try again.")]
public string RequiredField { get; set; }

Testing helpers

When writing integration tests that hit an endpoint marked with [OrderCloudUserAuth], you'll need to pass a properly formatted JWT token in the Authorization header, otherwise the call will fail. Fake tokens are a bit tedious to create, so OrderCloud.Catalyst provides a helper:

var token = FakeOrderCloudToken.Create(
    clientID: "my-client-id", 
    roles: new List<string> { "Shopper" },
    expiresUTC: DateTime.UtcNow + TimeSpan.FromHours(1),
    notValidBeforeUTC: DateTime.UtcNow - TimeSpan.FromHours(1)
);
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);