// Pseudocode: inventory, payments, and shipping represent your service clients.
const reservation = await inventory.reserve(order);
const payment = await payments.charge(order);
const shipment = await shipping.create(order, reservation, payment);

mkdir siglo-checkout
cd siglo-checkout
npm init -y
npm install @siglo/core
npm install --save-dev typescript tsx @types/node

npm run build --workspace=@siglo/core
node --import tsx examples/src/getting-started/checkout-demo.ts
node --import tsx --test examples/src/getting-started/checkout.test.ts

import { Step, flow } from '@siglo/core';

export interface Order {
    orderId: string;
    sku: string;
    quantity: number;
    amountCents: number;
}

export interface CheckoutServices {
    reserve(order: Order): Promise<string>;
    release(reservationId: string): Promise<void>;
    charge(order: Order): Promise<string>;
    refund(paymentId: string): Promise<void>;
    ship(order: Order & { reservationId: string; paymentId: string }): Promise<string>;
}

export class TemporaryPaymentError extends Error {}

export function createCheckout(services: CheckoutServices) {
    const validateOrder = Step.create('validateOrder', (order: Order) => {
        if (
            !order.orderId ||
            !order.sku ||
            !Number.isInteger(order.quantity) ||
            order.quantity < 1 ||
            !Number.isSafeInteger(order.amountCents) ||
            order.amountCents < 1
        ) {
            throw new Error('An order needs an ID, SKU, positive quantity, and amount in cents');
        }
        return { validated: true };
    });

    const reserveStock = Step.create('reserveStock', async (order: Order) => ({
        reservationId: await services.reserve(order),
    })).compensate(async (output: { reservationId: string }) => {
        await services.release(output.reservationId);
    });

    const chargePayment = Step.create('chargePayment', async (order: Order) => ({
        paymentId: await services.charge(order),
    }))
        .onFail({
            maxRetries: 2,
            delay: 10,
            backoff: 'exponential',
            retryIf: error => error instanceof TemporaryPaymentError,
        })
        .compensate(async (output: { paymentId: string }) => {
            await services.refund(output.paymentId);
        });

    const arrangeShipping = Step.create(
        'arrangeShipping',
        async (order: Order & { reservationId: string; paymentId: string }) => ({
            trackingId: await services.ship(order),
        }),
    );

    return flow(validateOrder, reserveStock, chargePayment, arrangeShipping);
}

import { createCheckout, TemporaryPaymentError } from './checkout';
import type { CheckoutServices, Order } from './checkout';

export function createDemoServices(failShipping = false) {
    const events: string[] = [];
    let paymentAttempts = 0;

    const services: CheckoutServices = {
        async reserve(order) {
            events.push('reserve stock');
            return `reservation-${order.orderId}`;
        },
        async release() {
            events.push('release stock');
        },
        async charge(order) {
            paymentAttempts++;
            events.push(`charge attempt ${paymentAttempts}`);
            if (paymentAttempts === 1) {
                // Simulate an unavailable gateway BEFORE it accepts a charge.
                throw new TemporaryPaymentError('Payment gateway unavailable');
            }
            return `payment-${order.orderId}`;
        },
        async refund() {
            events.push('refund payment');
        },
        async ship(order) {
            events.push('arrange shipping');
            if (failShipping) throw new Error('No courier available');
            return `tracking-${order.orderId}`;
        },
    };

    return { services, events };
}

export const sampleOrder: Order = {
    orderId: 'order-1001',
    sku: 'coffee-kit',
    quantity: 1,
    amountCents: 4500,
};

async function main() {
    for (const failShipping of [false, true]) {
        const { services, events } = createDemoServices(failShipping);
        const checkout = createCheckout(services);
        console.log(failShipping ? 'Shipping failure:' : 'Successful checkout:');
        try {
            const result = await checkout.run(sampleOrder, { pojo: true });
            console.log(result.trackingId);
        } catch (error) {
            console.log(error instanceof Error ? error.message : String(error));
        }
        console.log(events.join(' -> '));
    }
}

if (require.main === module) {
    main().catch(error => {
        console.error(error);
        process.exitCode = 1;
    });
}

node --import tsx checkout-demo.ts

Successful checkout:
tracking-order-1001
reserve stock -> charge attempt 1 -> charge attempt 2 -> arrange shipping
Shipping failure:
No courier available
reserve stock -> charge attempt 1 -> charge attempt 2 -> arrange shipping -> refund payment -> release stock

import assert from 'node:assert/strict';
import { test } from 'node:test';
import { createCheckout } from './checkout';
import { createDemoServices, sampleOrder } from './checkout-demo';

test('refunds payment before releasing stock when shipping fails', async () => {
    const { services, events } = createDemoServices(true);

    await assert.rejects(createCheckout(services).run(sampleOrder, { pojo: true }), /No courier available/);
    assert.deepEqual(events, [
        'reserve stock',
        'charge attempt 1',
        'charge attempt 2',
        'arrange shipping',
        'refund payment',
        'release stock',
    ]);
});

node --import tsx --test checkout.test.ts

const options = {
    pojo: true,
    namespace: 'shop-demo',
    idempotencyKey: `checkout:${sampleOrder.orderId}`,
    idempotencyTtlMs: 60 * 60 * 1000,
};

const first = await checkout.run(sampleOrder, options);
const second = await checkout.run(sampleOrder, options);
// The second successful request reuses the completed workflow result.