@onereach/step-voice 7.0.46-deskphoneintegration.13 → 7.0.46-deskphoneintegration.15

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.
@@ -1,4 +1,4 @@
1
- import VoiceStep, { CallStartEvent, TODO, VoiceEvent } from './voice';
1
+ import VoiceStep, { CallStartEvent, TODO } from './voice';
2
2
  import { IEvent } from '@onereach/flow-sdk/dst/types/event';
3
3
  import { DeskphoneConferenceEntry } from './deskphoneCorrelation';
4
4
  import { CarrierEnvelope } from './completeTransfer';
@@ -23,26 +23,30 @@ interface DeskphoneXferState {
23
23
  }
24
24
  export default class WaitForDeskPhoneCall extends VoiceStep<TODO, TODO, TODO> {
25
25
  get conversation(): string | import("@onereach/flow-sdk/types").IMergeField;
26
- runStep(): Promise<any>;
26
+ runStep(): Promise<void>;
27
27
  onCall(event: IEvent<CallStartEvent>): Promise<any>;
28
28
  /**
29
- * Named waiting state (resolves MEDIUM-1). Re-armed on every entry so the thread parks here across
30
- * events: the consult-leg BYE surfaces on `in/voice/<consultCallId>`; C's join/list results surface
31
- * on the A-leg stream `in/voice/<carrierCallId>`. Returns without exitStep/exitFlow so the step
32
- * stays alive (mirrors Initiate Call.waitForCall).
29
+ * Attended-transfer COMPLETION handler, driven by the `in/voice/deskphone/<sipUser>/transfer`
30
+ * event (NOT by a consult-leg BYE, NOT by a parked gotoState). Registered as a persistent `on` in
31
+ * `runStep`; per the trigger-lifetime finding (DESIGN §1) it is still live after the `/call`
32
+ * handoff to Initiate Call, so when desk-2001 presses Transfer the second time (SIP REFER ->
33
+ * Kamailio -> controller emits `/transfer`) this handler runs the completion on the LIVE A-leg
34
+ * carrier recorded in the correlation entry. Does NOT call exitStep: the step stays alive on its
35
+ * persistent subscriptions (mirrors how the `/call` listener keeps living).
33
36
  */
34
- awaitConsultComplete(): Promise<void>;
37
+ onTransfer(event: IEvent<TODO>): Promise<void>;
35
38
  /** Minimal routable envelope that carries completion commands on the LIVE A-leg. */
36
39
  carrierEnvelope(x: DeskphoneXferState): CarrierEnvelope;
37
- onConsultEvent(event: IEvent<VoiceEvent>): Promise<any>;
38
40
  /**
39
41
  * Job-2 completion wrapper around the SHARED `completeTransfer` helper (CC-5, DESIGN §4.3). The
40
42
  * leg-choreography (joinBot C -> listMembers -> relate clear -> unvmute -> kick B -> clear) lives in
41
43
  * the shared helper so Job 1 (`Conference Dial.ts`) and Job 2 use ONE code path. This wrapper only
42
- * builds the helper args from the step's `DeskphoneXferState` and owns the terminal action; the
43
- * caller (`onConsultEvent`) issues `exitStep('trigger')`. On a C-not-found abort the helper leaves
44
- * A+B intact and this returns without any further action.
44
+ * builds the helper args from the step's `DeskphoneXferState`; the caller (`onTransfer`) owns the
45
+ * trace of the boolean result. On a C-not-found abort the helper leaves A+B intact and returns
46
+ * `false` without any further action.
47
+ *
48
+ * @returns the shared helper's boolean result (`true` = C completed, `false` = C-not-found abort).
45
49
  */
46
- completeDeskphoneTransfer(x: DeskphoneXferState): Promise<void>;
50
+ completeDeskphoneTransfer(x: DeskphoneXferState): Promise<boolean>;
47
51
  }
48
52
  export {};
