@henrylabs-interview/payments 0.2.16

package/README.md

@@ -0,0 +1,205 @@
+# Henry Labs – Interview: Payment Processor
+
+A lightweight payments SDK for creating and confirming checkouts, with built-in webhook support and an embeddable checkout UI.
+
+This SDK simulates a real-world payment processing system, including:
+
+- Fraud detection
+- Transient system errors
+- Retry scenarios
+- Asynchronous authorization flows
+
+It is designed to test robustness, error handling, and webhook integration.
+
+---
+
+## Installation
+
+```bash
+bun install
+```
+
+Build:
+
+```bash
+bun run build
+```
+
+---
+
+# Overview
+
+The SDK provides:
+
+- Checkout creation
+- Checkout confirmation
+- Webhook endpoint registration
+- Embeddable checkout UI (frontend)
+- API key validation
+
+The system performs internal validation, fraud screening, and simulated load conditions.
+
+Operations may:
+
+- Succeed immediately
+- Resolve asynchronously
+- Require retries
+- Fail due to fraud controls
+- Fail due to temporary system overload
+
+---
+
+# Usage
+
+---
+
+## Initialize (Backend)
+
+```ts
+import { PaymentProcessor } from '@henrylabs-interview/payments';
+
+const processor = new PaymentProcessor({
+	apiKey: ...,
+});
+```
+
+# Checkout API
+
+Available under:
+
+```ts
+processor.checkout;
+```
+
+---
+
+## Create a Checkout
+
+```ts
+const response = await processor.checkout.create({
+	amount: 1000,
+	currency: 'USD',
+	customerId: 'cust_123',
+});
+```
+
+---
+
+## Confirm a Checkout (Backend)
+
+```ts
+const response = await processor.checkout.confirm({
+	checkoutId: ...,
+	type: 'raw-card',
+	data: {
+		number: ...,
+		expMonth: XX,
+		expYear: XXXX,
+		cvc: XXX,
+	},
+});
+```
+
+# Embedded Checkout (Frontend)
+
+The SDK provides an optional embeddable checkout UI for collecting card details in the browser.
+
+---
+
+## Initialize Embedded Checkout
+
+```ts
+import { EmbeddedCheckout } from '@henrylabs-interview/payments';
+
+const embedded = new EmbeddedCheckout({
+	checkoutId: 'chk_123',
+});
+```
+
+---
+
+## Render Embedded Checkout
+
+```ts
+embedded.render('#checkout-container', (paymentToken) => {
+	console.log('Received payment token:', paymentToken);
+
+	// Send token to backend for confirmation
+});
+```
+
+### Parameters
+
+| Parameter            | Description                           |
+| -------------------- | ------------------------------------- |
+| `containerElementId` | ID of DOM element to render into      |
+| `callbackFn`         | Called with a generated payment token |
+
+### Behavior
+
+- Renders a secure card collection UI
+- Collects card number, expiry, and CVC
+- Generates a payment token
+- Returns the token via callback
+- Token should be sent to your backend for confirmation
+
+The embedded checkout is intended for **browser environments only**.
+
+---
+
+# Webhooks
+
+Available under:
+
+```ts
+processor.webhooks;
+```
+
+---
+
+## Register Webhook Endpoint
+
+```ts
+processor.webhooks.createEndpoint({
+	url: 'https://example.com/webhooks',
+	event: 'checkout.confirm',
+	secret: 'whsec_...',
+});
+```
+
+---
+
+## Webhook Events
+
+Events may be emitted for:
+
+- `checkout.create`
+- `checkout.confirm`
+- `checkout.success`
+- `checkout.failure`
+
+Events are triggered for:
+
+- Immediate outcomes
+- Asynchronous resolutions
+- Retry scenarios
+
+---
+
+## Webhook Security
+
+If a secret is provided:
+
+- Deliveries are signed
+- Consumers must verify signatures
+- Handlers must be idempotent
+
+Retries may occur if delivery fails.
+
+---
+
+# Disclaimer
+
+This SDK is intended for evaluation and sandbox purposes only.
+
+It does **not** process real payments and should not be used in production.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { Checkout } from './resources/checkout';
+import { Webhooks } from './resources/webhooks';
+export declare class PaymentProcessor {
+    checkout: Checkout;
+    webhooks: Webhooks;
+    private VALID_API_KEYS;
+    constructor(config: {
+        apiKey: string;
+    });
+}
+export declare class EmbeddedCheckout {
+    private checkoutId;
+    constructor(config: {
+        checkoutId: string;
+    });
+    /**
+     * Renders the embedded checkout UI
+     * @param containerElementId - The ID of the container element where the checkout UI will be rendered
+     * @param callbackFn - Callback function to handle the payment token
+     * @returns - Whether the UI rendered successfully
+     */
+    render(containerElementId: string, callbackFn: (paymentToken: string) => void): Promise<boolean>;
+}

