Add Vertex, TaxJar, Avalara

README.md

@@ -10,6 +10,12 @@ If you're building solutions for OrderCloud using .NET and find a particular tas
 
 ## Features
 
+### [Commerce Integration List](./library/OrderCLoud.Catalyst/Integrations/Implementations/README.md)
+
+Interact with popular 3rd party APIs that provide functionality useful for commerce. Integrations within a category are made interoperable with an interface. 
+
+[Guide to adding an Integration](./library/OrderCLoud.Catalyst/Integrations/README.md)
+
 ### [User Authentication](https://github.com/ordercloud-api/ordercloud-dotnet-catalyst/tree/dev/library/OrderCloud.Catalyst/Auth/UserAuth)
 
 Use Ordercloud's authentication scheme in your own APIs.

library/OrderCloud.Catalyst/Integrations/Exceptions/IntegrationAuthFailedException.cs

@@ -0,0 +1,25 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace OrderCloud.Catalyst
+{
+	public class IntegrationAuthFailedException : CatalystBaseException
+	{
+		public IntegrationAuthFailedException(OCIntegrationConfig config, string requestUrl) : base(
+			"IntegrationAuthorizationFailed",
+			$"Authentication to 3rd party service \"{config.ServiceName}\" failed. Check your config credentials.",
+			new IntegrationAuthFailedError() 
+			{
+				ServiceName = config.ServiceName,
+				RequestUrl = requestUrl,
+			}, 
+			400) {}
+	}
+
+	public class IntegrationAuthFailedError
+	{
+		public string ServiceName { get; set; }
+		public string RequestUrl { get; set; }
+	}
+}

library/OrderCloud.Catalyst/Integrations/Exceptions/IntegrationErrorResponseException.cs.cs

@@ -0,0 +1,28 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace OrderCloud.Catalyst
+{
+	public class IntegrationErrorResponseException : CatalystBaseException 
+	{
+		public IntegrationErrorResponseException(OCIntegrationConfig config, string requestUrl, object responseBody) : base(
+			"IntegrationErrorResponse",
+			$"Request to 3rd party service \"{config.ServiceName}\" resulted in an error. See body for details.",
+			new IntegrationErrorResponseError()
+			{
+				ServiceName = config.ServiceName,
+				RequestUrl = requestUrl,
+				ResponseBody = responseBody
+			}
+			, 400)
+		{ }
+	}
+
+	public class IntegrationErrorResponseError
+	{
+		public string ServiceName { get; set; }
+		public string RequestUrl { get; set; }
+		public object ResponseBody { get; set; }
+	}
+}

library/OrderCloud.Catalyst/Integrations/Exceptions/IntegrationMissingConfigsException.cs

@@ -0,0 +1,31 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace OrderCloud.Catalyst
+{
+	public class IntegrationMissingConfigsException : CatalystBaseException 
+	{
+		public IntegrationMissingConfigsException(OCIntegrationConfig config, List<string> missingFields) : base(
+			"IntegrationMissingConfigs",
+			$"Configuration field(s) for 3rd party service \"{config.ServiceName}\" are null or empty. Check fields on class {config.GetType().Name}.",
+			new IntegrationMissingConfigs()
+			{
+				ServiceName = config.ServiceName,
+				MissingFieldNames = missingFields
+			},
+			400) { }
+	}
+
+	public class IntegrationMissingConfigs
+	{
+		public string ServiceName { get; set; }
+		public List<string> MissingFieldNames { get; set; } = new List<string>();
+	}
+
+	[AttributeUsage(AttributeTargets.Property)]
+	public class RequiredIntegrationFieldAttribute : Attribute
+	{
+
+	}
+}

library/OrderCloud.Catalyst/Integrations/Exceptions/IntegrationNoResponseException.cs.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace OrderCloud.Catalyst
+{
+	public class IntegrationNoResponseException : CatalystBaseException
+	{
+		public IntegrationNoResponseException(OCIntegrationConfig config, string requestUrl) : base(
+				"IntegrationNoResponse",
+				$"Request to 3rd party service \"{config.ServiceName}\" returned no response.",
+				new IntegrationNoResponseError()
+				{
+					ServiceName = config.ServiceName,
+					RequestUrl = requestUrl,
+				}
+				, 400)
+			{ }
+	}
+
+	public class IntegrationNoResponseError
+	{
+		public string ServiceName { get; set; }
+		public string RequestUrl { get; set; }
+	}
+}

library/OrderCloud.Catalyst/Integrations/Implementations/README.md

