@velaro/cli 1.4.228 → 1.4.230

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/velaro.js CHANGED
@@ -144,6 +144,7 @@ import { aiFollowupsCommand, businessActionCommand, callCommand, conversationCom
144
144
  import { crmViewCommand, crmBulkCommand, crmWebformCommand } from '../lib/commands/crm-views-bulk-webforms.js';
145
145
  import { crmImportCommand, crmTagCommand, crmDedupeCommand, crmAuditCommand } from '../lib/commands/crm-import-dedupe-audit.js';
146
146
  import { crmObjectCommand, crmRelCommand } from '../lib/commands/crm-objects-relationships.js';
147
+ import { crmOrderCommand, crmFulfillmentCommand, crmReturnCommand } from '../lib/commands/crm-orders-returns.js';
147
148
  import { crmApprovalCommand, crmScoreCommand } from '../lib/commands/crm-approvals-scoring.js';
148
149
  import { featureDiscoveryGroup } from '../lib/commands/feature-discovery.js';
149
150
  import { billingInsightsGroup } from '../lib/commands/billing-insights.js';
@@ -342,6 +343,9 @@ await (registerStaffCommands ? registerStaffCommands(baseYargs) : baseYargs)
342
343
  .command(crmAuditCommand)
343
344
  .command(crmObjectCommand)
344
345
  .command(crmRelCommand)
346
+ .command(crmOrderCommand)
347
+ .command(crmFulfillmentCommand)
348
+ .command(crmReturnCommand)
345
349
  .command(crmApprovalCommand)
346
350
  .command(crmScoreCommand)
347
351
  .demandCommand(1, 'Specify a command. Run "velaro --help" for options.')
@@ -380,5 +380,146 @@ export const bookingCommand = {
380
380
  })
381
381
  .demandCommand(1, 'Specify an appointment action: list | get | cancel'),
382
382
  })