package/dist/index.js

@@ -0,0 +1,36 @@
+import { Checkout } from './resources/checkout';
+import { renderEmbeddedCheckout } from './resources/embedded';
+import { Webhooks } from './resources/webhooks';
+export class PaymentProcessor {
+    checkout;
+    webhooks;
+    VALID_API_KEYS = ['824c951e-dfac-4342-8e03', '3f67e17a-880a-463b-a667', '78254d40-623a-48c5-b83f'];
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('Henry: apiKey is required');
+        }
+        if (!this.VALID_API_KEYS.includes(config.apiKey)) {
+            throw new Error('Henry: Invalid apiKey provided');
+        }
+        this.checkout = new Checkout();
+        this.webhooks = new Webhooks();
+    }
+}
+export class EmbeddedCheckout {
+    checkoutId;
+    constructor(config) {
+        if (!config.checkoutId) {
+            throw new Error('Henry: checkoutId is required');
+        }
+        this.checkoutId = config.checkoutId;
+    }
+    /**
+     * Renders the embedded checkout UI
+     * @param containerElementId - The ID of the container element where the checkout UI will be rendered
+     * @param callbackFn - Callback function to handle the payment token
+     * @returns - Whether the UI rendered successfully
+     */
+    render(containerElementId, callbackFn) {
+        return renderEmbeddedCheckout(containerElementId, this.checkoutId, callbackFn);
+    }
+}

package/dist/resources/checkout.d.ts