@@ -0,0 +1,5 @@
+# List of Integrations 
+
+| Name | Website | Integration Guide | Contributed By | Categories  |
+| ------------- | ------------- | ------------- | ------------- | ------------- |
+| Vertex | https://www.vertexinc.com/ | [./Vertex/README.md](./Vertex/README.md) | OrderCloud Team | Tax

library/OrderCloud.Catalyst/Integrations/Implementations/Vertex/Mappers/VertexRequestMapper.cs

@@ -0,0 +1,104 @@
+using OrderCloud.SDK;
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Text;
+
+namespace OrderCloud.Catalyst
+{
+	public static class VertexRequestMapper
+	{
+		public static VertexCalculateTaxRequest ToVertexCalculateTaxRequest(this OrderWorksheet order, List<OrderPromotion> promosOnOrder, string companyCode, VertexSaleMessageType type)
+		{
+			var itemLines = order.LineItems.Select(li => ToVertexLineItem(li));
+			var shippingLines = order.ShipEstimateResponse.ShipEstimates.Select(se =>
+			{
+				var firstLi = order.LineItems.FirstOrDefault(li => li.ID == se.ShipEstimateItems.First().LineItemID);
+				Require.That(firstLi != null, new CatalystBaseException("InvalidOrderWorksheet", $"Invalid OrderWorksheet. Based on ShipEstimateItems, expected to find a LineItem with ID {se.ShipEstimateItems.First().LineItemID}", null, 400));
+				return ToVertexLineItem(se, firstLi.ShippingAddress);
+			});
+
+			return new VertexCalculateTaxRequest()
+			{
+				postingDate = DateTime.Now.ToString("yyyy-MM-dd"),
+				saleMessageType = type.ToString(),
+				transactionType = VertexTransactionType.SALE.ToString(),
+				transactionId = order.Order.ID,
+				seller = new VertexSeller()
+				{
+					company = companyCode
+				},
+				customer = new VertexCustomer()
+				{
+					customerCode = new VertexCustomerCode()
+					{
+						classCode = order.Order.FromUserID,
+						value = order.Order.FromUser.Email
+					},
+				},
+				lineItems = itemLines.Concat(shippingLines).ToList()
+			};
+		}
+
+		public static VertexLineItem ToVertexLineItem(LineItem lineItem)
+		{
+			return new VertexLineItem()
+			{
+				customer = new VertexCustomer()
+				{
+					destination = lineItem.ShippingAddress.ToVertexLocation(),
+				},
+				product = new VertexProduct()
+				{
+					productClass = lineItem.Product.ID,
+					value = lineItem.Product.Name
+				},
+				quantity = new VertexMeasure()
+				{
+					value = lineItem.Quantity
+				},
+				unitPrice = (double) lineItem.UnitPrice,
+				lineItemId = lineItem.ID,
+				extendedPrice = (double) lineItem.LineTotal // this takes precedence over quanitity and unit price in determining tax cost
+			};
+		}
+
+		public static VertexLineItem ToVertexLineItem(ShipEstimate shipEstimate, Address shipTo)
+		{
+			var selectedMethod = shipEstimate.ShipMethods.FirstOrDefault(m => m.ID == shipEstimate.SelectedShipMethodID);
+			Require.That(selectedMethod != null, new CatalystBaseException("InvalidOrderWorksheet", $"Invalid OrderWorksheet. Based on SelectedShipMethodID, expected to find a ShipMethod with ID {shipEstimate.SelectedShipMethodID}", null, 400));
+			return new VertexLineItem()
+			{
+				customer = new VertexCustomer()
+				{
+					destination = shipTo.ToVertexLocation(),
+				},
+				product = new VertexProduct()
+				{
+					productClass = "shipping_code",
+					value = selectedMethod.Name
+				},
+				quantity = new VertexMeasure()
+				{
+					value = 1
+				},
+				unitPrice = (double) selectedMethod.Cost,
+				lineItemId = shipEstimate.ID,
+			};
+		}
+
+		public static VertexLocation ToVertexLocation(this Address address)
+		{
+			return new VertexLocation()
+			{
+				streetAddress1 = address.Street1,
+				streetAddress2 = address.Street2,
+				city = address.City,
+				mainDivision = address.State,
+				postalCode = address.Zip,
+				country = address.Country
+			};
+		}
+	}
+}

library/OrderCloud.Catalyst/Integrations/Implementations/Vertex/Mappers/VertexResponseMapper.cs

