@henrylabs-interview/payment-processor 0.1.2 → 0.1.4

package/README.md

@@ -1,15 +1,151 @@
-# henry-labs/take-home
+# Henry Labs - Interview: Payment Processor
 
-To install dependencies:
+A lightweight payments SDK for creating and confirming checkouts, with built-in webhook support.
+
+This SDK simulates a real-world payment processing system, including fraud detection, transient errors, retries, and asynchronous authorization flows.
+
+---
+
+## Installation
 
 ```bash
 bun install
 ```
 
-To run:
+Build:
 
 ```bash
-bun run index.ts
+bun run build
+```
+
+---
+
+## Overview
+
+The SDK provides three primary capabilities:
+
+- Create a checkout
+- Confirm a checkout
+- Register webhook endpoints
+
+The system performs internal validation, fraud screening, and risk checks.
+Depending on system conditions, operations may:
+
+- Succeed immediately
+- Succeed asynchronously
+- Require a retry
+- Fail due to risk controls
+- Fail due to temporary system overload
+
+Consumers should always handle both synchronous responses and webhook events.
+
+---
+
+## Usage
+
+### Initialize
+
+```ts
+import { PaymentSDK } from 'henry-labs/take-home';
+
+const sdk = new PaymentSDK();
+```
+
+---
+
+## Create a Checkout
+
+```ts
+const response = await sdk.create({
+	amount: 1000,
+	currency: 'USD',
+	customerId: 'cust_123',
+});
+```
+
+### Behavior
+
+Creating a checkout may:
+
+- Return immediate approval
+- Return a pending authorization state
+- Return a retryable error
+- Return a fraud-related failure
+- Fail due to temporary internal errors
+
+If the checkout is authorized asynchronously, the final outcome will be delivered via webhook.
+
+---
+
+## Confirm a Checkout
+
+```ts
+const response = await sdk.confirm({
+	checkoutId: '...',
+	type: 'raw-card',
+	data: {
+		number: '4242424242424242',
+		expMonth: 12,
+		expYear: 2030,
+		cvc: '123',
+	},
+});
+```
+
+### Behavior
+
+Confirmation requests are subject to:
+
+- Card validation
+- Fraud screening
+- Retry conditions
+- System load conditions
+
+Confirmations may resolve immediately or asynchronously.
+Webhook handling is required to receive final outcomes in deferred cases.
+
+---
+
+## Webhooks
+
+You can register webhook endpoints to receive event notifications.
+
+```ts
+sdk.webhooks.createEndpoint({
+	url: 'https://example.com/webhooks',
+	event: 'checkout.confirm',
+	secret: 'whsec_...',
+});
 ```
 