@@ -0,0 +1,100 @@
+type CheckoutCreateResponse = CheckoutCreateSuccessDeferred | CheckoutCreateSuccessImmediate | CheckoutCreateFailure;
+interface CheckoutCreateGeneric {
+    _reqId: string;
+    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: string;
+        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 {
+    _reqId: string;
+    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: string;
+        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 determineResponseCase;
+    private sendWebhookResponse;
+}
+export {};

package/dist/resources/checkout.js

@@ -0,0 +1,451 @@
+import { readHistory, writeHistory } from '../utils/store';
+import { generateTimeBasedID, genReqId, hashToString, signPayload } from '../utils/crypto';
+import { INTERNAL_WEBHOOKS } from './webhooks';
+import { sleep } from '../utils/async';
+import { isValidCardNumber, isValidExpiry } from '../utils/card';
+// checkoutId -> { historyRecordId }
+const INTERNAL_CHECKOUTS = {};
+export 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
+     */
+    async create(params) {
+        await sleep(Math.random() * 100);
+        const hashId = await this.buildHistoryHash(params);
+        const history = await readHistory();
+        const sameRecords = history.filter((v) => v.id === hashId);
+        // ---------------------------------------
+        // Phase 1: Validation
+        // ---------------------------------------
+        const validationFailure = this.validateCreate(params);
+        // ---------------------------------------
+        // Phase 2: Business Logic
+        // ---------------------------------------
+        const response = validationFailure ?? (await this.processCreateDecision(params, hashId, sameRecords.length));
+        // ---------------------------------------
+        // Phase 3: Webhook Scheduling
+        // ---------------------------------------
+        this.scheduleCreateWebhook(hashId, response);
+        // Add to history records
+        await writeHistory({
+            id: hashId,
+            amount: params.amount,
+            currency: params.currency,
+            customerId: params.customerId ?? null,
+        });
+        // Simulate API latency
+        await sleep(Math.random() * 2000);
+        return response;
+    }
+    /**
+     * Confirm a checkout session
+     * @param params - Either embedded or raw card checkout confirmation parameters
+     * @returns - The response from the checkout confirmation
+     */
+    async confirm(params) {
+        await sleep(Math.random() * 100);
+        // ---------------------------------------
+        // Phase 1: Validation (no early returns)
+        // ---------------------------------------
+        const validationFailure = await this.validateConfirm(params);
+        // ---------------------------------------
+        // Phase 2: Business Logic
+        // ---------------------------------------
+        const response = validationFailure ?? (await this.processConfirmDecision(params));
+        // ---------------------------------------
+        // Phase 3: Async Webhook Emission
+        // ---------------------------------------
+        this.scheduleConfirmWebhook(params, response);
+        // Simulate response delay
+        await sleep(Math.random() * 2000);
+        return response;
+    }
+    validateCreate(params) {
+        if (params.amount <= 0) {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '500-error',
+                code: 500,
+                message: 'Invalid amount',
+            };
+        }
+        if (params.currency === 'JPY') {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '501-not-supported',
+                code: 501,
+                message: 'This currency is currently not supported, please convert to another supported currency first.',
+            };
+        }
+        // Simulated stupid internal failures
+        if ((params.customerId ?? '').length === crypto.randomUUID().length || (params.customerId ?? '').includes('-') || params.customerId === '') {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '500-error',
+                code: 500,
+                message: 'An internal error occurred when creating checkout',
+            };
+        }
+        return null;
+    }
+    async processCreateDecision(params, hashId, duplicateCount) {
+        const resCase = this.determineResponseCase(params.amount, duplicateCount);
+        if (resCase === 'failure-retry') {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '503-retry',
+                code: 503,
+                message: 'Server is busy, please retry the request',
+            };
+        }
+        if (resCase === 'failure-fraud') {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '502-fraud',
+                code: 502,
+                message: 'Potential fraud detected with this purchase',
+            };
+        }
+        const checkoutId = await this.createCheckoutRecord(hashId);
+        if (resCase === 'success-deferred') {
+            return {
+                _reqId: genReqId(),
+                status: 'success',
+                substatus: '202-deferred',
+                code: 202,
+                message: 'Authorizing, checkout information will likely be returned via webhook',
+            };
+        }
+        return {
+            _reqId: genReqId(),
+            status: 'success',
+            substatus: '201-immediate',
+            code: 201,
+            message: 'Approved',
+            data: {
+                checkoutId,
+                paymentMethodOptions: ['embedded', 'raw-card'],
+            },
+        };
+    }
+    async createCheckoutRecord(hashId) {
+        const checkoutId = `cki_${await generateTimeBasedID('checkout')}`;
+        INTERNAL_CHECKOUTS[`${checkoutId}`] = {
+            historyRecordId: hashId,
+        };
+        return checkoutId;
+    }
+    scheduleCreateWebhook(hashId, response) {
+        const webhookDelay = Math.random() * 3000;
+        setTimeout(async () => {
+            // Deferred flow resolves later
+            if (response.status === 'success' && response.substatus === '202-deferred') {
+                if (Math.random() > 0.2) {
+                    const checkoutId = await this.createCheckoutRecord(hashId);
+                    this.sendWebhookResponse('checkout.create', {
+                        _reqId: response._reqId,
+                        status: 'success',
+                        substatus: '201-immediate',
+                        code: 201,
+                        message: 'Approved',
+                        data: {
+                            checkoutId,
+                            paymentMethodOptions: ['embedded', 'raw-card'],
+                        },
+                    });
+                }
+                else if (Math.random() > 0.05) {
+                    this.sendWebhookResponse('checkout.create', {
+                        _reqId: response._reqId,
+                        status: 'failure',
+                        substatus: '503-retry',
+                        code: 503,
+                        message: 'Server error, please retry the request',
+                    });
+                }
+                else {
+                    this.sendWebhookResponse('checkout.create', {
+                        _reqId: response._reqId,
+                        status: 'failure',
+                        substatus: '502-fraud',
+                        code: 502,
+                        message: 'Potential fraud detected with this purchase',
+                    });
+                }
+                return;
+            }
+            // Immediate success or failure
+            this.sendWebhookResponse('checkout.create', response);
+        }, webhookDelay);
+    }
+    async buildHistoryHash(params) {
+        return await hashToString(JSON.stringify({
+            type: 'HISTORY_RECORD',
+            amount: params.amount,
+            currency: params.currency,
+            customerId: params.customerId,
+        }));
+    }
+    ///
+    async validateConfirm(params) {
+        if (`${params.checkoutId}`.length !== 20 || !`${params.checkoutId}`.startsWith('cki_')) {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '500-error',
+                code: 500,
+                message: 'Invalid checkout ID',
+            };
+        }
+        if (!INTERNAL_CHECKOUTS[`${params.checkoutId}`]) {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '503-retry',
+                code: 504,
+                message: 'Expired checkout ID',
+            };
+        }
+        if (params.type === 'embedded') {
+            if (params.data.paymentToken.length !== 20 || !params.data.paymentToken.startsWith('pmt_')) {
+                return {
+                    _reqId: genReqId(),
+                    status: 'failure',
+                    substatus: '500-error',
+                    code: 500,
+                    message: 'Invalid payment token',
+                };
+            }
+        }
+        if (params.type === 'embedded') {
+            const paymentToken = `pmt_${await generateTimeBasedID('payment-token')}`;
+            if (params.data.paymentToken !== paymentToken) {
+                return {
+                    _reqId: genReqId(),
+                    status: 'failure',
+                    substatus: '503-retry',
+                    code: 503,
+                    message: 'Expired payment token',
+                };
+            }
+        }
+        if (params.type === 'raw-card') {
+            const { number, expMonth, expYear, cvc } = params.data;
+            if (!isValidCardNumber(number)) {
+                return {
+                    _reqId: genReqId(),
+                    status: 'failure',
+                    substatus: '500-error',
+                    code: 500,
+                    message: 'Invalid card number',
+                };
+            }
+            if (!isValidExpiry(expMonth, expYear)) {
+                return {
+                    _reqId: genReqId(),
+                    status: 'failure',
+                    substatus: '500-error',
+                    code: 500,
+                    message: 'Card expired',
+                };
+            }
+            if (!/^\d{3,4}$/.test(cvc)) {
+                return {
+                    _reqId: genReqId(),
+                    status: 'failure',
+                    substatus: '500-error',
+                    code: 500,
+                    message: 'Invalid CVC',
+                };
+            }
+        }
+        return null;
+    }
+    async processConfirmDecision(params) {
+        const decision = Math.random();
+        if (decision > 0.95) {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '502-fraud',
+                code: 502,
+                message: 'Potential fraud detected with this purchase',
+            };
+        }
+        if (decision > 0.65) {
+            return {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '503-retry',
+                code: 503,
+                message: 'Server is busy, please retry the request',
+            };
+        }
+        if (decision > 0.35) {
+            return {
+                _reqId: genReqId(),
+                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 {
+                _reqId: genReqId(),
+                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 {
+                _reqId: genReqId(),
+                status: 'failure',
+                substatus: '500-error',
+                code: 500,
+                message: 'Missing history record',
+            };
+        }
+        const confirmationId = 'cof_' +
+            (await hashToString(JSON.stringify({
+                type: 'CONFIRMATION_ID',
+                amount: record.amount,
+                currency: record.currency,
+                customerId: record.customerId,
+            })));
+        return {
+            _reqId: genReqId(),
+            status: 'success',
+            substatus: '201-immediate',
+            code: 201,
+            message: 'Approved',
+            data: {
+                confirmationId,
+                amount: record.amount,
+                currency: record.currency,
+                customerId: record.customerId ?? undefined,
+            },
+        };
+    }
+    scheduleConfirmWebhook(params, response) {
+        const webhookDelay = Math.random() * 3000;
+        setTimeout(() => {
+            if (response.status === 'success' && response.substatus === '202-deferred') {
+                if (Math.random() > 0.2) {
+                    this.buildInstantConfirmSuccess(params.checkoutId).then((finalResponse) => {
+                        this.sendWebhookResponse('checkout.confirm', finalResponse);
+                    });
+                }
+                else if (Math.random() > 0.05) {
+                    this.sendWebhookResponse('checkout.confirm', {
+                        _reqId: response._reqId,
+                        status: 'failure',
+                        substatus: '503-retry',
+                        code: 503,
+                        message: 'Server error, please retry the request',
+                    });
+                }
+                else {
+                    this.sendWebhookResponse('checkout.confirm', {
+                        _reqId: response._reqId,
+                        status: 'failure',
+                        substatus: '502-fraud',
+                        code: 502,
+                        message: 'Potential fraud detected with this purchase',
+                    });
+                }
+                return;
+            }
+            this.sendWebhookResponse('checkout.confirm', response);
+        }, webhookDelay);
+    }
+    //
+    determineResponseCase(amount, sameRecords) {
+        // --- Base probabilities ---
+        let immediateWeight = 65;
+        let deferredWeight = 20;
+        let retryWeight = 10;
+        let fraudWeight = 0;
+        // --- Adjust based on repeated attempts ---
+        immediateWeight -= sameRecords * 10;
+        deferredWeight += sameRecords * 5;
+        retryWeight += sameRecords * 5;
+        fraudWeight += sameRecords * 15;
+        // --- Adjust based on amount ---
+        if (amount > 1000) {
+            deferredWeight += sameRecords * 5 + 10;
+            retryWeight += sameRecords * 5 + 10;
+        }
+        if (amount > 5000) {
+            immediateWeight -= sameRecords * 5 + 15;
+            retryWeight += sameRecords * 5 + 30;
+            fraudWeight += sameRecords * 10;
+        }
+        if (amount > 10000) {
+            fraudWeight += sameRecords * 30;
+        }
+        // Ensure no negative weights
+        immediateWeight = Math.max(0, immediateWeight);
+        deferredWeight = Math.max(0, deferredWeight);
+        retryWeight = Math.max(0, retryWeight);
+        fraudWeight = Math.max(0, fraudWeight);
+        // --- Weighted random selection ---
+        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}`;
+        // Build all matching event types hierarchically
+        const matchingTypes = ['checkout', baseType, eventType];
+        const hooks = INTERNAL_WEBHOOKS.filter((w) => matchingTypes.includes(w.event));
+        const event = {
+            uid: `_${genReqId()}_`,
+            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['x-henry-signature'] = signPayload(payload, hook.secret);
+            }
+            await fetch(hook.url, {
+                method: 'POST',
+                headers,
+                body: payload,
+            });
+        }));
+        return true;
+    }
+}

package/dist/resources/embedded.d.ts

@@ -0,0 +1 @@
+export declare function renderEmbeddedCheckout(containerElementId: string, checkoutId: string, callbackFn: (paymentToken: string) => void): Promise<boolean>;

package/dist/resources/embedded.js

@@ -0,0 +1,178 @@
+import { isValidCardNumber, isValidExpiry } from '../utils/card';
+import { generateTimeBasedID } from '../utils/crypto';
+export async function renderEmbeddedCheckout(containerElementId, checkoutId, callbackFn) {
+    // --- Environment Guard ---
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        console.warn('EmbeddedCheckoutUI can only be used in a browser environment.');
+        return false;
+    }
+    // --- Checkout Validation ---
+    if (checkoutId.length !== 20 || !checkoutId.startsWith('cki_')) {
+        console.warn(`Invalid checkout ID: "${checkoutId}".`);
+        return false;
+    }
+    if (`${checkoutId}` !== `cki_${await generateTimeBasedID('checkout')}`) {
+        console.warn(`Expired checkout ID: "${checkoutId}".`);
+        return false;
+    }
+    const container = document.getElementById(containerElementId.startsWith('#') ? containerElementId.slice(1) : containerElementId);
+    if (!container) {
+        console.warn(`Container element "${containerElementId}" not found.`);
+        return false;
+    }
+    // --- Render UI ---
+    container.innerHTML = `
+  <div style="
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #ffffff;
+    border-radius: 16px;
+    box-shadow: 0 10px 30px rgba(0,0,0,0.08);
+    padding: 24px;
+    max-width: 400px;
+    width: 100%;
+    box-sizing: border-box;
+  ">
+    <h3 style="margin:0 0 20px 0; font-size:18px; font-weight:600; color:#111827;">
+      "Secure" Checkout
+    </h3>
+
+    <div style="display:flex; flex-direction:column; gap:14px;">
+
+      ${inputBlock('card-number', 'Card Number', '4242 4242 4242 4242', 19)}
+      <div style="display:flex; gap:10px;">
+        <div style="flex:1;">
+          ${inputBlock('exp-month', 'Exp. Month', '12', 2)}
+        </div>
+        <div style="flex:1;">
+          ${inputBlock('exp-year', 'Exp. Year', '2030', 4)}
+        </div>
+      </div>
+      ${inputBlock('cvc', 'CVC', '123', 3)}
+
+      <button id="confirm-btn"
+        style="
+          margin-top:8px;
+          padding:12px;
+          border-radius:12px;
+          border:none;
+          font-size:14px;
+          font-weight:600;
+          background: linear-gradient(135deg, #6366f1, #4f46e5);
+          color:white;
+          cursor:pointer;
+          transition: all 0.15s ease;
+          box-shadow: 0 4px 14px rgba(79,70,229,0.3);
+        ">
+        Confirm Payment
+      </button>
+
+      <p style="font-size:11px; color:#9ca3af; text-align:center; margin-top:8px;">
+        🔒 Payments are securely processed
+      </p>
+
+    </div>
+  </div>
+  `;
+    function inputBlock(id, label, placeholder, maxLength) {
+        return `
+      <div style="display:flex; flex-direction:column;">
+        <label style="font-size:12px; color:#6b7280; margin-bottom:6px;">
+          ${label}
+        </label>
+        <input
+          id="${id}"
+          type="text"
+		  inputmode="numeric"
+		  maxlength="${maxLength}"
+		  pattern="[0-9]*"
+          placeholder="${placeholder}"
+          style="
+            padding:10px 12px;
+            border-radius:10px;
+            border:1px solid #e5e7eb;
+            font-size:14px;
+            outline:none;
+            transition:border 0.2s, box-shadow 0.2s;
+          "
+        />
+        <div id="${id}-error"
+          style="font-size:12px; color:#ef4444; margin-top:4px; display:none;">
+        </div>
+      </div>
+    `;
+    }
+    // --- DOM Refs ---
+    const cardNumberInput = container.querySelector('#card-number');
+    const expMonthInput = container.querySelector('#exp-month');
+    const expYearInput = container.querySelector('#exp-year');
+    const cvcInput = container.querySelector('#cvc');
+    const button = container.querySelector('#confirm-btn');
+    // --- Helpers ---
+    function showError(input, message) {
+        input.style.border = '1px solid #ef4444';
+        const error = container?.querySelector(`#${input.id}-error`);
+        if (error) {
+            error.textContent = message;
+            error.style.display = 'block';
+        }
+    }
+    function clearError(input) {
+        input.style.border = '1px solid #e5e7eb';
+        const error = container?.querySelector(`#${input.id}-error`);
+        if (error) {
+            error.textContent = '';
+            error.style.display = 'none';
+        }
+    }
+    function setLoading(state) {
+        button.disabled = state;
+        button.style.opacity = state ? '0.6' : '1';
+        button.textContent = state ? 'Processing...' : 'Confirm Payment';
+    }
+    function clearAllErrors() {
+        [cardNumberInput, expMonthInput, expYearInput, cvcInput].forEach(clearError);
+    }
+    // --- Formatting ---
+    cardNumberInput.addEventListener('input', () => {
+        let value = cardNumberInput.value.replace(/\D/g, '').slice(0, 16);
+        value = value.replace(/(.{4})/g, '$1 ').trim();
+        cardNumberInput.value = value;
+        clearError(cardNumberInput);
+    });
+    [expMonthInput, expYearInput, cvcInput].forEach((input) => input.addEventListener('input', () => clearError(input)));
+    // --- Submit ---
+    button.addEventListener('click', async () => {
+        clearAllErrors();
+        const number = cardNumberInput.value.replace(/\s+/g, '');
+        const expMonth = Number(expMonthInput.value);
+        const expYear = Number(expYearInput.value);
+        const cvc = cvcInput.value;
+        let hasError = false;
+        if (!number) {
+            showError(cardNumberInput, 'Card number required');
+            hasError = true;
+        }
+        else if (!isValidCardNumber(number)) {
+            showError(cardNumberInput, 'Invalid card number');
+            hasError = true;
+        }
+        if (!expMonthInput.value || expMonth < 1 || expMonth > 12) {
+            showError(expMonthInput, 'Invalid month');
+            hasError = true;
+        }
+        if (!expYearInput.value || !isValidExpiry(expMonth, expYear)) {
+            showError(expYearInput, 'Card expired');
+            hasError = true;
+        }
+        if (!cvc || !/^\d{3,4}$/.test(cvc)) {
+            showError(cvcInput, 'Invalid CVC');
+            hasError = true;
+        }
+        if (hasError)
+            return;
+        setLoading(true);
+        const paymentToken = `pmt_${await generateTimeBasedID('payment-token')}`;
+        callbackFn(paymentToken);
+    });
+    return true;
+}

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 {
+    uid: 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/resources/webhooks.js

@@ -0,0 +1,20 @@
+import { sleep } from '../utils/async';
+export const INTERNAL_WEBHOOKS = [];
+export 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
+     */
+    async createEndpoint(params) {
+        for (const event of params.events) {
+            await sleep(Math.random() * 100);
+            INTERNAL_WEBHOOKS.push({
+                url: params.url,
+                event: event,
+                secret: params.secret,
+            });
+        }
+        return true;
+    }
+}