@@ -24,22 +24,19 @@ class WaitForDeskPhoneCall extends voice_1.default {
24
24
  sipUsernameTrimmed: sipUsername,
25
25
  willSubscribeCall: Boolean(sipUsername),
26
26
  callTrigger: sipUsername ? `in/voice/deskphone/${sipUsername}/call` : null,
27
- accountId: this.helpers.providersAccountId,
28
- resumeGuardCarrierCallId: this.state.deskphoneXfer?.carrierCallId ?? null,
29
- resumeGuardWillFire: Boolean(this.state.deskphoneXfer?.carrierCallId)
27
+ // Both subscriptions below are persistent `on` triggers registered pre-session: per the
28
+ // trigger-lifetime finding (DESIGN §1) they SURVIVE `exitStep('trigger')` to Initiate Call,
29
+ // so the `/transfer` listener is still live when desk-2001 presses Transfer the second time.
30
+ willSubscribeTransfer: Boolean(sipUsername),
31
+ transferTrigger: sipUsername ? `in/voice/deskphone/${sipUsername}/transfer` : null,
32
+ accountId: this.helpers.providersAccountId
30
33
  });
31
34
  if (sipUsername) {
35
+ // `/call` -> onCall: ordinary breakout, ALWAYS exits to Initiate Call (DESIGN §2).
32
36
  this.triggers.on(`in/voice/deskphone/${sipUsername}/call`, this.onCall);
33
- }
34
- // Resume guard: a consult is already in flight (persisted across a thread resume) -> go straight
35
- // back to the waiting state and re-arm the completion listeners (named-state re-arm pattern).
36
- if (this.state.deskphoneXfer?.carrierCallId) {
37
- this.log.info('deskphone:trace:oncall runStep resume-guard fired', {
38
- carrierCallId: this.state.deskphoneXfer?.carrierCallId,
39
- consultCallId: this.state.deskphoneXfer?.consultCallId ?? null,
40
- phase: this.state.deskphoneXfer?.phase ?? null
41
- });
42
- return this.gotoState('awaitConsultComplete');
37
+ // `/transfer` -> onTransfer: attended-transfer completion. Registered here (pre-session) so it
38
+ // is a true `on` that persists past the `/call` handoff to Initiate Call (DESIGN §1d/§1e).
39
+ this.triggers.on(`in/voice/deskphone/${sipUsername}/transfer`, this.onTransfer);
43
40
  }
44
41
  }
