reqon-dsl 0.2.0

package/examples/temporal-comparison/temporal/activities/stripe.ts

@@ -0,0 +1,169 @@
+// Stripe API activities
+// Another 200+ lines for what Reqon does declaratively
+
+import Stripe from 'stripe';
+import { Context } from '@temporalio/activity';
+import { StripePaymentIntent, UnifiedPayment } from '../types';
+
+// Custom errors
+export class StripeAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StripeAuthError';
+  }
+}
+
+export class StripeCardError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StripeCardError';
+  }
+}
+
+// Initialize Stripe client
+function getStripeClient(): Stripe {
+  const apiKey = process.env.STRIPE_SECRET_KEY;
+  if (!apiKey) {
+    throw new StripeAuthError('Missing Stripe API key');
+  }
+  return new Stripe(apiKey, {
+    apiVersion: '2023-10-16',
+    maxNetworkRetries: 0, // We handle retries via Temporal
+  });
+}
+
+// Transform Stripe payment to unified format
+// In Reqon: map payment -> UnifiedPayment { ... }
+function transformPayment(payment: Stripe.PaymentIntent): UnifiedPayment {
+  const statusMap: Record<string, string> = {
+    succeeded: 'captured',
+    requires_capture: 'authorized',
+    canceled: 'voided',
+    requires_payment_method: 'pending',
+    requires_confirmation: 'pending',
+    requires_action: 'pending',
+    processing: 'processing',
+  };
+
+  const shopifyOrderId = payment.metadata?.shopify_order_id;
+  const charge = payment.charges?.data?.[0];
+
+  return {
+    payment_id: `stripe_${payment.id}`,
+    order_id: shopifyOrderId ? `shopify_${shopifyOrderId}` : '',
+    amount: payment.amount / 100, // Convert from cents
+    currency: payment.currency,
+    status: statusMap[payment.status] || payment.status,
+    method: payment.payment_method_types?.[0] || 'unknown',
+    captured_at: charge ? new Date(charge.created * 1000) : new Date(),
+    refunded_amount: charge ? charge.amount_refunded / 100 : 0,
+  };
+}
+
+// Activity: Fetch all Stripe payments with pagination
+export async function fetchAllStripePayments(
+  since: number | null
+): Promise<UnifiedPayment[]> {
+  const stripe = getStripeClient();
+  const allPayments: UnifiedPayment[] = [];
+  let hasMore = true;
+  let startingAfter: string | undefined;
+  let pageCount = 0;
+
+  const params: Stripe.PaymentIntentListParams = {
+    limit: 100,
+    expand: ['data.charges'],
+  };
+
+  if (since) {
+    params.created = { gte: since };
+  }
+
+  while (hasMore) {
+    // Heartbeat for long-running pagination
+    Context.current().heartbeat({
+      page: pageCount,
+      paymentsFound: allPayments.length
+    });
+
+    if (startingAfter) {
+      params.starting_after = startingAfter;
+    }
+
+    try {
+      const response = await stripe.paymentIntents.list(params);
+
+      // Filter and transform payments that have a Shopify order ID
+      for (const payment of response.data) {
+        if (payment.metadata?.shopify_order_id) {
+          allPayments.push(transformPayment(payment));
+        }
+      }
+
+      hasMore = response.has_more;
+      if (response.data.length > 0) {
+        startingAfter = response.data[response.data.length - 1].id;
+      }
+
+      pageCount++;
+      console.log(`Stripe: Fetched page ${pageCount}, total payments: ${allPayments.length}`);
+    } catch (error) {
+      if (error instanceof Stripe.errors.StripeAuthenticationError) {
+        throw new StripeAuthError('Invalid Stripe API key');
+      }
+      if (error instanceof Stripe.errors.StripeCardError) {
+        throw new StripeCardError(error.message);
+      }
+      throw error;
+    }
+  }
+
+  return allPayments;
+}
+
+// Activity: Fetch a single payment by ID
+export async function fetchStripePayment(paymentId: string): Promise<UnifiedPayment | null> {
+  const stripe = getStripeClient();
+
+  try {
+    const payment = await stripe.paymentIntents.retrieve(paymentId, {
+      expand: ['charges'],
+    });
+    return transformPayment(payment);
+  } catch (error) {
+    if (error instanceof Stripe.errors.StripeInvalidRequestError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// Activity: Get last sync timestamp
+export async function getStripeLastSync(): Promise<number | null> {
+  // Would query database
+  const lastSync = process.env.STRIPE_LAST_SYNC;
+  return lastSync ? parseInt(lastSync, 10) : null;
+}
+
+// Activity: Update last sync timestamp
+export async function updateStripeLastSync(timestamp: number): Promise<void> {
+  console.log(`Updated Stripe last sync to: ${new Date(timestamp * 1000).toISOString()}`);
+}
+
+// Activity: Fetch refunds for reconciliation
+export async function fetchStripeRefunds(
+  paymentIntentId: string
+): Promise<Array<{ id: string; amount: number; status: string }>> {
+  const stripe = getStripeClient();
+
+  const refunds = await stripe.refunds.list({
+    payment_intent: paymentIntentId,
+    limit: 100,
+  });
+
+  return refunds.data.map((refund) => ({
+    id: refund.id,
+    amount: refund.amount / 100,
+    status: refund.status || 'unknown',
+  }));
+}

package/examples/temporal-comparison/temporal/activities/validation.ts

@@ -0,0 +1,205 @@
+// Validation activities
+// In Reqon, this is just `validate response { assume ... }`
+// In Temporal, we need explicit functions for every validation rule
+
+import {
+  UnifiedOrder,
+  UnifiedPayment,
+  UnifiedShipment,
+  Discrepancy,
+  Severity,
+} from '../types';
+
+interface ValidationResult {
+  isValid: boolean;
+  discrepancies: Discrepancy[];
+}
+
+// Activity: Check for orders without payments
+export async function validateOrdersHavePayments(
+  orders: UnifiedOrder[],
+  payments: UnifiedPayment[]
+): Promise<Discrepancy[]> {
+  const discrepancies: Discrepancy[] = [];
+  const paymentsByOrderId = new Map<string, UnifiedPayment[]>();
+
+  // Build payment lookup
+  for (const payment of payments) {
+    const existing = paymentsByOrderId.get(payment.order_id) || [];
+    existing.push(payment);
+    paymentsByOrderId.set(payment.order_id, existing);
+  }
+
+  // Check each pending order older than 3 days
+  const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000);
+
+  for (const order of orders) {
+    if (order.payment_status === 'pending' && order.created_at < threeDaysAgo) {
+      const orderPayments = paymentsByOrderId.get(order.order_id);
+
+      if (!orderPayments || orderPayments.length === 0) {
+        discrepancies.push({
+          id: `disc_${order.order_id}_no_payment`,
+          order_id: order.order_id,
+          type: 'missing_payment',
+          severity: 'high',
+          description: 'Order older than 3 days has no matching Stripe payment',
+          shopify_value: String(order.total_amount),
+          stripe_value: null,
+          shipstation_value: null,
+          detected_at: new Date(),
+        });
+      }
+    }
+  }
+
+  return discrepancies;
+}
+
+// Activity: Check for payment/order amount mismatches
+export async function validatePaymentAmounts(
+  orders: UnifiedOrder[],
+  payments: UnifiedPayment[]
+): Promise<Discrepancy[]> {
+  const discrepancies: Discrepancy[] = [];
+  const paymentsByOrderId = new Map<string, UnifiedPayment[]>();
+
+  // Build payment lookup
+  for (const payment of payments) {
+    const existing = paymentsByOrderId.get(payment.order_id) || [];
+    existing.push(payment);
+    paymentsByOrderId.set(payment.order_id, existing);
+  }
+
+  for (const order of orders) {
+    const orderPayments = paymentsByOrderId.get(order.order_id) || [];
+    const totalPaid = orderPayments.reduce((sum, p) => sum + p.amount, 0);
+
+    // Allow for small floating point differences
+    const difference = Math.abs(order.total_amount - totalPaid);
+
+    if (difference > 0.01) {
+      // Determine severity based on difference amount
+      let severity: Severity;
+      if (difference > 100) {
+        severity = 'critical';
+      } else if (difference > 10) {
+        severity = 'high';
+      } else {
+        severity = 'medium';
+      }
+
+      discrepancies.push({
+        id: `disc_${order.order_id}_amount_mismatch`,
+        order_id: order.order_id,
+        type: 'amount_mismatch',
+        severity,
+        description: 'Order total does not match payment total',
+        shopify_value: String(order.total_amount),
+        stripe_value: String(totalPaid),
+        shipstation_value: null,
+        detected_at: new Date(),
+      });
+    }
+  }
+
+  return discrepancies;
+}
+
+// Activity: Check for shipped orders without shipment records
+export async function validateShipmentsExist(
+  orders: UnifiedOrder[],
+  shipments: UnifiedShipment[]
+): Promise<Discrepancy[]> {
+  const discrepancies: Discrepancy[] = [];
+  const shipmentsByOrderId = new Set(shipments.map((s) => s.order_id));
+
+  for (const order of orders) {
+    if (order.fulfillment_status === 'shipped') {
+      if (!shipmentsByOrderId.has(order.order_id)) {
+        discrepancies.push({
+          id: `disc_${order.order_id}_no_shipment`,
+          order_id: order.order_id,
+          type: 'missing_shipment_record',
+          severity: 'medium',
+          description: 'Shopify shows fulfilled but no ShipStation shipment found',
+          shopify_value: order.fulfillment_status,
+          stripe_value: null,
+          shipstation_value: null,
+          detected_at: new Date(),
+        });
+      }
+    }
+  }
+
+  return discrepancies;
+}
+
+// Activity: Check for refund status mismatches
+export async function validateRefundStatuses(
+  orders: UnifiedOrder[],
+  payments: UnifiedPayment[]
+): Promise<Discrepancy[]> {
+  const discrepancies: Discrepancy[] = [];
+  const orderById = new Map(orders.map((o) => [o.order_id, o]));
+
+  for (const payment of payments) {
+    if (payment.refunded_amount > 0) {
+      const order = orderById.get(payment.order_id);
+
+      if (order) {
+        const expectedStatuses = ['refunded', 'partial_refund'];
+        if (!expectedStatuses.includes(order.payment_status)) {
+          discrepancies.push({
+            id: `disc_${payment.order_id}_refund_mismatch`,
+            order_id: payment.order_id,
+            type: 'refund_status_mismatch',
+            severity: 'high',
+            description: 'Stripe shows refund but Shopify payment status not updated',
+            shopify_value: order.payment_status,
+            stripe_value: String(payment.refunded_amount),
+            shipstation_value: null,
+            detected_at: new Date(),
+          });
+        }
+      }
+    }
+  }
+
+  return discrepancies;
+}
+
+// Activity: Run all validations
+export async function runAllValidations(
+  orders: UnifiedOrder[],
+  payments: UnifiedPayment[],
+  shipments: UnifiedShipment[]
+): Promise<ValidationResult> {
+  const allDiscrepancies: Discrepancy[] = [];
+
+  // Run all validation checks
+  const [paymentMissing, amountMismatch, shipmentMissing, refundMismatch] =
+    await Promise.all([
+      validateOrdersHavePayments(orders, payments),
+      validatePaymentAmounts(orders, payments),
+      validateShipmentsExist(orders, shipments),
+      validateRefundStatuses(orders, payments),
+    ]);
+
+  allDiscrepancies.push(
+    ...paymentMissing,
+    ...amountMismatch,
+    ...shipmentMissing,
+    ...refundMismatch
+  );
+
+  // Deduplicate by ID
+  const uniqueDiscrepancies = Array.from(
+    new Map(allDiscrepancies.map((d) => [d.id, d])).values()
+  );
+
+  return {
+    isValid: uniqueDiscrepancies.length === 0,
+    discrepancies: uniqueDiscrepancies,
+  };
+}

package/examples/temporal-comparison/temporal/client/schedule.ts

@@ -0,0 +1,218 @@
+// Temporal Client - Schedule and trigger workflows
+// More boilerplate that Reqon doesn't need
+
+import { Connection, Client, ScheduleClient } from '@temporalio/client';
+import { orderReconciliationWorkflow } from '../workflows/orderReconciliation';
+
+const TASK_QUEUE = 'order-reconciliation';
+const TEMPORAL_ADDRESS = process.env.TEMPORAL_ADDRESS || 'localhost:7233';
+const TEMPORAL_NAMESPACE = process.env.TEMPORAL_NAMESPACE || 'default';
+
+async function getClient(): Promise<Client> {
+  const connection = await Connection.connect({
+    address: TEMPORAL_ADDRESS,
+  });
+
+  return new Client({
+    connection,
+    namespace: TEMPORAL_NAMESPACE,
+  });
+}
+
+// Run workflow once
+export async function runReconciliation(): Promise<void> {
+  const client = await getClient();
+
+  const workflowId = `order-reconciliation-${Date.now()}`;
+
+  console.log(`Starting workflow: ${workflowId}`);
+
+  const handle = await client.workflow.start(orderReconciliationWorkflow, {
+    taskQueue: TASK_QUEUE,
+    workflowId,
+    // Workflow-level timeout
+    workflowExecutionTimeout: '1h',
+    // Retry policy for the entire workflow
+    retry: {
+      initialInterval: '1m',
+      backoffCoefficient: 2,
+      maximumAttempts: 3,
+      maximumInterval: '10m',
+    },
+  });
+
+  console.log(`Workflow started with run ID: ${handle.firstExecutionRunId}`);
+
+  // Wait for completion
+  const result = await handle.result();
+  console.log('Workflow completed:', result);
+}
+
+// Create a schedule for daily runs
+export async function createDailySchedule(): Promise<void> {
+  const connection = await Connection.connect({
+    address: TEMPORAL_ADDRESS,
+  });
+
+  const scheduleClient = new ScheduleClient({
+    connection,
+    namespace: TEMPORAL_NAMESPACE,
+  });
+
+  const scheduleId = 'order-reconciliation-daily';
+
+  try {
+    // Delete existing schedule if present
+    const existingHandle = scheduleClient.getHandle(scheduleId);
+    await existingHandle.delete();
+    console.log('Deleted existing schedule');
+  } catch {
+    // Schedule didn't exist
+  }
+
+  // Create new schedule
+  await scheduleClient.create({
+    scheduleId,
+    spec: {
+      // Run daily at 2 AM UTC
+      calendars: [
+        {
+          hour: 2,
+          minute: 0,
+        },
+      ],
+    },
+    action: {
+      type: 'startWorkflow',
+      workflowType: orderReconciliationWorkflow,
+      taskQueue: TASK_QUEUE,
+      workflowId: 'order-reconciliation-scheduled',
+      args: [],
+    },
+    policies: {
+      overlap: 'SKIP', // Skip if previous run still running
+      catchupWindow: '1h', // Catch up missed runs within 1 hour
+    },
+  });
+
+  console.log(`Created daily schedule: ${scheduleId}`);
+}
+
+// Query workflow status
+export async function getWorkflowStatus(workflowId: string): Promise<void> {
+  const client = await getClient();
+
+  const handle = client.workflow.getHandle(workflowId);
+
+  const description = await handle.describe();
+  console.log('Workflow status:', description.status.name);
+
+  // Query for detailed state
+  const state = await handle.query('getStatus');
+  console.log('Workflow state:', state);
+}
+
+// Cancel a running workflow
+export async function cancelWorkflow(workflowId: string): Promise<void> {
+  const client = await getClient();
+
+  const handle = client.workflow.getHandle(workflowId);
+
+  // Send cancel signal
+  await handle.signal('cancel');
+  console.log(`Sent cancel signal to workflow: ${workflowId}`);
+}
+
+// Pause a running workflow
+export async function pauseWorkflow(workflowId: string): Promise<void> {
+  const client = await getClient();
+
+  const handle = client.workflow.getHandle(workflowId);
+
+  await handle.signal('pause');
+  console.log(`Sent pause signal to workflow: ${workflowId}`);
+}
+
+// Resume a paused workflow
+export async function resumeWorkflow(workflowId: string): Promise<void> {
+  const client = await getClient();
+
+  const handle = client.workflow.getHandle(workflowId);
+
+  await handle.signal('resume');
+  console.log(`Sent resume signal to workflow: ${workflowId}`);
+}
+
+// CLI entry point
+async function main() {
+  const command = process.argv[2];
+  const workflowId = process.argv[3];
+
+  switch (command) {
+    case 'run':
+      await runReconciliation();
+      break;
+    case 'schedule':
+      await createDailySchedule();
+      break;
+    case 'status':
+      if (!workflowId) {
+        console.error('Usage: schedule.ts status <workflowId>');
+        process.exit(1);
+      }
+      await getWorkflowStatus(workflowId);
+      break;
+    case 'cancel':
+      if (!workflowId) {
+        console.error('Usage: schedule.ts cancel <workflowId>');
+        process.exit(1);
+      }
+      await cancelWorkflow(workflowId);
+      break;
+    case 'pause':
+      if (!workflowId) {
+        console.error('Usage: schedule.ts pause <workflowId>');
+        process.exit(1);
+      }
+      await pauseWorkflow(workflowId);
+      break;
+    case 'resume':
+      if (!workflowId) {
+        console.error('Usage: schedule.ts resume <workflowId>');
+        process.exit(1);
+      }
+      await resumeWorkflow(workflowId);
+      break;
+    default:
+      console.log('Usage: schedule.ts <command> [workflowId]');
+      console.log('Commands: run, schedule, status, cancel, pause, resume');
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+
+/*
+ * REQON EQUIVALENT:
+ *
+ * # Run once
+ * reqon reconciliation.vague
+ *
+ * # Run with credentials
+ * reqon reconciliation.vague --auth ./credentials.json
+ *
+ * # Dry run (preview without API calls)
+ * reqon reconciliation.vague --dry-run
+ *
+ * # Resume from checkpoint
+ * reqon reconciliation.vague --resume execution-abc123
+ *
+ * # For scheduling, use cron or any scheduler:
+ * 0 2 * * * reqon reconciliation.vague >> /var/log/reqon.log
+ *
+ * No Temporal server. No workers. No client SDK.
+ * Just a declarative DSL that runs anywhere.
+ */

package/examples/temporal-comparison/temporal/config/retry.ts

@@ -0,0 +1,63 @@
+// Retry configuration for each API
+// In Temporal, every activity needs its own retry policy configured manually
+
+import { ActivityOptions } from '@temporalio/workflow';
+
+// Shopify has strict rate limits - 40 requests per minute for most plans
+export const shopifyActivityOptions: ActivityOptions = {
+  startToCloseTimeout: '5m',
+  heartbeatTimeout: '30s',
+  retry: {
+    initialInterval: '2s',
+    backoffCoefficient: 2,
+    maximumAttempts: 5,
+    maximumInterval: '60s',
+    nonRetryableErrorTypes: ['ShopifyAuthError', 'ShopifyNotFoundError'],
+  },
+};
+
+// Stripe is more generous but still needs careful handling
+export const stripeActivityOptions: ActivityOptions = {
+  startToCloseTimeout: '3m',
+  heartbeatTimeout: '20s',
+  retry: {
+    initialInterval: '1s',
+    backoffCoefficient: 2,
+    maximumAttempts: 3,
+    maximumInterval: '30s',
+    nonRetryableErrorTypes: ['StripeAuthError', 'StripeCardError'],
+  },
+};
+
+// ShipStation has very strict rate limits
+export const shipStationActivityOptions: ActivityOptions = {
+  startToCloseTimeout: '10m',
+  heartbeatTimeout: '60s',
+  retry: {
+    initialInterval: '3s',
+    backoffCoefficient: 2,
+    maximumAttempts: 4,
+    maximumInterval: '120s',
+    nonRetryableErrorTypes: ['ShipStationAuthError'],
+  },
+};
+
+// Database operations should be fast with minimal retries
+export const databaseActivityOptions: ActivityOptions = {
+  startToCloseTimeout: '30s',
+  retry: {
+    initialInterval: '500ms',
+    backoffCoefficient: 1.5,
+    maximumAttempts: 3,
+    maximumInterval: '5s',
+    nonRetryableErrorTypes: ['DatabaseConstraintError'],
+  },
+};
+
+// Validation is local computation, shouldn't fail
+export const validationActivityOptions: ActivityOptions = {
+  startToCloseTimeout: '1m',
+  retry: {
+    maximumAttempts: 1, // No retries for pure computation
+  },
+};