package/dist/utils/async.d.ts

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

package/dist/utils/async.js

@@ -0,0 +1 @@
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/utils/card.d.ts

@@ -0,0 +1,2 @@
+export declare function isValidCardNumber(number: string): boolean;
+export declare function isValidExpiry(month: number, year: number): boolean;

package/dist/utils/card.js

@@ -0,0 +1,29 @@
+export function isValidCardNumber(number) {
+    // Test card is valid
+    if (number === '4242424242424242')
+        return true;
+    // Cards must be 13-19 digits
+    if (!/^\d{13,19}$/.test(number))
+        return false;
+    // Luhn check
+    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;
+}
+export function isValidExpiry(month, year) {
+    if (month < 1 || month > 12)
+        return false;
+    const now = new Date();
+    const expiry = new Date(year, month - 1);
+    return expiry > now;
+}

package/dist/utils/crypto.d.ts

@@ -0,0 +1,5 @@
+export declare function generateID(length?: number): number;
+export declare function generateTimeBasedID(extra?: string): Promise<string>;
+export declare function hashToString(input: string): Promise<string>;
+export declare function signPayload(payload: string, secret: string): string;
+export declare function genReqId(): string;

package/dist/utils/crypto.js

@@ -0,0 +1,28 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import crypto from 'crypto';
+export function generateID(length = 12) {
+    const digits = [];
+    const bytes = crypto.randomBytes(length);
+    for (let i = 0; i < length; i++) {
+        digits.push((bytes[i] ?? 0) % 10);
+    }
+    return parseInt(digits.join(''));
+}
+export async function generateTimeBasedID(extra = '') {
+    const now = Date.now(); // current time in ms
+    const oneMinute = 60 * 1000;
+    const ms = Math.floor(now / oneMinute) * oneMinute;
+    return await hashToString(`${ms}---${extra}`);
+}
+export async function hashToString(input) {
+    const hash = bytesToHex(sha256(new TextEncoder().encode(input)));
+    // 16 hex characters = 64 bits
+    return hash.slice(0, 16);
+}
+export function signPayload(payload, secret) {
+    return crypto.createHmac('sha256', secret).update(payload).digest('hex');
+}
+export function genReqId() {
+    return crypto.randomUUID().split('-')[0] ?? '';
+}