45
42
  async onCall(event) {
@@ -65,6 +62,9 @@ class WaitForDeskPhoneCall extends voice_1.default {
65
62
  // variable_sip_req_user / variable_sip_to_user = +17202392838. The dialed number MUST come from
66
63
  // `channel.to`; using `fromUser` dials the literal desk username and yields UNALLOCATED_NUMBER.
67
64
  const dialedNumber = event.params.channel.to ?? 'unknown';
65
+ // Correlation read is TRACE-ONLY on the `/call` path (DESIGN §2.1): the outbound desk-phone call
66
+ // ALWAYS takes the ordinary breakout and hands off to Initiate Call. The transfer completion is
67
+ // driven by the separate `/transfer` event (see onTransfer), NOT by a correlation entry here.
68
68
  const entry = await (0, deskphoneCorrelation_1.readDeskphoneConference)(this, accountId, fromUser);
69
69
  this.log.info('deskphone:trace:oncall correlation read result', {
70
70
  accountId,
@@ -73,6 +73,7 @@ class WaitForDeskPhoneCall extends voice_1.default {
73
73
  hasEntry: entry != null,
74
74
  entryAccountId: entry?.accountId ?? null,
75
75
  accountMatches: entry != null ? entry.accountId === accountId : null,
76
+ note: 'result no longer gates behavior; /call always takes always-exit path',
76
77
  entry: entry ?? null
77
78
  });
78
79
  const call = {
@@ -93,158 +94,120 @@ class WaitForDeskPhoneCall extends voice_1.default {
93
94
  call.dialedNumber = dialedNumber;
94
95
  call.fromUser = fromUser;
95
96
  this.log.warn(call, "call triggered Wait for desk phone");
96
- // Ordinary breakout (no correlation entry) OR cross-account mismatch -> UNCHANGED existing path.
97
- // A mismatch degrades safely to the ordinary breakout (A+B left intact); it is logged, not thrown.
97
+ // ALWAYS-EXIT path (DESIGN §2.1 / §3): the outbound desk-phone `/call` unconditionally starts the
98
+ // conversation and hands off to Initiate Call, which places the desk phone's outbound call to
99
+ // PSTN-2. The correlation entry read above is NOT a branch condition — a transfer is completed
100
+ // later via the persistent `/transfer` subscription (onTransfer), not by parking here.
101
+ const presetTime = (Number(endOfInputTimeout) || 0) * 60 * 1000;
102
+ const { sessionId: previousSessionId = '', beginningSessionId = '', } = event?.reporting ?? {};
103
+ await this.session.start({
104
+ timeout: presetTime || defaultSessionTimeout,
105
+ reporting: {
106
+ settingsKey: 'session',
107
+ startedBy: 'Visitor',
108
+ sessionType: 'Phone',
109
+ previousSessionId,
110
+ beginningSessionId
111
+ },
112
+ reportingSessions: [{
113
+ previousSessionId,
114
+ beginningSessionId
115
+ }]
116
+ });
117
+ await this.startConversation(call);
118
+ await this.transcript(call, {
119
+ action: 'Call Start',
120
+ reportingSettingsKey: 'transcript',
121
+ actionFromBot: false
122
+ });
123
+ this.log.info('deskphone:trace:oncall branch=always-exit', {
124
+ fromUser,
125
+ accountId,
126
+ dialedNumber,
127
+ hasEntry: entry != null,
128
+ nextStep: 'Initiate Call'
129
+ });
130
+ this.log.warn('run exit Wait for desk phone');
131
+ return this.exitStep('trigger');
132
+ }
133
+ /**
134
+ * Attended-transfer COMPLETION handler, driven by the `in/voice/deskphone/<sipUser>/transfer`
135
+ * event (NOT by a consult-leg BYE, NOT by a parked gotoState). Registered as a persistent `on` in
136
+ * `runStep`; per the trigger-lifetime finding (DESIGN §1) it is still live after the `/call`
137
+ * handoff to Initiate Call, so when desk-2001 presses Transfer the second time (SIP REFER ->
138
+ * Kamailio -> controller emits `/transfer`) this handler runs the completion on the LIVE A-leg
139
+ * carrier recorded in the correlation entry. Does NOT call exitStep: the step stays alive on its
140
+ * persistent subscriptions (mirrors how the `/call` listener keeps living).
141
+ */
142
+ async onTransfer(event) {
143
+ const accountId = this.helpers.providersAccountId;
144
+ const sipUser = String(this.data.sipUsername ?? '').trim();
145
+ const target = String(event.params?.target ?? '');
146
+ const replaces = event.params?.replaces ?? null;
147
+ const entry = await (0, deskphoneCorrelation_1.readDeskphoneConference)(this, accountId, sipUser);
148
+ this.log.info('deskphone:trace:xfer onTransfer entry', {
149
+ accountId,
150
+ sipUser,
151
+ target,
152
+ replaces,
153
+ hasEntry: entry != null,
154
+ entryAccountId: entry?.accountId ?? null,
155
+ params: event.params ?? null
156
+ });
157
+ // C = the transfer target from the `/transfer` event; the completion runs on the LIVE A-leg
158
+ // carrier recorded in the correlation entry (entry.callId / callback / callType / room /
159
+ // memberId / callerId / accountId) — the same fields completeTransfer consumes.
98
160
  if (!entry || entry.accountId !== accountId) {
99
- this.log.info('deskphone:trace:oncall branch=ordinary-breakout', {
100
- fromUser,
161
+ this.log.info('deskphone:trace:xfer onTransfer no/mismatched correlation entry; leaving A+B intact', {
101
162
  accountId,
102
- reason: !entry ? 'entry-missing' : 'account-mismatch',
163
+ sipUser,
164
+ target,
165
+ replaces,
103
166
  hasEntry: entry != null,
104
167
  entryAccountId: entry?.accountId ?? null
105
168
  });
106
- if (entry && entry.accountId !== accountId) {
107
- this.log.warn('deskphone transfer: account mismatch, ordinary breakout Wait for desk phone', { entryAccountId: entry.accountId, accountId });
108
- }
109
- const presetTime = (Number(endOfInputTimeout) || 0) * 60 * 1000;
110
- const { sessionId: previousSessionId = '', beginningSessionId = '', } = event?.reporting ?? {};
111
- await this.session.start({
112
- timeout: presetTime || defaultSessionTimeout,
113
- reporting: {
114
- settingsKey: 'session',
115
- startedBy: 'Visitor',
116
- sessionType: 'Phone',
117
- previousSessionId,
118
- beginningSessionId
119
- },
120
- reportingSessions: [{
121
- previousSessionId,
122
- beginningSessionId
123
- }]
124
- });
125
- await this.startConversation(call);
126
- await this.transcript(call, {
127
- action: 'Call Start',
128
- reportingSettingsKey: 'transcript',
129
- actionFromBot: false
130
- });
131
- this.log.warn('run exit Wait for desk phone');
132
- return this.exitStep('trigger');
169
+ return;
133
170
  }
134
- // TRANSFER. C = the dialed PSTN target (never the desk phone, never oct25sip).
135
- // Stash the state machine and transition to the named waiting state (re-arm pattern).
136
- // Do NOT splice, do NOT startConversation, do NOT arm a mid-handler local + bare return.
137
- this.log.info('deskphone:trace:oncall branch=transfer', {
138
- fromUser,
139
- accountId,
140
- C: event.params.channel.to,
141
- consultCallId: call.id,
142
- carrierCallId: entry.callId,
143
- entry
144
- });
145
- this.state.deskphoneXfer = {
146
- fromUser,
171
+ // Build the minimal DeskphoneXferState the shared wrapper consumes. The consult-leg fields are
172
+ // unused on this path (completion is event-driven), so carrier = the live A-leg carrier id.
173
+ const deskphoneXfer = {
174
+ fromUser: sipUser,
147
175
  entry,
148
- C: event.params.channel.to,
149
- consultCallId: call.id,
176
+ C: target,
177
+ consultCallId: '',
150
178
  carrierCallId: entry.callId,
151
- phase: 'await-bye'
179
+ phase: 'completing'
152
180
  };
153
- this.log.info('deskphone:trace:xfer state stashed; transitioning to awaitConsultComplete', {
154
- deskphoneXfer: this.state.deskphoneXfer
155
- });
156
- return this.gotoState('awaitConsultComplete');
157
- }
158
- /**
159
- * Named waiting state (resolves MEDIUM-1). Re-armed on every entry so the thread parks here across
160
- * events: the consult-leg BYE surfaces on `in/voice/<consultCallId>`; C's join/list results surface
161
- * on the A-leg stream `in/voice/<carrierCallId>`. Returns without exitStep/exitFlow so the step
162
- * stays alive (mirrors Initiate Call.waitForCall).
163
- */
164
- async awaitConsultComplete() {
165
- this.log.warn("awaitConsultComplete Wait for desk phone");
166
- const { carrierCallId, consultCallId } = this.state.deskphoneXfer;
167
- this.log.info('deskphone:trace:xfer awaitConsultComplete entry', {
168
- carrierCallId,
169
- consultCallId,
170
- carrierTrigger: `in/voice/${carrierCallId}`,
171
- consultTrigger: `in/voice/${consultCallId}`,
172
- phase: this.state.deskphoneXfer?.phase ?? null
181
+ this.log.info('deskphone:trace:xfer onTransfer before completeTransfer', {
182
+ accountId,
183
+ sipUser,
184
+ target,
185
+ replaces,
186
+ carrierCallId: entry.callId,
187
+ room: entry.room
173
188
  });
174
- this.triggers.local(`in/voice/${carrierCallId}`, this.onConsultEvent);
175
- this.triggers.local(`in/voice/${consultCallId}`, this.onConsultEvent);
176
- this.log.info('deskphone:trace:xfer awaitConsultComplete both triggers.local registered', {
177
- carrierTrigger: `in/voice/${carrierCallId}`,
178
- consultTrigger: `in/voice/${consultCallId}`
189
+ const completed = await this.completeDeskphoneTransfer(deskphoneXfer);
190
+ this.log.info('deskphone:trace:xfer onTransfer after completeTransfer', {
191
+ accountId,
192
+ sipUser,
193
+ target,
194
+ replaces,
195
+ result: completed
179
196
  });
180
197
  }
181
198
  /** Minimal routable envelope that carries completion commands on the LIVE A-leg. */
182
199
  carrierEnvelope(x) {
183
200
  return { id: x.carrierCallId, type: x.entry.callType, callback: x.entry.callback };
184
201
  }
185
- async onConsultEvent(event) {
186
- this.log.warn(event, "onConsultEvent Wait for desk phone");
187
- const x = this.state.deskphoneXfer;
188
- this.log.info('deskphone:trace:xfer consult-event', {
189
- type: event.params?.type ?? null,
190
- params: event.params ?? null,
191
- hasState: x != null,
192
- phase: x?.phase ?? null,
193
- carrierCallId: x?.carrierCallId ?? null,
194
- consultCallId: x?.consultCallId ?? null
195
- });
196
- if (!x) {
197
- this.log.info('deskphone:trace:xfer consult-event no state; ignoring', {
198
- type: event.params?.type ?? null
199
- });
200
- return;
201
- }
202
- switch (event.params.type) {
203
- case 'hangup': {
204
- this.log.warn(event, "onConsultEvent hangup Wait for desk phone");
205
- this.log.info('deskphone:trace:xfer consult-event case=hangup -> starting completion', {
206
- phaseBefore: x.phase,
207
- willAct: x.phase === 'await-bye'
208
- });
209
- // Consult-leg BYE = COMPLETION START. Only act once, while awaiting the BYE.
210
- if (x.phase !== 'await-bye') {
211
- this.log.info('deskphone:trace:xfer consult-event hangup ignored; not awaiting BYE', {
212
- phase: x.phase
213
- });
214
- return;
215
- }
216
- x.phase = 'completing';
217
- this.log.info('deskphone:trace:xfer consult-event phase flipped await-bye -> completing', {
218
- phaseAfter: x.phase
219
- });
220
- // C is the dialed PSTN target; run the ONE shared completion path (CC-5, DESIGN §4.3) on the
221
- // LIVE A-leg carrier: joinBot C -> listMembers -> relate clear -> unvmute -> kick B -> clear.
222
- // No new INVITE toward the phone. Job 2 keeps its `exitStep('trigger')` terminal.
223
- await this.completeDeskphoneTransfer(x);
224
- return this.exitStep('trigger');
225
- }
226
- case 'error': {
227
- this.log.warn(event, "onConsultEvent hangup Wait for desk phone");
228
- this.log.info('deskphone:trace:xfer consult-event case=error -> leaving A+B intact', {
229
- error: event.params.error ?? null
230
- });
231
- this.log.error('deskphone transfer consult/join error; leaving A+B intact', { error: event.params.error });
232
- return this.exitStep('trigger');
233
- }
234
- default:
235
- this.log.info('deskphone:trace:xfer consult-event case=default (ignored type)', {
236
- type: event.params?.type ?? null
237
- });
238
- return;
239
- }
240
- }
241
202
  /**
242
203
  * Job-2 completion wrapper around the SHARED `completeTransfer` helper (CC-5, DESIGN §4.3). The
243
204
  * leg-choreography (joinBot C -> listMembers -> relate clear -> unvmute -> kick B -> clear) lives in
244
205
  * the shared helper so Job 1 (`Conference Dial.ts`) and Job 2 use ONE code path. This wrapper only
245
- * builds the helper args from the step's `DeskphoneXferState` and owns the terminal action; the
246
- * caller (`onConsultEvent`) issues `exitStep('trigger')`. On a C-not-found abort the helper leaves
247
- * A+B intact and this returns without any further action.
206
+ * builds the helper args from the step's `DeskphoneXferState`; the caller (`onTransfer`) owns the
207
+ * trace of the boolean result. On a C-not-found abort the helper leaves A+B intact and returns
208
+ * `false` without any further action.
209
+ *
210
+ * @returns the shared helper's boolean result (`true` = C completed, `false` = C-not-found abort).
248
211
  */
249
212
  async completeDeskphoneTransfer(x) {
250
213
  const carrier = this.carrierEnvelope(x);
@@ -258,7 +221,7 @@ class WaitForDeskPhoneCall extends voice_1.default {
258
221
  bMemberId: x.entry.memberId,
259
222
  sipUser: x.fromUser
260
223
  });
261
- await (0, completeTransfer_1.completeTransfer)(this, {
224
+ const result = await (0, completeTransfer_1.completeTransfer)(this, {
262
225
  carrier,
263
226
  room: x.entry.room,
264
227
  accountId: x.entry.accountId,
@@ -271,9 +234,11 @@ class WaitForDeskPhoneCall extends voice_1.default {
271
234
  carrierId: carrier.id,
272
235
  room: x.entry.room,
273
236
  targetC: x.C,
274
- sipUser: x.fromUser
237
+ sipUser: x.fromUser,
238
+ result
275
239
  });
276
240
  this.log.warn("completeDeskphoneTransfer Wait for desk phone");
241
+ return result;
277
242
  }
278
243
  }
279
244
  exports.default = WaitForDeskPhoneCall;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onereach/step-voice",
3
- "version": "7.0.46-deskphoneintegration.13",
3
+ "version": "7.0.46-deskphoneintegration.15",
4
4
  "author": "Roman Zolotarov <roman.zolotarov@onereach.com>",
5
5
  "contributors": [
6
6
  "Roman Zolotarov",