@diagonal-finance/backend-sdk

Diagonal Backend SDK

SDK for easier interaction with the Diagonal backend.

👥 Contributing   |   🤝 Code of conduct   |   🔎 Issues

Diagonal SDK backend is a collection of classes which enables developers easier interaction with the Diagonal backend.

♜ Jest tests & common test coverage for all packages (npm test)
♞ ESLint & Prettier to keep the code neat and well organized (npm run format & npm run lint)
♝ Automatic deployment of documentation generated with typedocs

📦 Package

Package	Version	Downloads	Size
@diagonal-finance/backend-sdk (docs)

🛠 Installation

ESMModule:

npm install @diagonal-finance/backend-sdk

📜 Usage

ESModule:

Webhook:

import { Constants, DiagonalError, Event, EventType, Webhooks } from '@diagonal-finance/backend-sdk';

import express from 'express';

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
	let payload = req.body;
	let signatureHeader = req.headers[Constants.SIGNATURE_HEADER_KEY] as string;
	const endpointSecret = process.env.DIAGONAL_WEBHOOK_ENDPOINT_SECRET as string;

	let event: Event;

	try {
		event = Webhooks.constructEvent(payload, signatureHeader, endpointSecret);
	} catch (e) {
		if (e instanceof DiagonalError) {
			// Obtain error information
		}
		return res.sendStatus(400);
	}

	// Handle the event
	switch (event.type) {
		case EventType.SIGNATURE_CHARGE_REQUEST:
			console.log(`Charge signature request`);
			// Then define and call a method to handle the charge signature request
			// handleChargeSignatureRequest(event);
			break;
		case EventType.SUBSCRIPTION_CREATED:
			console.log(`Subscription was created`);
			// Then define and call a method to handle the subscription created event
			// handleSubscriptionCreated(event);
			break;
		default:
			// Unexpected event type
			console.log(`Unhandled event type ${event.type}.`);
	}

	// Return a 200 response to acknowledge receipt of the event
	res.sendStatus(200);
});

app.listen(3000, () => console.log('Running on port 3000'));

Handle charge request signature, signing locally (when having access to the signer private key)

import { Diagonal, ECDSASignature, Signature } from '@diagonal-finance/backend-sdk';

const apiKey = process.env.DIAGONAL_API_KEY as string;
const diagonal = new Diagonal(apiKey);

async function handleChargeSignatureRequest(signature: Signature): Promise<void> {
	const privateKey = process.env.SIGNER_PRIVATE_KEY as string;
	let ecdsaSignature: ECDSASignature;

	try {
		ecdsaSignature = diagonal.signatures.sign(signature, privateKey);
	} catch (e) {
		// if error is received at this step, operation should be aborted
		// the errors serve for information purposes
		console.log(`Error while signing event: ${e.message}`);

		// abort operation
		throw e;
	}

	const receivedCharge = signature.data.charge;

	const charge = await diagonal.charges.capture(receivedCharge.id, ecdsaSignature);
}

Handle charge request signature, signing remotely (for example when using AWS KMS)

import { Diagonal, Signature } from '@diagonal-finance/backend-sdk';

const apiKey = process.env.DIAGONAL_API_KEY as string;
const diagonal = new Diagonal(apiKey);

async function handleChargeSignatureRequest(signature: Signature): Promise<void> {
	let chargeDigest: string;

	try {
		chargeDigest = diagonal.signatures.createDigest(signature);
	} catch (e) {
		// if error is received at this step, operation should be aborted
		// the errors serve for information purposes
		console.log(`Error while creating charge digest: ${e.message}`);

		// abort operation
		throw e;
	}

	const receivedCharge = signature.data.charge;

	// handle external signing (i.e KMS)
	const ecdsaSignature = handleKmsSignining(chargeDigest);

	const charge = await diagonal.charges.capture(receivedCharge.id, ecdsaSignature);
}

Create Diagonal app instance

The Diagonal class accepts an apiKey and apiUrl inputs. The apiKey is your Diagonal API key, used for authentication to Diagonal backend. The apiUrl represents the API endpoint that should be used (TEST or PRODUCTION). By default, the production url (https://api.diagonal.finance) will be used.

import { Constants, Diagonal } from '@diagonal-finance/backend-sdk';

// connect to the TEST API
const diagonal = new Diagonal(apiKey, Constants.API_URL_TEST_ENVIRONMENT);

🛠 Development

Clone this repository and install the dependencies:

git clone https://github.com/diagonal-finance/backend-sdk.git
cd backend-sdk && npm i

📜 Usage

npm run lint # Syntax check with ESLint (yarn lint:fix to fix errors).
npm run format # Syntax check with Prettier (yarn prettier:fix to fix errors).
npm test # Run tests (with common coverage).
npm run build # Create a JS build.