-This project was created using `bun init` in bun v1.3.9. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### Webhook Events
+
+Events are emitted for:
+
+- Checkout creation
+- Checkout confirmation
+- Success outcomes
+- Failure outcomes
+
+Webhooks may be triggered for both synchronous and asynchronous results.
+
+All webhook deliveries are signed if a secret is provided.
+
+Consumers are responsible for verifying signatures and handling retries idempotently.
+
+---
+
+## Important Notes
+
+- Not all operations resolve immediately.
+- Some failures are retryable.
+- The system may simulate temporary overload conditions.
+- Fraud checks may result in blocked transactions.
+- Consumers should implement robust retry and webhook handling logic.
+
+---
+
+## Disclaimer
+
+This SDK is intended for evaluation and sandbox purposes only.
+It does not process real payments.

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export interface ClientOptions {
-    apiKey: string;
-}
-export declare class MySDK {
-    private apiKey;
-    constructor(options: ClientOptions);
-    getData(): Promise<unknown>;
+import { Checkout } from './resources/checkout';
+import { Webhooks } from './resources/webhooks';
+export declare class HenryTakeHomeSDK {
+    checkout: Checkout;
+    webhooks: Webhooks;
+    constructor(config: {
+        apiKey: string;
+    });
 }

package/dist/index.js

@@ -1,7 +1,20 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
 var __moduleCache = /* @__PURE__ */ new WeakMap;
 var __toCommonJS = (from) => {
   var entry = __moduleCache.get(from), desc;
@@ -29,20 +42,442 @@ var __export = (target, all) => {
 // src/index.ts
 var exports_src = {};
 __export(exports_src, {
-  MySDK: () => MySDK
+  HenryTakeHomeSDK: () => HenryTakeHomeSDK
 });
 module.exports = __toCommonJS(exports_src);
 
-class MySDK {
-  apiKey;
-  constructor(options) {
-    this.apiKey = options.apiKey;
+// src/utils/store.ts
+var path = new URL("../db-store/history.json", "file:///Users/aaroncassar/Projects/take-home/src/utils/store.ts");
+async function readHistory() {
+  const file = Bun.file(path);
+  if (!await file.exists()) {
+    return [];
+  }
+  const text = await file.text();
+  if (!text)
+    return [];
+  try {
+    return JSON.parse(text);
+  } catch {
+    return [];
+  }
+}
+
+// src/utils/crypto.ts
+var import_crypto = __toESM(require("crypto"));
+function generateID(length = 12) {
+  const digits = [];
+  const bytes = import_crypto.default.randomBytes(length);
+  for (let i = 0;i < length; i++) {
+    digits.push((bytes[i] ?? 0) % 10);
+  }
+  return parseInt(digits.join(""));
+}
+function hashToNumber(input, length = 12) {
+  if (length > 16) {
+    throw new Error("Length is greater than max length of 16!");
+  }
+  const hash = import_crypto.default.createHash("sha256").update(input).digest("hex");
+  return parseInt(hash.slice(0, length), 16);
+}
+function signPayload(payload, secret) {
+  return import_crypto.default.createHmac("sha256", secret).update(payload).digest("hex");
+}
+
+// src/utils/async.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/resources/webhooks.ts
+var INTERNAL_WEBHOOKS = [];
+
+class Webhooks {
+  async createEndpoint(params) {
+    for (const event of params.events) {
+      await sleep(Math.random() * 100);
+      INTERNAL_WEBHOOKS.push({
+        url: params.url,
+        event,
+        secret: params.secret
+      });
+    }
+    return true;
+  }
+}
+
+// src/resources/checkout.ts
+var INTERNAL_CHECKOUTS = {};
+var INTERNAL_CARDS = {};
+
+class Checkout {
+  async create(params) {
+    await sleep(Math.random() * 100);
+    const hashId = this.buildHistoryHash(params);
+    const history = await readHistory();
+    const sameRecords = history.filter((v) => v.id === hashId);
+    const validationFailure = this.validateCreate(params);
+    const response = validationFailure ?? this.processCreateDecision(params, hashId, sameRecords.length);
+    this.scheduleCreateWebhook(hashId, response);
+    await sleep(Math.random() * 2000);
+    return response;
+  }
+  async confirm(params) {
+    await sleep(Math.random() * 100);
+    const validationFailure = await this.validateConfirm(params);
+    const response = validationFailure ?? await this.processConfirmDecision(params);
+    this.scheduleConfirmWebhook(params, response);
+    await sleep(Math.random() * 2000);
+    return response;
+  }
+  validateCreate(params) {
+    if (params.amount <= 0) {
+      return {
+        status: "failure",
+        substatus: "500-error",
+        code: 500,
+        message: "Invalid amount"
+      };
+    }
+    if (params.currency === "JPY") {
+      return {
+        status: "failure",
+        substatus: "501-not-supported",
+        code: 501,
+        message: "This currency is currently not supported, please convert first."
+      };
+    }
+    if (Math.random() > 0.85) {
+      return {
+        status: "failure",
+        substatus: "500-error",
+        code: 500,
+        message: "An internal error occurred when creating checkout"
+      };
+    }
+    return null;
+  }
+  processCreateDecision(params, hashId, duplicateCount) {
+    const resCase = this.determineResponseCase(params.amount, duplicateCount);
+    if (resCase === "failure-retry") {
+      return {
+        status: "failure",
+        substatus: "503-retry",
+        code: 503,
+        message: "Server is busy, please retry the request"
+      };
+    }
+    if (resCase === "failure-fraud") {
+      return {
+        status: "failure",
+        substatus: "502-fraud",
+        code: 502,
+        message: "Potential fraud detected with this purchase"
+      };
+    }
+    const checkoutId = this.createCheckoutRecord(hashId);
+    if (resCase === "success-deferred") {
+      return {
+        status: "success",
+        substatus: "202-deferred",
+        code: 202,
+        message: "Authorizing, checkout information will likely be returned via webhook"
+      };
+    }
+    return {
+      status: "success",
+      substatus: "201-immediate",
+      code: 201,
+      message: "Approved",
+      data: {
+        checkoutId,
+        paymentMethodOptions: ["embedded", "raw-card"]
+      }
+    };
+  }
+  createCheckoutRecord(hashId) {
+    const checkoutId = generateID();
+    INTERNAL_CHECKOUTS[checkoutId] = {
+      historyRecordId: hashId
+    };
+    return checkoutId;
+  }
+  scheduleCreateWebhook(hashId, response) {
+    const webhookDelay = Math.random() * 3000;
+    setTimeout(() => {
+      if (response.status === "success" && response.substatus === "202-deferred") {
+        const isSuccess = Math.random() > 0.35;
+        if (isSuccess) {
+          const checkoutId = this.createCheckoutRecord(hashId);
+          this.sendWebhookResponse("checkout.create", {
+            status: "success",
+            substatus: "201-immediate",
+            code: 201,
+            message: "Approved",
+            data: {
+              checkoutId,
+              paymentMethodOptions: ["embedded", "raw-card"]
+            }
+          });
+        } else {
+          this.sendWebhookResponse("checkout.create", {
+            status: "failure",
+            substatus: "502-fraud",
+            code: 502,
+            message: "Potential fraud detected with this purchase"
+          });
+        }
+        return;
+      }
+      this.sendWebhookResponse("checkout.create", response);
+    }, webhookDelay);
+  }
+  buildHistoryHash(params) {
+    return hashToNumber(JSON.stringify({
+      type: "HISTORY_RECORD",
+      amount: params.amount,
+      currency: params.currency,
+      customerId: params.customerId
+    }));
+  }
+  async validateConfirm(params) {
+    if (!INTERNAL_CHECKOUTS[params.checkoutId]) {
+      return {
+        status: "failure",
+        substatus: "500-error",
+        code: 500,
+        message: "Invalid checkout ID"
+      };
+    }
+    if (params.type === "embedded") {
+      const stored = INTERNAL_CARDS[params.data.paymentToken];
+      if (!stored) {
+        return {
+          status: "failure",
+          substatus: "500-error",
+          code: 500,
+          message: "Invalid payment token"
+        };
+      }
+    }
+    if (params.type === "raw-card") {
+      const { number, expMonth, expYear, cvc } = params.data;
+      if (!this.isValidCardNumber(number)) {
+        return {
+          status: "failure",
+          substatus: "502-fraud",
+          code: 502,
+          message: "Invalid card number"
+        };
+      }
+      if (!this.isValidExpiry(expMonth, expYear)) {
+        return {
+          status: "failure",
+          substatus: "503-retry",
+          code: 503,
+          message: "Card expired"
+        };
+      }
+      if (!/^\d{3,4}$/.test(cvc)) {
+        return {
+          status: "failure",
+          substatus: "502-fraud",
+          code: 502,
+          message: "Invalid CVC"
+        };
+      }
+    }
+    return null;
+  }
+  async processConfirmDecision(params) {
+    const decision = Math.random();
+    if (decision > 0.85) {
+      return {
+        status: "failure",
+        substatus: "502-fraud",
+        code: 502,
+        message: "Potential fraud detected with this purchase"
+      };
+    }
+    if (decision > 0.65) {
+      return {
+        status: "failure",
+        substatus: "503-retry",
+        code: 503,
+        message: "Server is busy, please retry the request"
+      };
+    }
+    if (decision > 0.35) {
+      return {
+        status: "success",
+        substatus: "202-deferred",
+        code: 202,
+        message: "Authorizing, purchase information will likely be returned via webhook"
+      };
+    }
+    return this.buildInstantConfirmSuccess(params.checkoutId);
+  }
+  async buildInstantConfirmSuccess(checkoutId) {
+    const { historyRecordId } = INTERNAL_CHECKOUTS[checkoutId] ?? {};
+    if (!historyRecordId) {
+      return {
+        status: "failure",
+        substatus: "500-error",
+        code: 500,
+        message: "Missing history record"
+      };
+    }
+    const history = await readHistory();
+    const record = history.find((v) => v.id === historyRecordId);
+    if (!record) {
+      return {
+        status: "failure",
+        substatus: "500-error",
+        code: 500,
+        message: "Missing history record"
+      };
+    }
+    const confirmationId = hashToNumber(JSON.stringify({
+      type: "CONFIRMATION_ID",
+      amount: record.amount,
+      currency: record.currency,
+      customerId: record.customerId
+    }));
+    return {
+      status: "success",
+      substatus: "201-immediate",
+      code: 201,
+      message: "Approved",
+      data: {
+        confirmationId,
+        amount: record.amount,
+        currency: record.currency,
+        customerId: record.customerId ?? undefined
+      }
+    };
   }
-  async getData() {
-    return fetch("https://api.example.com/data", {
-      headers: {
-        Authorization: `Bearer ${this.apiKey}`
+  scheduleConfirmWebhook(params, response) {
+    const webhookDelay = Math.random() * 3000;
+    setTimeout(() => {
+      if (response.status === "success" && response.substatus === "202-deferred") {
+        const isSuccess = Math.random() > 0.35;
+        if (isSuccess) {
+          this.buildInstantConfirmSuccess(params.checkoutId).then((finalResponse) => {
+            this.sendWebhookResponse("checkout.confirm", finalResponse);
+          });
+        } else {
+          this.sendWebhookResponse("checkout.confirm", {
+            status: "failure",
+            substatus: "502-fraud",
+            code: 502,
+            message: "Potential fraud detected with this purchase"
+          });
+        }
+        return;
       }
-    }).then((res) => res.json());
+      this.sendWebhookResponse("checkout.confirm", response);
+    }, webhookDelay);
+  }
+  isValidCardNumber(number) {
+    if (number === "4242424242424242")
+      return true;
+    if (!/^\d{13,19}$/.test(number))
+      return false;
+    let sum = 0;
+    let shouldDouble = false;
+    for (let i = number.length - 1;i >= 0; i--) {
+      let digit = parseInt(number[i] ?? "");
+      if (shouldDouble) {
+        digit *= 2;
+        if (digit > 9)
+          digit -= 9;
+      }
+      sum += digit;
+      shouldDouble = !shouldDouble;
+    }
+    return sum % 10 === 0;
+  }
+  isValidExpiry(month, year) {
+    if (month < 1 || month > 12)
+      return false;
+    const now = new Date;
+    const expiry = new Date(year, month - 1);
+    return expiry > now;
+  }
+  determineResponseCase(amount, sameRecords) {
+    let immediateWeight = 65;
+    let deferredWeight = 20;
+    let retryWeight = 10;
+    let fraudWeight = 5;
+    immediateWeight -= sameRecords * 10;
+    deferredWeight += sameRecords * 5;
+    retryWeight += sameRecords * 5;
+    fraudWeight += sameRecords * 5;
+    if (amount > 1000) {
+      deferredWeight += 10;
+      retryWeight += 5;
+    }
+    if (amount > 5000) {
+      immediateWeight -= 10;
+      retryWeight += 10;
+      fraudWeight += 10;
+    }
+    if (amount > 1e4) {
+      fraudWeight += 20;
+    }
+    immediateWeight = Math.max(0, immediateWeight);
+    deferredWeight = Math.max(0, deferredWeight);
+    retryWeight = Math.max(0, retryWeight);
+    fraudWeight = Math.max(0, fraudWeight);
+    const total = immediateWeight + deferredWeight + retryWeight + fraudWeight;
+    const rand = Math.random() * total;
+    if (rand < immediateWeight) {
+      return "success-immediate";
+    }
+    if (rand < immediateWeight + deferredWeight) {
+      return "success-deferred";
+    }
+    if (rand < immediateWeight + deferredWeight + retryWeight) {
+      return "failure-retry";
+    }
+    return "failure-fraud";
+  }
+  async sendWebhookResponse(baseType, response) {
+    const statusSuffix = response.status === "success" ? "success" : "failure";
+    const eventType = `${baseType}.${statusSuffix}`;
+    const matchingTypes = ["checkout", baseType, eventType];
+    const hooks = INTERNAL_WEBHOOKS.filter((w) => matchingTypes.includes(w.event));
+    const event = {
+      id: crypto.randomUUID(),
+      type: eventType,
+      createdAt: Date.now(),
+      data: response
+    };
+    const payload = JSON.stringify(event);
+    await Promise.allSettled(hooks.map(async (hook) => {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (hook.secret) {
+        headers["webhook-signature"] = signPayload(payload, hook.secret);
+      }
+      await fetch(hook.url, {
+        method: "POST",
+        headers,
+        body: payload
+      });
+    }));
+    return true;
+  }
+}
+
+// src/index.ts
+class HenryTakeHomeSDK {
+  checkout;
+  webhooks;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("Henry: apiKey is required");
+    }
+    this.checkout = new Checkout;
+    this.webhooks = new Webhooks;
   }
 }

package/dist/resources/checkout.d.ts

@@ -0,0 +1,100 @@
+type CheckoutCreateResponse = CheckoutCreateSuccessDeferred | CheckoutCreateSuccessImmediate | CheckoutCreateFailure;
+interface CheckoutCreateGeneric {
+    status: 'success' | 'failure';
+    code: number;
+    message: string;
+}
+interface CheckoutCreateSuccessDeferred extends CheckoutCreateGeneric {
+    status: 'success';
+    substatus: '202-deferred';
+}
+interface CheckoutCreateSuccessImmediate extends CheckoutCreateGeneric {
+    status: 'success';
+    substatus: '201-immediate';
+    data: {
+        checkoutId: number;
+        paymentMethodOptions: string[];
+    };
+}
+interface CheckoutCreateFailure extends CheckoutCreateGeneric {
+    status: 'failure';
+    substatus: '500-error' | '501-not-supported' | '502-fraud' | '503-retry';
+}
+type CheckoutConfirmParams = CheckoutConfirmParamsEmbedded | CheckoutConfirmParamsRawCard;
+interface CheckoutConfirmParamsGeneric {
+    checkoutId: string;
+    type: 'embedded' | 'raw-card';
+}
+interface CheckoutConfirmParamsEmbedded extends CheckoutConfirmParamsGeneric {
+    type: 'embedded';
+    data: {
+        paymentToken: string;
+    };
+}
+interface CheckoutConfirmParamsRawCard extends CheckoutConfirmParamsGeneric {
+    type: 'raw-card';
+    data: {
+        number: string;
+        expMonth: number;
+        expYear: number;
+        cvc: string;
+    };
+}
+type CheckoutConfirmResponse = CheckoutConfirmSuccessDeferred | CheckoutConfirmSuccessImmediate | CheckoutConfirmFailure;
+interface CheckoutConfirmGeneric {
+    status: 'success' | 'failure';
+    code: number;
+    message: string;
+}
+interface CheckoutConfirmSuccessDeferred extends CheckoutConfirmGeneric {
+    status: 'success';
+    substatus: '202-deferred';
+}
+interface CheckoutConfirmSuccessImmediate extends CheckoutConfirmGeneric {
+    status: 'success';
+    substatus: '201-immediate';
+    data: {
+        confirmationId: number;
+        amount: number;
+        currency: string;
+        customerId?: string;
+    };
+}
+interface CheckoutConfirmFailure extends CheckoutConfirmGeneric {
+    status: 'failure';
+    substatus: '500-error' | '502-fraud' | '503-retry';
+}
+export declare class Checkout {
+    /**
+     * Create a new checkout session
+     * @param amount - The amount for the checkout
+     * @param currency - The curreny type (note: not all are supported atm)
+     * @param customerId - Optional customer ID, used for unique customer identification
+     * @returns The response from the checkout creation
+     */
+    create(params: {
+        amount: number;
+        currency: 'USD' | 'EUR' | 'JPY';
+        customerId?: string;
+    }): Promise<CheckoutCreateResponse>;
+    /**
+     * Confirm a checkout session
+     * @param params - Either embedded or raw card checkout confirmation parameters
+     * @returns - The response from the checkout confirmation
+     */
+    confirm(params: CheckoutConfirmParams): Promise<CheckoutConfirmResponse>;
+    private validateCreate;
+    private processCreateDecision;
+    private createCheckoutRecord;
+    private scheduleCreateWebhook;
+    private buildHistoryHash;
+    private validateConfirm;
+    private processConfirmDecision;
+    private buildInstantConfirmSuccess;
+    private scheduleConfirmWebhook;
+    private isValidCardNumber;
+    private isValidExpiry;
+    private determineResponseCase;
+    private sendWebhookResponse;
+}
+export {};

package/dist/resources/webhooks.d.ts

@@ -0,0 +1,24 @@
+export type EventType = 'checkout' | 'checkout.create' | 'checkout.create.success' | 'checkout.create.failure' | 'checkout.confirm' | 'checkout.confirm.success' | 'checkout.confirm.failure';
+export interface WebhookEvent {
+    id: string;
+    type: EventType;
+    createdAt: number;
+    data: Record<string, any>;
+}
+export declare const INTERNAL_WEBHOOKS: {
+    url: string;
+    event: EventType;
+    secret?: string;
+}[];
+export declare class Webhooks {
+    /**
+     * Registers a new webhook endpoint for the specified events
+     * @param params - The webhook parameters including URL, events, and optional secret
+     * @returns A promise that resolves to a boolean indicating successful registration
+     */
+    createEndpoint(params: {
+        url: string;
+        events: EventType[];
+        secret?: string;
+    }): Promise<boolean>;
+}

package/dist/utils/async.d.ts

@@ -0,0 +1 @@
+export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/utils/crypto.d.ts

@@ -0,0 +1,3 @@
+export declare function generateID(length?: number): number;
+export declare function hashToNumber(input: string, length?: number): number;
+export declare function signPayload(payload: string, secret: string): string;

package/dist/utils/store.d.ts

@@ -0,0 +1,17 @@
+export type HistoryRecord = {
+    id: number;
+    amount: number;
+    currency: 'USD' | 'EUR' | 'JPY';
+    customerId: string | null;
+    updatedAt: number;
+    createdAt: number;
+    confirmed: boolean;
+};
+/**
+ * Reads all history records from the JSON store.
+ */
+export declare function readHistory(): Promise<HistoryRecord[]>;
+/**
+ * Writes a new record to the JSON store.
+ */
+export declare function writeHistory(params: Omit<HistoryRecord, 'updatedAt'>): Promise<HistoryRecord>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henrylabs-interview/payment-processor",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"type": "module",
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.mjs",
@@ -17,7 +17,8 @@
 	],
 	"scripts": {
 		"build": "bun run build.ts && bunx tsc -p tsconfig.build.json",
-		"dev": "bun run src/index.ts"
+		"dev": "bun run src/index.ts",
+		"publish": "bun run build && npm publish --access public"
 	},
 	"devDependencies": {
 		"@types/bun": "latest",