OloLabs.Promotions.SDK 3.0.3

OloLabs.Promotions.SDK

OloLabs.Promotions.SDK is a NuGet package that provides models and tools for integrating with the Olo Promotions Specification.

View the Promotions Spec at https://developer.olo.com/docs.

Use of the SDK is subject to the terms of the Olo Promotions SDK License.

Table of Contents

• OloLabs.Promotions.SDK
  • Table of Contents
  • Getting Started
    • Install from nuget.org
    • Install from .nupkg file
  • Structure
  • How to Use
    • Authentication
    • Requests
    • Responses
      • Successful Responses
      • Error Responses

Getting Started

Install from NuGet.org

This SDK is available on NuGet.org: OloLabs.Promotions.SDK

This can be installed via the NuGet command line:

• nuget install OloLabs.Promotions.SDK

Or added to an existing project using the dotnet CLI:

• dotnet add package OloLabs.Promotions.SDK

Or added via Visual Studio's NuGet Package Manager:

• See Quickstart: Install and use a NuGet package in Visual Studio.

Install from .nupkg file

1. Download the latest release of our NuGet package GitHub or NuGet.org.
2. Create a local feed for NuGet.
   • See https://learn.microsoft.com/en-us/nuget/hosting-packages/local-feeds.
3. Add the OloLabs.Promotions.SDK package to the local feed.
4. Install the package to your application.
   • nuget install OloLabs.Promotions.SDK

Structure

The SDK includes three primary directories/namespaces:

├───OloLabs.Promotions.SDK
│   ├───Authentication
│   ├───Requests
│   └───Responses

These areas include:

• Authentication helpers
• Models for Requests
• Models for Responses

How to Use

Authentication

bool ValidateSignature(string signatureFromRequest)
{
    // Build the RequestAuthenticator.
    var requestAuthenticator = new RequestAuthenticator();

    // Generate a signature using the URL and body from the incoming request, along with the shared secret between you and Olo.
    var expectedSignature = requestAuthenticator.CreateSignature(
        url: "https://your-promotions-api.local/promotions/validate",
        body: "{the-request-body}",
        secret: "YOUR_SECRET");

    // Compare the request's signature (provided in the header X-Promo-Signature) with your generated signature.
    // If they match, then the signature is valid and the request is successfully authenticated.
    // If they don't match, then the signature is invalid and the request fails authentication.
    return signatureFromRequest == expectedSignature;
}

builder.Services.AddSingleton<IRequestAuthenticator, RequestAuthenticator>();

public class PromotionsRequestAuthenticatorMiddleware
{
    private readonly IRequestAuthenticator _requestAuthenticator;

    public PromotionsRequestAuthenticatorMiddleware(IRequestAuthenticator requestAuthenticator)
    {
        _requestAuthenticator = requestAuthenticator;
    }

    bool ValidateSignature(string signatureFromRequest)
    {
        var expectedSignature = _requestAuthenticator.CreateSignature(...);

        ...
    }
}

Requests

The following request models are provided:

• AccruePointsRequest
• CreateAccountRequest
• RedeemPromotionsRequest
• ValidatePromotionsRequest
• VoidAccrualRequest
• VoidRedemptionRequest

You can use the relevant models in your API configuration to accept incoming Promotions requests that specify a request body.

public class ValidatePromotionsController
{
    [HttpPost]
    public IActionResult ValidatePromotions([FromBody] ValidatePromotionsRequest request)
    {
        Console.WriteLine(JsonSerializer.Serialize(request));
    }
}

// Output:
// {
//    "orderId": null,
//    "accountId": "391528477",
//    "source": "Web",
//    "handoff": "delivery",
//    "currency": "USD",
//    "placed": "2023-02-01T18:00:00.000Z",
//    "wanted": "2023-02-01T19:30:00.000Z",
//    ...
// }

[Route("/promotions/accounts/{accountId}")]
public class GetAccountController
{
    ...
}

Responses

Successful Responses

The following response models are provided:

• AccruePointsResponse
• CreateAccountResponse
• FindAccountsResponse
• GetAccountResponse
• RedeemPromotionsResponse
• ValidatePromotionsResponse
• VoidAccrualResponse
• VoidRedemptionResponse

You can use the relevant models to return successful responses from your API.

public class VoidAccrualController
{
    [HttpDelete]
    public IActionResult VoidAccrual(...)
    {
        ...

        return Ok(new VoidAccrualResponse
        {
            Transaction = new Transaction
            {
                ...
            }
        });
    }
}

Error Responses

Two error response models are provided:

• ErrorCodeResponse
  • For 400 Bad Request error responses that require a code.
  • Use ErrorCode to specify the value for code
    • ErrorCode.InvalidAccount → INVALID_ACCOUNT
    • ErrorCode.InvalidPromotion → INVALID_PROMOTION
    • etc.
• ErrorResponse
  • For all other error responses.

Example for ErrorCodeResponse:

public class VoidAccrualController
{
    [HttpDelete]
    [Route("/promotions/accruals/{accrualId}")]
    public IActionResult VoidAccrual(string accrualId, [FromBody] VoidAccrualRequest request)
    {
        ...

        return BadRequest(new ErrorCodeResponse
        {
            Id = Guid.NewGuid().ToString(),
            Code = ErrorCode.InvalidAccount // "INVALID_ACCOUNT",
            Details = $"Account ID '{request.AccountId}' could not be found.",
            Message = "There was a problem with your loyalty account. Please try again later."
        });
    }
}

Example for ErrorResponse:

public class VoidAccrualController
{
    [HttpDelete]
    [Route("/promotions/accruals/{accrualId}")]
    public IActionResult VoidAccrual(string accrualId, [FromBody] VoidAccrualRequest request)
    {
        ...

        return NotFound(new ErrorResponse
        {
            Id = Guid.NewGuid().ToString(),
            Details = $"Transaction ID {accrualId} could not be found.",
            Message = "There was a problem voiding the loyalty transaction. Please try again later."
        });
    }
}