383
+ // -- floor + no-show + deposits + analytics (messaging FloorController / BookingsController) --
384
+ .command({
385
+ command: 'floor <action>',
386
+ describe: 'Scheduler floor -- waitlist, walk-ins, settings, tables, meeting links',
387
+ builder: y => y
388
+ .command({
389
+ command: 'waitlist',
390
+ describe: 'List the current waitlist and walk-ins',
391
+ handler: runCommand(async () => {
392
+ console.log(JSON.stringify(await messagingGet('/Floor/Waitlist'), null, 2));
393
+ }),
394
+ })
395
+ .command({
396
+ command: 'add',
397
+ describe: 'Add a guest to the waitlist (or record a walk-in with --walk-in)',
398
+ builder: y2 => y2
399
+ .option('name', { type: 'string', demandOption: true, describe: 'Guest name' })
400
+ .option('phone', { type: 'string', demandOption: true, describe: 'Phone for the table-ready text' })
401
+ .option('party-size', { type: 'number', demandOption: true, describe: 'Party size' })
402
+ .option('vip', { type: 'boolean', describe: 'VIP guest' })
403
+ .option('quoted-wait', { type: 'number', describe: 'Quoted wait in minutes' })
404
+ .option('notes', { type: 'string', describe: 'Notes' })
405
+ .option('walk-in', { type: 'boolean', describe: 'Record as a walk-in' }),
406
+ handler: runCommand(async argv => {
407
+ const body = { guestName: argv.name, phone: argv.phone, partySize: argv.partySize, isVip: argv.vip, quotedWaitMinutes: argv.quotedWait, notes: argv.notes };
408
+ console.log(JSON.stringify(await messagingPost(argv.walkIn ? '/Floor/WalkIn' : '/Floor/Waitlist', body), null, 2));
409
+ }),
410
+ })
411
+ .command({
412
+ command: 'entry <id> <verb>',
413
+ describe: 'Act on a waitlist entry: ready | seat | remove | noshow',
414
+ builder: y2 => y2
415
+ .positional('id', { type: 'number', describe: 'Waitlist entry id' })
416
+ .positional('verb', { type: 'string', choices: ['ready', 'seat', 'remove', 'noshow'] })
417
+ .option('resource-id', { type: 'number', describe: 'Table (resource) id, for seat' }),
418
+ handler: runCommand(async argv => {
419
+ const verbs = { ready: 'Ready', seat: 'Seat', remove: 'Remove', noshow: 'NoShow' };
420
+ const body = argv.resourceId != null ? { resourceId: argv.resourceId } : {};
421
+ console.log(JSON.stringify(await messagingPost(`/Floor/Waitlist/${argv.id}/${verbs[argv.verb]}`, body), null, 2));
422
+ }),
423
+ })
424
+ .command({
425
+ command: 'settings',
426
+ describe: 'Show floor settings, or change them with the flags',
427
+ builder: y2 => y2
428
+ .option('turn-minutes', { type: 'number', describe: 'Default turn minutes (5-600)' })
429
+ .option('overbook-percent', { type: 'number', describe: 'Overbook percent (0-50)' })
430
+ .option('seatings-json', { type: 'string', describe: 'Seatings JSON' })
431
+ .option('confirmation-sms', { type: 'boolean', describe: 'Send a booking confirmation SMS' })
432
+ .option('auto-meeting-link', { type: 'boolean', describe: 'Create meeting links automatically' })
433
+ .option('meeting-organizer', { type: 'string', describe: 'Meeting organizer UPN' })
434
+ .option('instructions', { type: 'string', describe: 'Default guest instructions' }),
435
+ handler: runCommand(async argv => {
436
+ const map = { defaultTurnMinutes: argv.turnMinutes, overbookPercent: argv.overbookPercent, seatingsJson: argv.seatingsJson, sendBookingConfirmationSms: argv.confirmationSms, autoCreateMeetingLink: argv.autoMeetingLink, meetingOrganizerUpn: argv.meetingOrganizer, defaultInstructions: argv.instructions };
437
+ const body = {}; for (const [k, v] of Object.entries(map)) if (v !== undefined) body[k] = v;
438
+ const result = Object.keys(body).length ? await messagingPut('/Floor/Settings', body) : await messagingGet('/Floor/Settings');
439
+ console.log(JSON.stringify(result, null, 2));
440
+ }),
441
+ })
442
+ .command({
443
+ command: 'table <resource-id>',
444
+ describe: 'Update a table (empty --combine-group clears it)',
445
+ builder: y2 => y2
446
+ .positional('resource-id', { type: 'number', describe: 'Table (resource) id' })
447
+ .option('min-party', { type: 'number' })
448
+ .option('max-party', { type: 'number' })
449
+ .option('turn-minutes', { type: 'number' })
450
+ .option('combine-group', { type: 'string' }),
451
+ handler: runCommand(async argv => {
452
+ const map = { minParty: argv.minParty, maxParty: argv.maxParty, turnMinutes: argv.turnMinutes, combineGroup: argv.combineGroup };
453
+ const body = {}; for (const [k, v] of Object.entries(map)) if (v !== undefined) body[k] = v;
454
+ console.log(JSON.stringify(await messagingPut(`/Floor/Tables/${argv.resourceId}`, body), null, 2));
455
+ }),
456
+ })
457
+ .command({
458
+ command: 'send-meeting-link <booking-id>',
459
+ describe: 'Send the meeting link for a booking now',
460
+ builder: y2 => y2
461
+ .positional('booking-id', { type: 'number' })
462
+ .option('channel', { type: 'string', choices: ['sms', 'email'], default: 'sms' }),
463
+ handler: runCommand(async argv => {
464
+ console.log(JSON.stringify(await messagingPost(`/Floor/Bookings/${argv.bookingId}/SendMeetingLink`, { channel: argv.channel }), null, 2));
465
+ }),
466
+ })
467
+ .demandCommand(1, 'Specify a floor action: waitlist | add | entry | settings | table | send-meeting-link'),
468
+ })
469
+ .command({
470
+ command: 'no-show <id>',
471
+ describe: 'Mark a booking as a no-show',
472
+ builder: y => y.positional('id', { type: 'number', describe: 'Booking id' }),
473
+ handler: runCommand(async argv => {
474
+ console.log(JSON.stringify(await messagingPost(`/Bookings/${argv.id}/no-show`, {}), null, 2));
475
+ }),
476
+ })
477
+ .command({
478
+ command: 'deposit <action>',
479
+ describe: 'Booking deposits -- set | link | status',
480
+ builder: y => y
481
+ .command({
482
+ command: 'set <id>',
483
+ describe: 'Require or clear a deposit on a booking',
484
+ builder: y2 => y2
485
+ .positional('id', { type: 'number', describe: 'Booking id' })
486
+ .option('required', { type: 'boolean', demandOption: true, describe: 'Whether a deposit is required' })
487
+ .option('amount', { type: 'number', describe: 'Deposit amount' }),
488
+ handler: runCommand(async argv => {
489
+ const body = { required: argv.required }; if (argv.amount != null) body.amount = argv.amount;
490
+ console.log(JSON.stringify(await messagingPut(`/Bookings/${argv.id}/deposit`, body), null, 2));
491
+ }),
492
+ })
493
+ .command({
494
+ command: 'link <id>',
495
+ describe: 'Create a deposit payment link',
496
+ builder: y2 => y2.positional('id', { type: 'number', describe: 'Booking id' }),
497
+ handler: runCommand(async argv => {
498
+ console.log(JSON.stringify(await messagingPost(`/Bookings/${argv.id}/deposit/link`, {}), null, 2));
499
+ }),
500
+ })
501
+ .command({
502
+ command: 'status <payment-id>',
503
+ describe: 'Check a deposit payment',
504
+ builder: y2 => y2.positional('payment-id', { type: 'string' }),
505
+ handler: runCommand(async argv => {
506
+ console.log(JSON.stringify(await messagingGet(`/Bookings/deposit/status?paymentId=${encodeURIComponent(argv.paymentId)}`), null, 2));
507
+ }),
508
+ })
509
+ .demandCommand(1, 'Specify a deposit action: set | link | status'),
510
+ })
511
+ .command({
512
+ command: 'analytics',
513
+ describe: 'Booking analytics for a date range',
514
+ builder: y => y
515
+ .option('from', { type: 'string', describe: 'Start, ISO 8601 UTC' })
516
+ .option('to', { type: 'string', describe: 'End, ISO 8601 UTC' }),
517
+ handler: runCommand(async argv => {
518
+ const q = new URLSearchParams();
519
+ if (argv.from) q.set('fromUtc', argv.from);
520
+ if (argv.to) q.set('toUtc', argv.to);
521
+ console.log(JSON.stringify(await messagingGet(`/Bookings/analytics${q.toString() ? '?' + q : ''}`), null, 2));
522
+ }),
523
+ })
383
524
  .demandCommand(1, 'Specify a subcommand: resource | service | availability | appointment'),
