Returns Quickstart

mkdir stateset-returns-example
cd stateset-returns-example
npm init -y
npm install @stateset/embedded@1.35.1

import assert from 'node:assert/strict';
import { Commerce } from '@stateset/embedded';

const commerce = new Commerce(':memory:');
const customer = await commerce.customers.create({
  email: 'ada@example.com', firstName: 'Ada', lastName: 'Lovelace',
});
const order = await commerce.orders.createExact({
  customerId: customer.id,
  currency: 'USD',
  items: [{ sku: 'MUG-001', name: 'Ceramic mug', quantity: 2, unitPrice: '12.50' }],
});
// Simulate a shipped order in this test database; no carrier is contacted.
await commerce.orders.ship(order.id, 'DEMO-OUTBOUND-001');
const shipped = await commerce.orders.get(order.id);
assert.equal(shipped.status, 'shipped');

const request = {
  orderId: shipped.id,
  reason: 'damaged',
  reasonDetails: 'One mug arrived cracked',
  idempotencyKey: `return-${shipped.id}-mug-1`,
  items: [{ orderItemId: shipped.items[0].id, quantity: 1 }],
};
const rma = await commerce.returns.create(request);
assert.equal(rma.status, 'requested');
console.log(`Created: ${rma.status}`);

const replay = await commerce.returns.create(request);
assert.equal(replay.id, rma.id);
assert.equal(await commerce.returns.count(), 1);
console.log('Retry returned the same return; count is 1');

const approved = await commerce.returns.approve(rma.id);
assert.equal(approved.status, 'approved');
console.log(`Approved: ${approved.status}`);
const inTransit = await commerce.returns.addTracking(rma.id, 'DEMO-RETURN-001');
assert.equal(inTransit.status, 'in_transit');
console.log(`Tracking added: ${inTransit.status}`);
// Simulate receipt only for this local demonstration.
const received = await commerce.returns.markReceived(rma.id);
assert.equal(received.status, 'received');
console.log(`Received: ${received.status}`);

// Version 1.35.1 requires an item disposition before completion.
await assert.rejects(
  () => commerce.returns.complete(rma.id),
  error => error.code === 'POLICY_REJECTED' && /disposition/.test(error.message),
);
assert.equal((await commerce.returns.get(rma.id)).status, 'received');
console.log('Completion blocked: record item dispositions before completing');

node returns-demo.mjs

Created: requested
Retry returned the same return; count is 1
Approved: approved
Tracking added: in_transit
Received: received
Completion blocked: record item dispositions before completing