Add primary sales backend api example (#2103)

immutable · Aug 21, 2024 · 1b827d0 · 1b827d0
1 parent a60950c
commit 1b827d0
Show file tree

Hide file tree

Showing 24 changed files with 1,133 additions and 0 deletions.
diff --git a/examples/primary-sales-backend-api/.env.example b/examples/primary-sales-backend-api/.env.example
@@ -0,0 +1,9 @@
+PORT=3000
+
+# Environment variables declared in this file are automatically made available to Prisma.
+# See the documentation for more detail: https://pris.ly/d/prisma-schema#accessing-environment-variables-from-the-schema
+
+# Prisma supports the native connection string format for PostgreSQL, MySQL, SQLite, SQL Server, MongoDB and CockroachDB.
+# See the documentation for all the connection string options: https://pris.ly/d/connection-strings
+
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/primarysales?schema=public"
diff --git a/examples/primary-sales-backend-api/.gitignore b/examples/primary-sales-backend-api/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+# Keep environment variables out of version control
+.env
+build
diff --git a/examples/primary-sales-backend-api/.nvmrc b/examples/primary-sales-backend-api/.nvmrc
@@ -0,0 +1 @@
+v20.16.0
diff --git a/examples/primary-sales-backend-api/README.md b/examples/primary-sales-backend-api/README.md
@@ -0,0 +1,40 @@
+# Example Primary Sales Webhook API
+
+This example shows how to implement the webhooks required for the [primary sales backend config](https://docs.immutable.com/products/zkEVM/checkout/widgets/primary-sales/backend/byo).
+
+## Pre-requisites
+
+* [NodeJS >= v20](https://nodejs.org/en)
+* [Docker](https://www.docker.com/)
+
+### Install dependencies
+
+Run `npm i`
+
+### Set environment variables
+
+Copy the `.env.example` file and rename it to `.env`.
+
+## Running the app
+
+1. Run `docker-compose up -d` to start the postgres DB at port 5432.
+2. Run `npx prisma migrate dev` and `npm run seed` to initialise the DB schema and seed it with data.
+3. `npm run dev` to start your server on port 3000
+
+## Webhook endpoints
+
+To see the list of endpoints this example serves, go to [the Swagger UI](http://localhost:3000/docs).
+
+Apart from the `/api/v1/products` endpoint which is used to list the products available in the DB, the rest of the endpoints correspond to the [Primary Sales backend config documentation](https://docs.immutable.com/products/zkEVM/checkout/widgets/primary-sales/backend/byo).
+
+
+## Example requests
+
+For your convenience, we have also added a postman collection under the `postman` folder. These contain sample requests for each endpoint, using the seeded products data.
+
+To run the requests, download [Postman](https://www.postman.com/) and import the collection.
+
+
+## TO-DO list
+
+* Add authentication for each endpoint, as per the [webhook authentication section](https://docs.immutable.com/products/zkEVM/checkout/widgets/primary-sales/backend/byo#webhook-authentication)
diff --git a/examples/primary-sales-backend-api/docker-compose.yml b/examples/primary-sales-backend-api/docker-compose.yml
@@ -0,0 +1,18 @@
+version: '3.8'
+
+services:
+  primary-sales-db:
+    image: postgres:14
+    ports:
+      - 5432:5432
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=postgres
+      - POSTGRES_DB=primarysales
+    restart: always
+    volumes:
+      - primary-sales-db-data:/data/postgres
+
+volumes:
+  primary-sales-db-data:
+
diff --git a/examples/primary-sales-backend-api/package.json b/examples/primary-sales-backend-api/package.json
@@ -0,0 +1,29 @@
+{
+  "devDependencies": {
+    "@types/node": "^22.2.0",
+    "fastify-tsconfig": "^2.0.0",
+    "nodemon": "^3.1.4",
+    "prisma": "^5.18.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "@fastify/autoload": "^5.10.0",
+    "@fastify/env": "^4.4.0",
+    "@fastify/swagger": "^8.15.0",
+    "@fastify/swagger-ui": "^4.1.0",
+    "@fastify/type-provider-typebox": "^4.0.0",
+    "@paralleldrive/cuid2": "^2.2.2",
+    "@prisma/client": "^5.18.0",
+    "fastify": "^4.28.1"
+  },
+  "prisma": {
+    "seed": "ts-node prisma/seed.ts"
+  },
+  "scripts": {
+    "build": "rm -rf build ; tsc",
+    "start": "node build/src/server.js",
+    "dev": "nodemon --exec ts-node src/server.ts",
+    "seed": "prisma db seed"
+  }
+}
diff --git a/examples/primary-sales-backend-api/postman/Primary sales BE.postman_collection.json b/examples/primary-sales-backend-api/postman/Primary sales BE.postman_collection.json
@@ -0,0 +1,189 @@
+{
+	"info": {
+		"_postman_id": "c754b503-fb61-4722-8fac-47fecc2efb3e",
+		"name": "Primary sales BE",
+		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+		"_exporter_id": "25754861"
+	},
+	"item": [
+		{
+			"name": "Quote",
+			"request": {
+				"method": "POST",
+				"header": [
+					{
+						"key": "QUOTE_API_KEY",
+						"value": "test_api_key",
+						"type": "text"
+					}
+				],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n  \"recipient_address\": \"0xdd9AAE1C317eE6EFEb0F3DB0A068e9Ed952a6CEB\",\n  \"products\": [\n    {\n      \"product_id\": \"vi7age4ku18qynwbk4wx90ge\",\n      \"quantity\": 1\n    }\n  ]\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "localhost:3000/api/v1/orders/quotes",
+					"host": [
+						"localhost"
+					],
+					"port": "3000",
+					"path": [
+						"api",
+						"v1",
+						"orders",
+						"quotes"
+					]
+				}
+			},
+			"response": []
+		},
+		{
+			"name": "Create order",
+			"request": {
+				"method": "POST",
+				"header": [
+					{
+						"key": "QUOTE_API_KEY",
+						"value": "test_api_key",
+						"type": "text"
+					}
+				],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n  \"recipient_address\": \"0xdd9AAE1C317eE6EFEb0F3DB0A068e9Ed952a6CEB\",\n  \"currency\": \"USDC\",\n  \"products\": [\n    {\n      \"product_id\": \"vi7age4ku18qynwbk4wx90ge\",\n      \"quantity\": 1\n    },\n    {\n      \"product_id\": \"jtwrclpj0v1zab865ne893hb\",\n      \"quantity\": 1\n    }\n  ]\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "localhost:3000/api/v1/sale-authorization",
+					"host": [
+						"localhost"
+					],
+					"port": "3000",
+					"path": [
+						"api",
+						"v1",
+						"sale-authorization"
+					]
+				}
+			},
+			"response": []
+		},
+		{
+			"name": "Expire an order",
+			"request": {
+				"method": "POST",
+				"header": [
+					{
+						"key": "QUOTE_API_KEY",
+						"value": "test_api_key",
+						"type": "text"
+					}
+				],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n  \"reference\": \"cm02a70000001updhnudm7bop\"\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "localhost:3000/api/v1/expire",
+					"host": [
+						"localhost"
+					],
+					"port": "3000",
+					"path": [
+						"api",
+						"v1",
+						"expire"
+					]
+				}
+			},
+			"response": []
+		},
+		{
+			"name": "Confirm",
+			"request": {
+				"method": "POST",
+				"header": [
+					{
+						"key": "QUOTE_API_KEY",
+						"value": "test_api_key",
+						"type": "text"
+					}
+				],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n  \"reference\": \"cm02apig000035o3ipwszr02z\",\n  \"tx_hash\": \"test\",\n  \"recipient_address\": \"0xdd9AAE1C317eE6EFEb0F3DB0A068e9Ed952a6CEB\"\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "localhost:3000/api/v1/confirm",
+					"host": [
+						"localhost"
+					],
+					"port": "3000",
+					"path": [
+						"api",
+						"v1",
+						"confirm"
+					]
+				}
+			},
+			"response": []
+		},
+		{
+			"name": "Products",
+			"protocolProfileBehavior": {
+				"disableBodyPruning": true
+			},
+			"request": {
+				"method": "GET",
+				"header": [
+					{
+						"key": "QUOTE_API_KEY",
+						"value": "test_api_key",
+						"type": "text"
+					}
+				],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n  \"reference\": \"cm02a70000001updhnudm7bop\",\n  \"tx_hash\": \"test\",\n  \"recipient_address\": \"0xdd9AAE1C317eE6EFEb0F3DB0A068e9Ed952a6CEB\"\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "localhost:3000/api/v1/products",
+					"host": [
+						"localhost"
+					],
+					"port": "3000",
+					"path": [
+						"api",
+						"v1",
+						"products"
+					]
+				}
+			},
+			"response": []
+		}
+	]
+}
diff --git a/examples/primary-sales-backend-api/prisma/migrations/20240820102407_init/migration.sql b/examples/primary-sales-backend-api/prisma/migrations/20240820102407_init/migration.sql
@@ -0,0 +1,65 @@
+-- CreateEnum
+CREATE TYPE "CurrencyType" AS ENUM ('crypto', 'fiat');
+
+-- CreateEnum
+CREATE TYPE "OrderStatus" AS ENUM ('reserved', 'completed', 'expired', 'failed');
+
+-- CreateTable
+CREATE TABLE "Product" (
+    "id" TEXT NOT NULL,
+    "collectionAddress" TEXT NOT NULL,
+    "contractType" TEXT NOT NULL,
+    "stockQuantity" INTEGER NOT NULL,
+
+    CONSTRAINT "Product_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Currency" (
+    "name" TEXT NOT NULL,
+    "type" "CurrencyType" NOT NULL,
+
+    CONSTRAINT "Currency_pkey" PRIMARY KEY ("name")
+);
+
+-- CreateTable
+CREATE TABLE "ProductPrice" (
+    "product_id" TEXT NOT NULL,
+    "currency_name" TEXT NOT NULL,
+    "amount" DOUBLE PRECISION NOT NULL,
+
+    CONSTRAINT "ProductPrice_pkey" PRIMARY KEY ("product_id","currency_name")
+);
+
+-- CreateTable
+CREATE TABLE "Order" (
+    "id" TEXT NOT NULL,
+    "status" "OrderStatus" NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "transactionHash" TEXT,
+    "recipientAddress" TEXT NOT NULL,
+
+    CONSTRAINT "Order_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "OrderLineItem" (
+    "order_id" TEXT NOT NULL,
+    "product_id" TEXT NOT NULL,
+    "quantity" INTEGER NOT NULL,
+
+    CONSTRAINT "OrderLineItem_pkey" PRIMARY KEY ("order_id","product_id")
+);
+
+-- AddForeignKey
+ALTER TABLE "ProductPrice" ADD CONSTRAINT "ProductPrice_product_id_fkey" FOREIGN KEY ("product_id") REFERENCES "Product"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "ProductPrice" ADD CONSTRAINT "ProductPrice_currency_name_fkey" FOREIGN KEY ("currency_name") REFERENCES "Currency"("name") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OrderLineItem" ADD CONSTRAINT "OrderLineItem_order_id_fkey" FOREIGN KEY ("order_id") REFERENCES "Order"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OrderLineItem" ADD CONSTRAINT "OrderLineItem_product_id_fkey" FOREIGN KEY ("product_id") REFERENCES "Product"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
diff --git a/examples/primary-sales-backend-api/prisma/migrations/migration_lock.toml b/examples/primary-sales-backend-api/prisma/migrations/migration_lock.toml
@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (i.e. Git)
+provider = "postgresql"