@@ -0,0 +1,56 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace OrderCloud.Catalyst
+{
+	public static class VertexResponseMapper
+	{
+		public static bool IsShippingLineItem(this VertexResponseLineItem li) => li.product.productClass == "shipping_code";
+
+		public static OrderTaxCalculation ToOrderTaxCalculation(this VertexCalculateTaxResponse response)
+		{
+			var shippingLines = response.lineItems?.Where(li => li.IsShippingLineItem()) ?? new List<VertexResponseLineItem>();
+			var itemLines = response.lineItems?.Where(li => !li.IsShippingLineItem()) ?? new List<VertexResponseLineItem>();
+
+			return new OrderTaxCalculation()
+			{
+				OrderID = response.transactionId,
+				ExternalTransactionID = response.transactionId,
+				TotalTax = (decimal) response.totalTax,
+				LineItems = itemLines.Select(ToItemTaxDetails).ToList(),
+				OrderLevelTaxes = shippingLines.SelectMany(ToShippingTaxDetails).ToList()
+			};
+		}
+
+		public static IEnumerable<TaxDetails> ToShippingTaxDetails(this VertexResponseLineItem transactionLineModel)
+		{
+			return transactionLineModel.taxes?.Select(detail => detail.ToTaxDetails(transactionLineModel.lineItemId)) ?? new List<TaxDetails>();
+		}
+
+		public static LineItemTaxCalculation ToItemTaxDetails(this VertexResponseLineItem transactionLineModel)
+		{
+			return new LineItemTaxCalculation()
+			{
+				LineItemID = transactionLineModel.lineItemId,
+				LineItemTotalTax = (decimal) transactionLineModel.totalTax,
+				LineItemLevelTaxes = transactionLineModel.taxes?.Select(detail => detail.ToTaxDetails(null)).ToList() ?? new List<TaxDetails>()
+			};
+		}
+
+		public static TaxDetails ToTaxDetails(this VertexTax detail, string shipEstimateID)
+		{
+			return new TaxDetails()
+			{
+				Tax = (decimal) detail.calculatedTax,
+				Taxable = (decimal) detail.taxable,
+				Exempt = 0, // we don't get a property back for exempt
+				TaxDescription = detail.impositionType.value,
+				JurisdictionLevel = detail.jurisdiction.jurisdictionLevel.ToString(),
+				JurisdictionValue = detail.jurisdiction.value,
+				ShipEstimateID = shipEstimateID
+			};
+		}
+	}
+}

library/OrderCloud.Catalyst/Integrations/Implementations/Vertex/Models/VertexCalculateTaxRequest.cs

@@ -0,0 +1,75 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace OrderCloud.Catalyst
+{
+	public class VertexCalculateTaxRequest
+	{
+		public string saleMessageType { get; set; }
+		public VertexSeller seller { get; set; }
+		public VertexCustomer customer { get; set; }
+		public VertexDiscount discount { get; set; }
+		public List<VertexLineItem> lineItems { get; set; } = new List<VertexLineItem>();
+		public string postingDate { get; set; }
+		public string transactionId { get; set; }
+		public string transactionType { get; set; }
+	}
+
+	public class VertexSitusOverride
+	{
+		public VertexTaxingLocation taxingLocation { get; set; }
+	}
+
+
+	public enum VertexTaxingLocation
+	{
+		ADMINISTRATIVE_DESTINATION, ADMINISTRATIVE_ORIGIN, DESTINATION, PHYSICAL_ORIGIN
+	}
+
+	public class VertexImposition
+	{
+		public string impositionType { get; set; }
+		public VertexJurisdictionLevel value { get; set; }
+	}
+
+
+	public enum VertexTaxOverrideType
+	{
+		TAXABLE, NONTAXABLE
+	}
+
+	public class VertexTaxOverride
+	{
+		public VertexTaxOverrideType overrideType { get; set; }
+		public string overrideReasonCode { get; set; }
+	}
+
+	public enum VertexSaleMessageType
+	{
+		QUOTATION,
+		INVOICE,
+		DISTRIBUTE_TAX
+	}
+
+	public class VertexTaxRegistrations
+	{
+		public string taxRegistrationNumber { get; set; }
+		public string isoCountryCode { get; set; }
+		public string mainDivision { get; set; }
+		public string hasPhysicalPresenceIndicator { get; set; }
+		public string impositionType { get; set; }
+	}
+
+
+	public enum VertexLocationCustomsStatus
+	{
+		FREE_CIRCULATION, BONDED_WAREHOUSE, FREE_TRADE_ZONE, TEMPORARY_IMPORT, INWARD_PROCESSING_RELIEF, OUTWARD_PROCESSING_RELIEF
+	}
+
+	public class VertexExemptionCertificate
+	{
+		public string exemptionCertificateNumber { get; set; }
+		public string value { get; set; }
+	}
+}