384
525
  };
@@ -0,0 +1,272 @@
1
+ import { messagingGet, messagingPost } from '../api.js';
2
+ import { runCommand } from '../run.js';
3
+
4
+ // -- velaro crm-order / crm-fulfillment / crm-return ----------------------------
5
+ // CLI for CRM orders, fulfillment and RMA (docs/architecture/crm-orders-rma.md):
6
+ // crm-order CrmOrdersController /CrmOrders (orders, their lines, history)
7
+ // crm-fulfillment CrmFulfillmentsController /CrmFulfillments (shipments with carrier and tracking)
8
+ // crm-return CrmReturnsController /CrmReturns (return authorizations and refunds)
9
+ // The site always comes from the signed-in credential; no command takes a site id. Every create and refund takes an
10
+ // --idempotency-key: the same key again returns what the first call made and changes nothing.
11
+ // MCP parity: mcp/parity/crm-orders-returns.customer.js (crm_order_*, crm_fulfillment_*, crm_return_* tools).
12
+
13
+ const BOLD = '\x1b[1m';
14
+ const DIM = '\x1b[2m';
15
+ const RST = '\x1b[0m';
16
+
17
+ const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
18
+ const printJson = (v) => console.log(JSON.stringify(v, null, 2));
19
+ const q = (o) => {
20
+ const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
21
+ return p.length ? `?${p.join('&')}` : '';
22
+ };
23
+ const json = (y) => y.option('json', { type: 'boolean', default: false, describe: 'Print raw JSON' });
24
+ const parseJson = (text, what) => {
25
+ try { return JSON.parse(text); } catch { throw new Error(`[CrmOrders] ${what} must be valid JSON.`); }
26
+ };
27
+ const done = (msg) => console.log(`\n ${msg}\n`);
28
+ const money = (n, c) => `${c ?? ''} ${Number(n ?? 0).toFixed(2)}`.trim();
29
+ const paging = (yy) => yy
30
+ .option('page', { type: 'number', default: 1 })
31
+ .option('page-size', { type: 'number', alias: 'pageSize', default: 25 });
32
+
33
+ const REASONS = ['defective', 'wrong_item', 'damaged', 'not_as_described', 'no_longer_needed', 'other'];
34
+ const METHODS = ['original_payment', 'store_credit', 'adjustment_credit'];
35
+ const STATUSES = ['open', 'partially_fulfilled', 'fulfilled', 'cancelled'];
36
+ const RETURN_STATUSES = ['requested', 'approved', 'received', 'refunded', 'closed', 'denied'];
37
+
38
+ // ---------------------------------------------------------------- orders
39
+
40
+ async function orderListHandler(argv) {
41
+ const r = data(await messagingGet(`/CrmOrders${q({ status: argv.status, contactId: argv.contactId, companyId: argv.companyId, dealId: argv.dealId, search: argv.search, page: argv.page, pageSize: argv.pageSize })}`));
42
+ if (argv.json) return printJson(r);
43
+ console.log(`\n${BOLD}Orders${RST} (${r?.total ?? 0})`);
44
+ for (const o of r?.items ?? []) console.log(` #${o.id} ${o.orderNumber} ${o.status} ${money(o.total, o.currency)} ${DIM}${o.externalSystem ?? ''}${RST}`);
45
+ console.log('');
46
+ }
47
+
48
+ function printOrder(v) {
49
+ const o = v.order;
50
+ console.log(`\n${BOLD}Order ${o.orderNumber}${RST} ${o.status} ${money(o.total, o.currency)}`);
51
+ for (const l of v.lines ?? []) console.log(` line ${l.lineNumber} ${l.name}${l.sku ? ` (${l.sku})` : ''} ordered ${l.quantity}, shipped ${l.quantityShipped}, returned ${l.quantityReturned} ${money(l.lineTotal, o.currency)}`);
52
+ for (const f of v.fulfillments ?? []) console.log(` shipment #${f.id} ${f.carrier ?? ''} ${f.trackingNumber ?? ''} ${f.status}`);
53
+ for (const r of v.returns ?? []) console.log(` return #${r.id} ${r.rmaNumber} ${r.status} worth ${money(r.maxRefundAmount, r.currency)}`);
54
+ if (o.externalSyncNote) console.log(` ${DIM}${o.externalSyncNote}${RST}`);
55
+ console.log('');
56
+ }
57
+
58
+ async function orderGetHandler(argv) {
59
+ const r = data(await messagingGet(`/CrmOrders/${argv.id}`));
60
+ return argv.json ? printJson(r) : printOrder(r);
61
+ }
62
+
63
+ async function orderFindHandler(argv) {
64
+ const r = data(await messagingGet(`/CrmOrders/by-number/${encodeURIComponent(argv.number)}`));
65
+ return argv.json ? printJson(r) : printOrder(r);
66
+ }
67
+
68
+ // --lines is a JSON array of { sku, name, quantity, unitPrice, discount }.
69
+ async function orderCreateHandler(argv) {
70
+ const body = {
71
+ contactId: argv.contactId, companyId: argv.companyId, dealId: argv.dealId, conversationId: argv.conversationId,
72
+ orderNumber: argv.orderNumber, currency: argv.currency, shippingAmount: argv.shipping, taxAmount: argv.tax, notes: argv.notes,
73
+ externalSystem: argv.externalSystem, externalId: argv.externalId, idempotencyKey: argv.idempotencyKey,
74
+ lines: parseJson(argv.lines, '--lines'),
75
+ };
76
+ const r = data(await messagingPost('/CrmOrders', body));
77
+ if (argv.json) return printJson(r);
78
+ done(`${r?.created === false ? 'Same order returned (the key was used before)' : 'Order created'}: ${r?.order?.order?.orderNumber} (#${r?.order?.order?.id}).`);
79
+ }
80
+
81
+ async function orderCancelHandler(argv) {
82
+ const r = data(await messagingPost(`/CrmOrders/${argv.id}/cancel`, {}));
83
+ if (argv.json) return printJson(r);
84
+ done(`Order ${r?.order?.orderNumber ?? argv.id} is ${r?.order?.status ?? 'cancelled'}.`);
85
+ }
86
+
87
+ async function orderAuditHandler(argv) {
88
+ const r = data(await messagingGet(`/CrmOrders/${argv.id}/audit${q({ page: argv.page, pageSize: argv.pageSize })}`));
89
+ if (argv.json) return printJson(r);
90
+ console.log(`\n${BOLD}History of order #${argv.id}${RST} (${r?.total ?? 0})`);
91
+ for (const a of r?.items ?? []) console.log(` ${a.changedAt} ${a.actor} ${a.newValue ?? a.field}`);
92
+ console.log('');
93
+ }
94
+
95
+ export const crmOrderCommand = {
96
+ command: 'crm-order <subcommand>',
97
+ describe: 'CRM orders: create, list, read, cancel and see the history of an order',
98
+ builder: (y) => y
99
+ .command({
100
+ command: 'list',
101
+ describe: 'List orders, newest first',
102
+ builder: (yy) => json(paging(yy)
103
+ .option('status', { choices: STATUSES })
104
+ .option('contact-id', { type: 'number', alias: 'contactId' })
105
+ .option('company-id', { type: 'number', alias: 'companyId' })
106
+ .option('deal-id', { type: 'number', alias: 'dealId' })
107
+ .option('search', { type: 'string', describe: 'Part of the order number' })),
108
+ handler: runCommand(orderListHandler),
109
+ })
110
+ .command({ command: 'get <id>', describe: 'Show an order with its lines, shipments and returns', builder: json, handler: runCommand(orderGetHandler) })
111
+ .command({ command: 'find <number>', describe: 'Show an order by its order number', builder: json, handler: runCommand(orderFindHandler) })
112
+ .command({
113
+ command: 'create',
114
+ describe: 'Create an order (idempotent per --idempotency-key)',
115
+ builder: (yy) => json(yy
116
+ .option('lines', { type: 'string', demandOption: true, describe: 'JSON array of { sku, name, quantity, unitPrice, discount }' })
117
+ .option('contact-id', { type: 'number', alias: 'contactId' })
118
+ .option('company-id', { type: 'number', alias: 'companyId' })
119
+ .option('deal-id', { type: 'number', alias: 'dealId' })
120
+ .option('conversation-id', { type: 'number', alias: 'conversationId' })
121
+ .option('order-number', { type: 'string', alias: 'orderNumber', describe: 'Leave out to number it automatically' })
122
+ .option('currency', { type: 'string', describe: '3-letter code, default USD' })
123
+ .option('shipping', { type: 'number', default: 0 })
124
+ .option('tax', { type: 'number', default: 0 })
125
+ .option('notes', { type: 'string' })
126
+ .option('external-system', { type: 'string', alias: 'externalSystem', describe: 'Connected system that also holds the order, for example Shopify' })
127
+ .option('external-id', { type: 'string', alias: 'externalId', describe: 'The order id or number in that system' })
128
+ .option('idempotency-key', { type: 'string', alias: 'idempotencyKey' })),
129
+ handler: runCommand(orderCreateHandler),
130
+ })
131
+ .command({ command: 'cancel <id>', describe: 'Cancel an order that has not shipped and has no return', builder: json, handler: runCommand(orderCancelHandler) })
132
+ .command({ command: 'audit <id>', describe: 'Who changed the order, its shipments and its returns', builder: (yy) => json(paging(yy)), handler: runCommand(orderAuditHandler) })
133
+ .demandCommand(1),
134
+ handler: () => {},
135
+ };
136
+
137
+ // ---------------------------------------------------------------- shipments
138
+
139
+ async function shipListHandler(argv) {
140
+ const r = data(await messagingGet(`/CrmFulfillments?orderId=${encodeURIComponent(argv.orderId)}`));
141
+ if (argv.json) return printJson(r);
142
+ console.log(`\n${BOLD}Shipments of order #${argv.orderId}${RST} (${r?.items?.length ?? 0})`);
143
+ for (const f of r?.items ?? []) console.log(` #${f.id} ${f.carrier ?? ''} ${f.trackingNumber ?? ''} ${f.status} ${(f.lines ?? []).map((l) => `${l.quantity} x line ${l.orderLineId}`).join(', ')}`);
144
+ console.log('');
145
+ }
146
+
147
+ // Ships --lines (JSON array of { orderLineId, quantity }) or everything left with --all. Over-shipping is a 400.
148
+ async function shipHandler(argv) {
149
+ const body = {
150
+ orderId: argv.orderId, carrier: argv.carrier, trackingNumber: argv.trackingNumber, trackingUrl: argv.trackingUrl, notes: argv.notes,
151
+ idempotencyKey: argv.idempotencyKey, shipAllRemaining: argv.all === true,
152
+ };
153
+ if (argv.lines) body.lines = parseJson(argv.lines, '--lines');
154
+ const r = data(await messagingPost('/CrmFulfillments', body));
155
+ if (argv.json) return printJson(r);
156
+ done(`${r?.created === false ? 'Same shipment returned (the key was used before)' : 'Shipment saved'}: #${r?.fulfillment?.id}. The order is ${r?.order?.order?.status}.`);
157
+ }
158
+
159
+ async function deliveredHandler(argv) {
160
+ const r = data(await messagingPost(`/CrmFulfillments/${argv.id}/delivered`, {}));
161
+ if (argv.json) return printJson(r);
162
+ done(`Shipment ${argv.id} is ${r?.status ?? 'delivered'}.`);
163
+ }
164
+
165
+ export const crmFulfillmentCommand = {
166
+ command: 'crm-fulfillment <subcommand>',
167
+ describe: 'CRM shipments: ship some or all of an order, with carrier and tracking number',
168
+ builder: (y) => y
169
+ .command({ command: 'list <orderId>', describe: 'List the shipments of an order', builder: (yy) => json(yy.positional('orderId', { type: 'number' })), handler: runCommand(shipListHandler) })
170
+ .command({
171
+ command: 'ship <orderId>',
172
+ describe: 'Ship items of an order (a line can never ship more than was ordered)',
173
+ builder: (yy) => json(yy.positional('orderId', { type: 'number' })
174
+ .option('lines', { type: 'string', describe: 'JSON array of { orderLineId, quantity }' })
175
+ .option('all', { type: 'boolean', describe: 'Ship every unit still waiting' })
176
+ .option('carrier', { type: 'string' })
177
+ .option('tracking-number', { type: 'string', alias: 'trackingNumber' })
178
+ .option('tracking-url', { type: 'string', alias: 'trackingUrl' })
179
+ .option('notes', { type: 'string' })
180
+ .option('idempotency-key', { type: 'string', alias: 'idempotencyKey' })),
181
+ handler: runCommand(shipHandler),
182
+ })
183
+ .command({ command: 'delivered <id>', describe: 'Mark a shipment delivered', builder: json, handler: runCommand(deliveredHandler) })
184
+ .demandCommand(1),
185
+ handler: () => {},
186
+ };
187
+
188
+ // ---------------------------------------------------------------- returns
189
+
190
+ async function returnListHandler(argv) {
191
+ const r = data(await messagingGet(`/CrmReturns${q({ orderId: argv.orderId, status: argv.status, page: argv.page, pageSize: argv.pageSize })}`));
192
+ if (argv.json) return printJson(r);
193
+ console.log(`\n${BOLD}Returns${RST} (${r?.total ?? 0})`);
194
+ for (const x of r?.items ?? []) console.log(` #${x.id} ${x.rmaNumber} ${x.status} worth ${money(x.maxRefundAmount, x.currency)} ${x.reasonCode}`);
195
+ console.log('');
196
+ }
197
+
198
+ async function returnGetHandler(argv) {
199
+ const r = data(await messagingGet(`/CrmReturns/${argv.id}`));
200
+ printJson(r);
201
+ }
202
+
203
+ async function returnFindHandler(argv) {
204
+ printJson(data(await messagingGet(`/CrmReturns/by-number/${encodeURIComponent(argv.number)}`)));
205
+ }
206
+
207
+ // --lines is a JSON array of { orderLineId, quantity }: at most shipped minus already returned per line.
208
+ async function returnCreateHandler(argv) {
209
+ const r = data(await messagingPost('/CrmReturns', {
210
+ orderId: argv.orderId, reasonCode: argv.reason, reasonNote: argv.note, idempotencyKey: argv.idempotencyKey, lines: parseJson(argv.lines, '--lines'),
211
+ }));
212
+ if (argv.json) return printJson(r);
213
+ done(`${r?.created === false ? 'Same return returned (the key was used before)' : 'Return requested'}: ${r?.return?.rmaNumber} (#${r?.return?.id}), worth ${money(r?.return?.maxRefundAmount, r?.return?.currency)}. It needs approval before it can be refunded.`);
214
+ }
215
+
216
+ const move = (verb, past) => async (argv) => {
217
+ const body = verb === 'receive' ? {} : { comment: argv.comment };
218
+ const r = data(await messagingPost(`/CrmReturns/${argv.id}/${verb}`, body));
219
+ if (argv.json) return printJson(r);
220
+ done(`Return ${r?.rmaNumber ?? argv.id} is now ${r?.status ?? past}.`);
221
+ };
222
+
223
+ // 200 = refunded or replayed, 202 = waiting for a Manager's approval (nothing refunded). A refusal by the money policy is a 403 and exits non-zero.
224
+ async function returnRefundHandler(argv) {
225
+ const r = data(await messagingPost(`/CrmReturns/${argv.id}/refund`, { amount: argv.amount, method: argv.method, reason: argv.reason, idempotencyKey: argv.idempotencyKey }));
226
+ if (argv.json) return printJson(r);
227
+ done(`${r?.decision}: ${r?.message ?? ''}`);
228
+ }
229
+
230
+ const idArg = (yy) => yy.positional('id', { type: 'number' });
231
+
232
+ export const crmReturnCommand = {
233
+ command: 'crm-return <subcommand>',
234
+ describe: 'CRM return authorizations (RMA): request, approve, receive and refund returns',
235
+ builder: (y) => y
236
+ .command({
237
+ command: 'list',
238
+ describe: 'List returns, newest first',
239
+ builder: (yy) => json(paging(yy)
240
+ .option('order-id', { type: 'number', alias: 'orderId' })
241
+ .option('status', { choices: RETURN_STATUSES })),
242
+ handler: runCommand(returnListHandler),
243
+ })
244
+ .command({ command: 'get <id>', describe: 'Show one return', builder: idArg, handler: runCommand(returnGetHandler) })
245
+ .command({ command: 'find <number>', describe: 'Show a return by its RMA number', handler: runCommand(returnFindHandler) })
246
+ .command({
247
+ command: 'create <orderId>',
248
+ describe: 'Request a return (idempotent per --idempotency-key; never more than shipped minus already returned)',
249
+ builder: (yy) => json(yy.positional('orderId', { type: 'number' })
250
+ .option('lines', { type: 'string', demandOption: true, describe: 'JSON array of { orderLineId, quantity }' })
251
+ .option('reason', { choices: REASONS, default: 'other' })
252
+ .option('note', { type: 'string' })
253
+ .option('idempotency-key', { type: 'string', alias: 'idempotencyKey' })),
254
+ handler: runCommand(returnCreateHandler),
255
+ })
256
+ .command({ command: 'approve <id>', describe: 'Approve a return (Manager or Administrator)', builder: (yy) => json(idArg(yy).option('comment', { type: 'string' })), handler: runCommand(move('approve', 'approved')) })
257
+ .command({ command: 'deny <id>', describe: 'Deny a return with a comment (Manager or Administrator); its units go back to the order', builder: (yy) => json(idArg(yy).option('comment', { type: 'string', demandOption: true })), handler: runCommand(move('deny', 'denied')) })
258
+ .command({ command: 'receive <id>', describe: 'Mark the returned items received', builder: (yy) => json(idArg(yy)), handler: runCommand(move('receive', 'received')) })
259
+ .command({ command: 'close <id>', describe: 'Close a return (before the items arrived, its units go back to the order)', builder: (yy) => json(idArg(yy).option('comment', { type: 'string' })), handler: runCommand(move('close', 'closed')) })
260
+ .command({
261
+ command: 'refund <id>',
262
+ describe: 'Refund a received return through the approval rules and your money policy (idempotent per --idempotency-key)',
263
+ builder: (yy) => json(idArg(yy)
264
+ .option('amount', { type: 'number', describe: 'Defaults to the value of the returned items; never more' })
265
+ .option('method', { choices: METHODS, default: 'original_payment' })
266
+ .option('reason', { type: 'string' })
267
+ .option('idempotency-key', { type: 'string', alias: 'idempotencyKey' })),
268
+ handler: runCommand(returnRefundHandler),
269
+ })
270
+ .demandCommand(1),
271
+ handler: () => {},
272
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/cli",
3
- "version": "1.4.228",
3
+ "version": "1.4.230",
4
4
  "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
5
5
  "type": "module",
6
6
  "bin": {