package/dist/utils/store.d.ts

@@ -0,0 +1,16 @@
+export type HistoryRecord = {
+    id: string;
+    amount: number;
+    currency: 'USD' | 'EUR' | 'JPY';
+    customerId: string | null;
+    updatedAt: number;
+    createdAt: number;
+};
+/**
+ * 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, 'createdAt' | 'updatedAt'>): Promise<HistoryRecord>;

package/dist/utils/store.js

@@ -0,0 +1,40 @@
+const path = new URL('../db-store/history.json', import.meta.url);
+async function ensureFileExists() {
+    const file = Bun.file(path);
+    if (!(await file.exists())) {
+        await Bun.write(path, '[]');
+    }
+}
+/**
+ * Reads all history records from the JSON store.
+ */
+export async function readHistory() {
+    await ensureFileExists();
+    const file = Bun.file(path);
+    const text = await file.text();
+    if (!text)
+        return [];
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // If file somehow becomes corrupted, reset it
+        await Bun.write(path, '[]');
+        return [];
+    }
+}
+/**
+ * Writes a new record to the JSON store.
+ */
+export async function writeHistory(params) {
+    const history = await readHistory();
+    const now = Date.now();
+    const record = {
+        ...params,
+        createdAt: now,
+        updatedAt: now,
+    };
+    history.push(record);
+    await Bun.write(path, JSON.stringify(history, null, 2));
+    return record;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@henrylabs-interview/payments",
+	"version": "0.2.16",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "rm -rf dist && bunx tsc -p tsconfig.build.json",
+		"dev": "bun run src/index.ts",
+		"publish": "bun run build && npm publish --access public"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@noble/hashes": "^2.0.1"
+	}
+}