@payloops/processor-core 0.0.1

package/.env.example

@@ -0,0 +1,4 @@
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/loop
+ENCRYPTION_KEY=your-encryption-key-at-least-32-chars
+TEMPORAL_ADDRESS=localhost:7233
+TEMPORAL_NAMESPACE=loop

package/Dockerfile

@@ -0,0 +1,41 @@
+# Build stage
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source
+COPY src ./src
+COPY tsconfig.json ./
+
+# Build
+RUN npm run build
+
+# Production stage
+FROM node:22-alpine AS runner
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json ./
+
+# Install production dependencies only
+RUN npm ci --omit=dev
+
+# Copy built files
+COPY --from=builder /app/dist ./dist
+
+# Create non-root user
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 loop
+
+USER loop
+
+ENV NODE_ENV=production
+
+CMD ["node", "dist/worker.js"]

package/README.md

@@ -0,0 +1,248 @@
+# PayLoops Processor Core
+
+The **processor-core** service is the workflow engine powering PayLoops. It orchestrates payment processing, handles retries, manages state transitions, and ensures reliable webhook delivery—all with durability guarantees from [Temporal](https://temporal.io).
+
+## Role in the Platform
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                                                                         │
+│                           Backend API                                   │
+│                               │                                         │
+│                               │ Triggers workflows                      │
+│                               ▼                                         │
+│   ┌─────────────────────────────────────────────────────────────────┐  │
+│   │               ★ PROCESSOR-CORE (this repo) ★                     │  │
+│   │                                                                  │  │
+│   │  ┌──────────────────────────────────────────────────────────┐   │  │
+│   │  │                   Temporal Workers                        │   │  │
+│   │  │                                                           │   │  │
+│   │  │  PaymentWorkflow    RefundWorkflow    WebhookWorkflow    │   │  │
+│   │  │       │                   │                  │            │   │  │
+│   │  │       ▼                   ▼                  ▼            │   │  │
+│   │  │  ┌─────────┐        ┌─────────┐        ┌─────────┐       │   │  │
+│   │  │  │Activities│        │Activities│        │Activities│       │   │  │
+│   │  │  └─────────┘        └─────────┘        └─────────┘       │   │  │
+│   │  └──────────────────────────────────────────────────────────┘   │  │
+│   │                               │                                  │  │
+│   └───────────────────────────────┼──────────────────────────────────┘  │
+│                                   │                                     │
+│                                   ▼                                     │
+│              ┌────────────────────────────────────────┐                │
+│              │         Payment Processors             │                │
+│              │   processor-stripe  processor-razorpay │                │
+│              └────────────────────────────────────────┘                │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Why Temporal?
+
+Payment processing requires **durability** and **reliability**:
+
+- If the server crashes mid-payment, the workflow resumes exactly where it left off
+- Long-running operations (like waiting for 3DS) don't block resources
+- Automatic retries with configurable backoff
+- Full audit trail of every state transition
+- Easy to add timeouts, deadlines, and cancellation
+
+## Workflows
+
+### PaymentWorkflow
+
+Handles the complete lifecycle of a payment from order creation to completion.
+
+```
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│ pending │───▶│ routing │───▶│charging │───▶│ 3DS/SCA │───▶│completed│
+└─────────┘    └─────────┘    └─────────┘    └─────────┘    └─────────┘
+                                                  │
+                                                  ▼
+                                           Wait for signal
+                                           (threeDSComplete)
+```
+
+**States:**
+- `pending` - Order created, awaiting payment
+- `processing` - Routing to optimal processor
+- `authorized` - Payment authorized, awaiting capture
+- `requires_action` - Waiting for 3DS/SCA verification
+- `captured` - Payment successfully captured
+- `failed` - Payment failed
+
+**Signals:**
+- `threeDSComplete` - Customer completed 3DS challenge
+
+### WebhookDeliveryWorkflow
+
+Ensures merchants receive webhook notifications reliably.
+
+```
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│ attempt │───▶│  retry  │───▶│  retry  │───▶│  final  │
+│   #1    │    │   #2    │    │   #3    │    │ status  │
+└─────────┘    └─────────┘    └─────────┘    └─────────┘
+    1min          5min           30min
+```
+
+**Retry Schedule:**
+1. Immediate
+2. 1 minute
+3. 5 minutes
+4. 30 minutes
+5. 2 hours
+6. 24 hours (final attempt)
+
+## Processor Registry
+
+The core provides a plugin system for payment processors:
+
+```typescript
+// In processor-stripe or processor-razorpay
+import { registerProcessor, PaymentProcessor } from '@payloops/processor-core';
+
+class StripeProcessor implements PaymentProcessor {
+  name = 'stripe';
+
+  async createPayment(input, config) { /* ... */ }
+  async capturePayment(orderId, amount, config) { /* ... */ }
+  async refundPayment(transactionId, amount, config) { /* ... */ }
+  async getPaymentStatus(orderId, config) { /* ... */ }
+}
+
+registerProcessor(new StripeProcessor());
+```
+
+Workflows dynamically load the appropriate processor based on routing rules.
+
+## Activities
+
+Activities are the building blocks that workflows orchestrate:
+
+| Activity | Description |
+|----------|-------------|
+| `getOrder` | Fetch order details from database |
+| `updateOrderStatus` | Update order status in database |
+| `getProcessorConfig` | Get decrypted processor credentials |
+| `routePayment` | Determine which processor to use |
+| `processPayment` | Execute payment via processor |
+| `deliverWebhook` | POST webhook to merchant endpoint |
+
+## Development
+
+### Prerequisites
+
+- Node.js 22+
+- pnpm
+- Temporal server (via Docker)
+- PostgreSQL (via Docker)
+
+### Setup
+
+```bash
+# Install dependencies
+pnpm install
+
+# Copy environment template
+cp .env.example .env
+
+# Start Temporal (from root loop repo)
+docker-compose up -d temporal
+
+# Start worker in development mode
+pnpm dev
+```
+
+### Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `pnpm dev` | Start worker with hot reload |
+| `pnpm build` | Build for production |
+| `pnpm start` | Run production worker |
+| `pnpm typecheck` | Run TypeScript compiler |
+| `pnpm lint` | Run ESLint |
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string |
+| `TEMPORAL_ADDRESS` | Yes | Temporal server (default: localhost:7233) |
+| `TEMPORAL_NAMESPACE` | Yes | Temporal namespace |
+| `ENCRYPTION_KEY` | Yes | Key to decrypt processor credentials |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | No | OpenTelemetry collector endpoint (default: http://localhost:4318) |
+| `OTEL_SERVICE_NAME` | No | Service name for telemetry (default: loop-processor-core) |
+
+## Adding a New Processor
+
+1. Create a new repository (e.g., `processor-paypal`)
+2. Implement the `PaymentProcessor` interface
+3. Call `registerProcessor()` on module load
+4. Import the processor in this repo's worker
+
+See [processor-stripe](https://github.com/payloops/processor-stripe) for a complete example.
+
+## Observability
+
+The processor-core is fully instrumented with OpenTelemetry for distributed tracing, metrics, and structured logging.
+
+### What's Collected
+
+| Type | Description |
+|------|-------------|
+| **Traces** | Activity spans with workflow context, processor calls |
+| **Metrics** | Activity execution counts, durations, error rates |
+| **Logs** | Structured JSON logs with `trace_id`, `span_id`, workflow context |
+
+### Activity Tracing
+
+Every activity execution is automatically traced with:
+
+```
+activity.processPayment
+├── temporal.activity.type: processPayment
+├── temporal.workflow.id: payment-ord_abc123
+├── temporal.task_queue: payment-queue
+└── duration: 245ms
+```
+
+### Correlation with Backend
+
+When the backend triggers a workflow, the correlation ID is propagated via:
+- **Search Attributes**: `CorrelationId`, `MerchantId`, `OrderId`
+- **Memo**: `traceContext`, `correlationId`
+
+This enables end-to-end tracing from HTTP request → workflow → activities.
+
+### Viewing in OpenObserve
+
+1. Open http://localhost:5080 (login: `admin@loop.dev` / `admin123`)
+2. **Logs**: Filter by `service: loop-processor-core` or workflow ID
+3. **Traces**: View activity spans linked to parent workflow
+4. **Metrics**: Query activity execution metrics
+
+### Temporal UI
+
+Access at `http://localhost:8080` to:
+- View running and completed workflows
+- Inspect workflow history and state
+- Search by `CorrelationId` search attribute
+- Manually trigger signals
+- Terminate stuck workflows
+
+### Workflow IDs
+
+Workflows use predictable IDs for easy lookup:
+- Payment: `payment-{orderId}`
+- Webhook: `webhook-{eventId}`
+
+## Related Repositories
+
+- [backend](https://github.com/payloops/backend) - Triggers workflows via Temporal client
+- [processor-stripe](https://github.com/payloops/processor-stripe) - Stripe processor implementation
+- [processor-razorpay](https://github.com/payloops/processor-razorpay) - Razorpay processor implementation
+
+## License
+
+Copyright © 2025 PayLoops. All rights reserved.

package/dist/activities/index.d.ts

@@ -0,0 +1,2 @@
+import '../index-CsnpS83V.js';
+export { c as capturePayment, d as deliverWebhook, a as getMerchantWebhookUrl, g as getProcessorConfig, p as processPayment, r as refundPayment, u as updateOrderStatus } from '../index-CXmmtGo_.js';

package/dist/activities/index.js

@@ -0,0 +1,19 @@
+import {
+  capturePayment,
+  deliverWebhook,
+  getMerchantWebhookUrl,
+  getProcessorConfig,
+  processPayment,
+  refundPayment,
+  updateOrderStatus
+} from "../chunk-X2Y2ZUQA.js";
+import "../chunk-MLKGABMK.js";
+export {
+  capturePayment,
+  deliverWebhook,
+  getMerchantWebhookUrl,
+  getProcessorConfig,
+  processPayment,
+  refundPayment,
+  updateOrderStatus
+};

package/dist/chunk-AV4OEJXY.js

@@ -0,0 +1,132 @@
+// src/workflows/payment.ts
+import { proxyActivities, sleep, defineSignal, setHandler } from "@temporalio/workflow";
+var { processPayment, updateOrderStatus, capturePayment } = proxyActivities({
+  startToCloseTimeout: "2 minutes",
+  retry: {
+    initialInterval: "1s",
+    maximumInterval: "1m",
+    backoffCoefficient: 2,
+    maximumAttempts: 5
+  }
+});
+var completePaymentSignal = defineSignal(
+  "completePayment"
+);
+var cancelPaymentSignal = defineSignal("cancelPayment");
+async function PaymentWorkflow(input) {
+  let paymentCompleted = false;
+  let paymentResult = null;
+  let cancelled = false;
+  setHandler(completePaymentSignal, (result) => {
+    paymentCompleted = true;
+    paymentResult = {
+      success: result.success,
+      status: result.success ? "captured" : "failed",
+      processorTransactionId: result.processorTransactionId
+    };
+  });
+  setHandler(cancelPaymentSignal, () => {
+    cancelled = true;
+  });
+  try {
+    const result = await processPayment({
+      orderId: input.orderId,
+      merchantId: input.merchantId,
+      amount: input.amount,
+      currency: input.currency,
+      processor: input.processor,
+      returnUrl: input.returnUrl
+    });
+    if (result.status === "requires_action") {
+      await updateOrderStatus(input.orderId, "requires_action", result.processorOrderId);
+      const timeout = 15 * 60 * 1e3;
+      const startTime = Date.now();
+      while (!paymentCompleted && !cancelled && Date.now() - startTime < timeout) {
+        await sleep("10 seconds");
+      }
+      if (cancelled) {
+        await updateOrderStatus(input.orderId, "cancelled");
+        return { success: false, status: "failed", errorCode: "cancelled", errorMessage: "Payment cancelled" };
+      }
+      if (!paymentCompleted) {
+        await updateOrderStatus(input.orderId, "failed");
+        return { success: false, status: "failed", errorCode: "timeout", errorMessage: "Payment timeout" };
+      }
+      if (paymentResult) {
+        await updateOrderStatus(
+          input.orderId,
+          paymentResult.status,
+          result.processorOrderId,
+          paymentResult.processorTransactionId
+        );
+        return paymentResult;
+      }
+    }
+    await updateOrderStatus(input.orderId, result.status, result.processorOrderId, result.processorTransactionId);
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    await updateOrderStatus(input.orderId, "failed");
+    return {
+      success: false,
+      status: "failed",
+      errorCode: "workflow_error",
+      errorMessage
+    };
+  }
+}
+
+// src/workflows/webhook.ts
+import { proxyActivities as proxyActivities2, sleep as sleep2 } from "@temporalio/workflow";
+var { deliverWebhook, getMerchantWebhookUrl } = proxyActivities2({
+  startToCloseTimeout: "1 minute",
+  retry: {
+    initialInterval: "1s",
+    maximumInterval: "30s",
+    backoffCoefficient: 2,
+    maximumAttempts: 3
+  }
+});
+var MAX_ATTEMPTS = 5;
+var RETRY_DELAYS = [
+  60 * 1e3,
+  // 1 minute
+  5 * 60 * 1e3,
+  // 5 minutes
+  30 * 60 * 1e3,
+  // 30 minutes
+  2 * 60 * 60 * 1e3,
+  // 2 hours
+  24 * 60 * 60 * 1e3
+  // 24 hours
+];
+async function WebhookDeliveryWorkflow(input) {
+  const { secret } = await getMerchantWebhookUrl(input.merchantId);
+  let attempt = 0;
+  let lastResult = null;
+  while (attempt < MAX_ATTEMPTS) {
+    attempt++;
+    const result = await deliverWebhook(input.webhookEventId, input.webhookUrl, secret || void 0, input.payload);
+    lastResult = result;
+    if (result.success) {
+      return result;
+    }
+    if (attempt >= MAX_ATTEMPTS) {
+      return {
+        success: false,
+        attempts: attempt,
+        errorMessage: result.errorMessage || "Max attempts reached"
+      };
+    }
+    const delay = RETRY_DELAYS[attempt - 1] || RETRY_DELAYS[RETRY_DELAYS.length - 1];
+    await sleep2(delay);
+  }
+  return lastResult || { success: false, attempts: attempt, errorMessage: "Unknown error" };
+}
+
+export {
+  completePaymentSignal,
+  cancelPaymentSignal,
+  PaymentWorkflow,
+  WebhookDeliveryWorkflow
+};

package/dist/chunk-CZTZBCNV.js

@@ -0,0 +1,133 @@
+// src/workflows/payment.ts
+import { proxyActivities, sleep, defineSignal, setHandler } from "@temporalio/workflow";
+var { processPayment, updateOrderStatus, capturePayment } = proxyActivities({
+  startToCloseTimeout: "2 minutes",
+  retry: {
+    initialInterval: "1s",
+    maximumInterval: "1m",
+    backoffCoefficient: 2,
+    maximumAttempts: 5
+  }
+});
+var completePaymentSignal = defineSignal(
+  "completePayment"
+);
+var cancelPaymentSignal = defineSignal("cancelPayment");
+async function PaymentWorkflow(input) {
+  let paymentCompleted = false;
+  let paymentResult = null;
+  let cancelled = false;
+  setHandler(completePaymentSignal, (result) => {
+    paymentCompleted = true;
+    paymentResult = {
+      success: result.success,
+      status: result.success ? "captured" : "failed",
+      processorTransactionId: result.processorTransactionId
+    };
+  });
+  setHandler(cancelPaymentSignal, () => {
+    cancelled = true;
+  });
+  try {
+    const result = await processPayment({
+      orderId: input.orderId,
+      merchantId: input.merchantId,
+      amount: input.amount,
+      currency: input.currency,
+      processor: input.processor,
+      returnUrl: input.returnUrl
+    });
+    if (result.status === "requires_action") {
+      await updateOrderStatus(input.orderId, "requires_action", result.processorOrderId);
+      const timeout = 15 * 60 * 1e3;
+      const startTime = Date.now();
+      while (!paymentCompleted && !cancelled && Date.now() - startTime < timeout) {
+        await sleep("10 seconds");
+      }
+      if (cancelled) {
+        await updateOrderStatus(input.orderId, "cancelled");
+        return { success: false, status: "failed", errorCode: "cancelled", errorMessage: "Payment cancelled" };
+      }
+      if (!paymentCompleted) {
+        await updateOrderStatus(input.orderId, "failed");
+        return { success: false, status: "failed", errorCode: "timeout", errorMessage: "Payment timeout" };
+      }
+      if (paymentResult !== null) {
+        const finalResult = paymentResult;
+        await updateOrderStatus(
+          input.orderId,
+          finalResult.status,
+          result.processorOrderId,
+          finalResult.processorTransactionId
+        );
+        return finalResult;
+      }
+    }
+    await updateOrderStatus(input.orderId, result.status, result.processorOrderId, result.processorTransactionId);
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    await updateOrderStatus(input.orderId, "failed");
+    return {
+      success: false,
+      status: "failed",
+      errorCode: "workflow_error",
+      errorMessage
+    };
+  }
+}
+
+// src/workflows/webhook.ts
+import { proxyActivities as proxyActivities2, sleep as sleep2 } from "@temporalio/workflow";
+var { deliverWebhook, getMerchantWebhookUrl } = proxyActivities2({
+  startToCloseTimeout: "1 minute",
+  retry: {
+    initialInterval: "1s",
+    maximumInterval: "30s",
+    backoffCoefficient: 2,
+    maximumAttempts: 3
+  }
+});
+var MAX_ATTEMPTS = 5;
+var RETRY_DELAYS = [
+  60 * 1e3,
+  // 1 minute
+  5 * 60 * 1e3,
+  // 5 minutes
+  30 * 60 * 1e3,
+  // 30 minutes
+  2 * 60 * 60 * 1e3,
+  // 2 hours
+  24 * 60 * 60 * 1e3
+  // 24 hours
+];
+async function WebhookDeliveryWorkflow(input) {
+  const { secret } = await getMerchantWebhookUrl(input.merchantId);
+  let attempt = 0;
+  let lastResult = null;
+  while (attempt < MAX_ATTEMPTS) {
+    attempt++;
+    const result = await deliverWebhook(input.webhookEventId, input.webhookUrl, secret || void 0, input.payload);
+    lastResult = result;
+    if (result.success) {
+      return result;
+    }
+    if (attempt >= MAX_ATTEMPTS) {
+      return {
+        success: false,
+        attempts: attempt,
+        errorMessage: result.errorMessage || "Max attempts reached"
+      };
+    }
+    const delay = RETRY_DELAYS[attempt - 1] || RETRY_DELAYS[RETRY_DELAYS.length - 1];
+    await sleep2(delay);
+  }
+  return lastResult || { success: false, attempts: attempt, errorMessage: "Unknown error" };
+}
+
+export {
+  completePaymentSignal,
+  cancelPaymentSignal,
+  PaymentWorkflow,
+  WebhookDeliveryWorkflow
+};

package/dist/chunk-MLKGABMK.js

@@ -0,0 +1,9 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};