@onereach/step-voice 7.0.45 → 7.0.46-deskphoneintegration.10

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/README.md CHANGED
@@ -8,3 +8,10 @@
8
8
 
9
9
  - ``` npm run upload-prod ```
10
10
  - ``` npm run upload-dev ```
11
+
12
+
13
+ ### Publish flow for testing
14
+ 1. NO_VERIFY=1 npm run pub-prerelease
15
+ 2. npm run update-module-versions 7.0.46-deskphoneintegration.6
16
+ 3. npm run patch-steps
17
+ 4. npm run deploy
@@ -1,10 +1,48 @@
1
1
  import VoiceStep from './voice';
2
- export default class ConferenceDial extends VoiceStep<{
2
+ declare const enum GATEWAY_SETTINGS_MODE {
3
+ DEFAULT = "default",
4
+ CUSTOM = "custom",
5
+ INHERIT = "inherit",
6
+ PROFILE = "profile"
7
+ }
8
+ declare const enum SIP_PROFILE {
9
+ DEFAULT = "default",
10
+ INTERNAL = "internal",
11
+ EXTERNAL = "external"
12
+ }
13
+ type ConferenceDialInput = {
3
14
  stayInConference: boolean;
4
15
  sourceConf: string;
5
16
  botNumber: string;
6
17
  headers?: Record<string, string>;
7
18
  hearOnly: boolean;
8
- }> {
19
+ /**
20
+ * The SIP caller identity presented on the dialed leg (becomes `variable_sip_from_user`). For a
21
+ * desk-phone breakout (`isDeskPhone === true`) this MUST be an enabled `subscriber.username`
22
+ * because voicer resolves the account from it; an empty or non-subscriber value is refused by the
23
+ * switch. When empty/absent the param is omitted from the dial entirely (never sent as an empty
24
+ * string or the literal `undefined`).
25
+ */
26
+ fromNumber?: string;
27
+ /**
28
+ * Set `true` only on the step instance that dials the desk phone. When true (and `botNumber`
29
+ * trims to a non-empty SIP username), the step records a desk-phone correlation entry on
30
+ * `conference-start` and clears it on `hangup`/`conference-end`. Default `false` — every existing
31
+ * use leaves it absent, so their behavior is unchanged.
32
+ */
33
+ isDeskPhone?: boolean;
34
+ /**
35
+ * SIP gateway/profile selector (mirrors Initiate Call). Optional — when no profile/custom host
36
+ * is selected no gateway is attached and the conference join is unchanged. `isDeskPhone` alone
37
+ * does NOT synthesize a gateway.
38
+ */
39
+ gatewaySettingsMode?: GATEWAY_SETTINGS_MODE;
40
+ sipProfile?: SIP_PROFILE;
41
+ sipHost?: string;
42
+ sipUser?: string;
43
+ sipPassword?: string;
44
+ };
45
+ export default class ConferenceDial extends VoiceStep<ConferenceDialInput> {
9
46
  runStep(): Promise<void>;
10
47
  }
48
+ export {};
@@ -3,16 +3,80 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  const tslib_1 = require("tslib");
4
4
  const lodash_1 = tslib_1.__importDefault(require("lodash"));
5
5
  const voice_1 = tslib_1.__importDefault(require("./voice"));
6
+ const deskphoneCorrelation_1 = require("./deskphoneCorrelation");
7
+ const completeTransfer_1 = require("./completeTransfer");
8
+ /** The internal SBC host desk-phone / extension legs dial through (DESIGN §4.1). */
9
+ const INTERNAL_SBC_HOST = 'sip.staging.onereach.ai';
10
+ /**
11
+ * The per-target-class joinBot shape for Job-1 completion (DESIGN §4.1/§4.2).
12
+ *
13
+ * - INTERNAL target (bare extension, e.g. `2222`): a `sip:<target>@<SBC host>` URI over the
14
+ * internal profile, so `buildJoinBotDial` honors the embedded host (never a hostless loopback
15
+ * dial). The member-list match value is the bare extension.
16
+ * - PSTN target (`+E164`): the bare number over the external gateway + owned DID. Member-list match
17
+ * is the bare number.
18
+ */
19
+ function resolveTransferTargetClass(target) {
20
+ const t = lodash_1.default.trim(target);
21
+ // PSTN if a +E164-style number; otherwise treat as an internal extension (DESIGN §4.1 default).
22
+ if (/^\+?\d{6,}$/.test(t) && lodash_1.default.startsWith(t, '+')) {
23
+ return { botNumber: t, targetMatch: t, gateway: { profile: 'external' } };
24
+ }
25
+ return {
26
+ botNumber: `sip:${t}@${INTERNAL_SBC_HOST}`,
27
+ targetMatch: t,
28
+ gateway: { profile: 'internal' }
29
+ };
30
+ }
31
+ /** The gate shared by the correlation write and both clears (identical gate + trimmed key). */
32
+ function isDeskPhoneSipUser(data) {
33
+ return data.isDeskPhone === true && lodash_1.default.trim(String(data.botNumber ?? '')) !== '';
34
+ }
35
+ /** True when a desk-phone dial is requested but no caller (From) identity was provided. */
36
+ function isDeskPhoneWithoutFromNumber(data) {
37
+ return data.isDeskPhone === true && lodash_1.default.trim(String(data.fromNumber ?? '')) === '';
38
+ }
6
39
  class ConferenceDial extends voice_1.default {
7
40
  async runStep() {
8
41
  const call = await this.fetchData();
42
+ // Desk-phone attended-transfer COMPLETION (Job 1, CC-3): subscribe to the SIP-user-keyed transfer
43
+ // event voicer emits (`in/voice/deskphone/<sipUser>/transfer`). Keyed by the SAME trimmed SIP user
44
+ // the correlation write uses. On receipt, stash { target, replaces } so the subsequent
45
+ // conference-end (B leaving) runs the completion on the live A-leg.
46
+ if (isDeskPhoneSipUser(this.data)) {
47
+ const sipUser = lodash_1.default.trim(String(this.data.botNumber ?? ''));
48
+ this.triggers.local(`in/voice/deskphone/${sipUser}/transfer`, async (event) => {
49
+ this.state.pendingTransfer = {
50
+ target: event.params.target,
51
+ replaces: event.params.replaces
52
+ };
53
+ });
54
+ }
9
55
  this.triggers
10
56
  .local(`in/voice/${call.id}`, async (event) => {
11
57
  switch (event.params.type) {
12
58
  case 'hangup':
59
+ if (isDeskPhoneSipUser(this.data)) {
60
+ await (0, deskphoneCorrelation_1.clearDeskphoneConference)(this, this.helpers.providersAccountId, lodash_1.default.trim(String(this.data.botNumber ?? '')));
61
+ }
13
62
  await this.handleHangup(call);
14
63
  return await this.waitConvEnd();
15
64
  case 'conference-start':
65
+ if (isDeskPhoneSipUser(this.data)) {
66
+ const sipUser = lodash_1.default.trim(String(this.data.botNumber ?? ''));
67
+ const owningCall = await this.fetchData();
68
+ const accountId = this.helpers.providersAccountId;
69
+ await (0, deskphoneCorrelation_1.writeDeskphoneConference)(this, accountId, sipUser, {
70
+ accountId,
71
+ room: this.data.sourceConf,
72
+ memberId: event.params.user,
73
+ callerId: owningCall.botNumber,
74
+ callId: owningCall.id,
75
+ callType: owningCall.type,
76
+ callback: owningCall.callback,
77
+ bConvId: this.conversationId
78
+ });
79
+ }
16
80
  if (this.data.stayInConference) {
17
81
  return this.exitFlow();
18
82
  }
@@ -20,6 +84,41 @@ class ConferenceDial extends voice_1.default {
20
84
  return this.exitStep('next', lodash_1.default.omit(event.params, ['type']));
21
85
  }
22
86
  case 'conference-end':
87
+ if (isDeskPhoneSipUser(this.data)) {
88
+ const sipUser = lodash_1.default.trim(String(this.data.botNumber ?? ''));
89
+ const accountId = this.helpers.providersAccountId;
90
+ const pending = this.state?.pendingTransfer;
91
+ const target = lodash_1.default.trim(String(pending?.target ?? ''));
92
+ // Job-1 COMPLETION (DESIGN §3.3/§4.3): B (desk-2001) left the conference AND a transfer
93
+ // target was captured within the window -> bring C into the room on the LIVE A-leg, then
94
+ // take the branch's existing terminal. The correlation entry (B's member id + A-leg
95
+ // carrier) was written by this step at B's join; read it back to drive the kick.
96
+ if (target !== '') {
97
+ const owningCall = await this.fetchData();
98
+ const entry = await (0, deskphoneCorrelation_1.readDeskphoneConference)(this, accountId, sipUser);
99
+ if (entry) {
100
+ const { botNumber, targetMatch, gateway } = resolveTransferTargetClass(target);
101
+ await (0, completeTransfer_1.completeTransfer)(this, {
102
+ carrier: { id: owningCall.id, type: owningCall.type, callback: owningCall.callback },
103
+ room: this.data.sourceConf,
104
+ accountId,
105
+ targetC: botNumber,
106
+ targetMatch,
107
+ gateway,
108
+ // Owned DID = the conference-owning botNumber. NEVER the SIP user, NEVER oct25sip.
109
+ fromNumber: owningCall.botNumber,
110
+ bMemberId: entry.memberId,
111
+ sipUser
112
+ });
113
+ this.state.pendingTransfer = undefined;
114
+ return this.data.stayInConference ? this.exitStep('next') : this.exitFlow();
115
+ }
116
+ // No correlation entry (should not happen if this step wrote it) -> fall through to
117
+ // the ordinary clear + terminal below, leaving A+B as-is.
118
+ }
119
+ // No transfer captured (ordinary hangup, §5 guard): clear correlation and exit as today.
120
+ await (0, deskphoneCorrelation_1.clearDeskphoneConference)(this, accountId, sipUser);
121
+ }
23
122
  return this.data.stayInConference ? this.exitStep('next') : this.exitFlow();
24
123
  case 'error':
25
124
  return this.throwError(event.params.error);
@@ -29,6 +128,25 @@ class ConferenceDial extends voice_1.default {
29
128
  });
30
129
  this.triggers.otherwise(async () => {
31
130
  const { sourceConf, botNumber, headers, hearOnly } = this.data;
131
+ if (isDeskPhoneWithoutFromNumber(this.data)) {
132
+ this.throwError(new Error("Conference Dial: 'Caller (From)' is required when 'Desk phone dial' is enabled. " +
133
+ 'It must be an enabled desk-phone subscriber username (e.g. desk-2001) so the platform ' +
134
+ 'can resolve the account; an empty or non-subscriber value is refused by the switch.'));
135
+ }
136
+ const fromNumber = lodash_1.default.trim(String(this.data.fromNumber ?? ''));
137
+ const { gatewaySettingsMode, sipProfile, sipHost, sipUser, sipPassword } = this.data;
138
+ // Hardened vs Initiate Call (null-safe): sipProfile is optional here. Does NOT branch on isDeskPhone.
139
+ const profile = sipProfile != null && sipProfile !== "default" /* SIP_PROFILE.DEFAULT */ ? sipProfile : undefined;
140
+ let gateway;
141
+ switch (gatewaySettingsMode) {
142
+ case "custom" /* GATEWAY_SETTINGS_MODE.CUSTOM */:
143
+ gateway = { host: sipHost, user: sipUser, username: sipUser, password: sipPassword, profile };
144
+ break;
145
+ case "profile" /* GATEWAY_SETTINGS_MODE.PROFILE */:
146
+ gateway = profile != null ? { profile } : undefined;
147
+ break;
148
+ // DEFAULT / INHERIT / undefined -> gateway stays undefined (today's behavior)
149
+ }
32
150
  const command = {
33
151
  name: 'conference.joinBot',
34
152
  params: {
@@ -36,7 +154,9 @@ class ConferenceDial extends voice_1.default {
36
154
  botNumber,
37
155
  headers,
38
156
  hearOnly,
39
- stayInConference: this.data.stayInConference
157
+ stayInConference: this.data.stayInConference,
158
+ ...(fromNumber !== '' ? { fromNumber } : {}),
159
+ ...(gateway != null ? { gateway } : {})
40
160
  }
41
161
  };
42
162
  await this.sendCommands(call, [command]);
@@ -0,0 +1,48 @@
1
+ import VoiceStep, { CallStartEvent, TODO, VoiceEvent } from './voice';
2
+ import { IEvent } from '@onereach/flow-sdk/dst/types/event';
3
+ import { DeskphoneConferenceEntry } from './deskphoneCorrelation';
4
+ import { CarrierEnvelope } from './completeTransfer';
5
+ /** The in-flight attended-transfer state machine stashed on `this.state.deskphoneXfer`. */
6
+ interface DeskphoneXferState {
7
+ /** trimmed desk-phone SIP username (the correlation key), e.g. `desk-2001`. */
8
+ fromUser: string;
9
+ /** the correlation entry recorded by Conference Dial at B's join. */
10
+ entry: DeskphoneConferenceEntry;
11
+ /** the transfer target (PSTN C) captured from the consult INVITE `channel.to`. */
12
+ C: string;
13
+ /** the consult-leg call id — delivers the BYE; NOT the command carrier. */
14
+ consultCallId: string;
15
+ /** the LIVE A-leg call id — the completion command carrier + result stream. */
16
+ carrierCallId: string;
17
+ /**
18
+ * Completion phase. `await-bye` -> (consult BYE) -> `completing`. The consult BYE triggers the ONE
19
+ * shared completion path (CC-5); there is no separate await-for-C-join phase (the shared helper
20
+ * joins C and lists members in sequence on the live A-leg).
21
+ */
22
+ phase: 'await-bye' | 'completing';
23
+ }
24
+ export default class WaitForDeskPhoneCall extends VoiceStep<TODO, TODO, TODO> {
25
+ get conversation(): string | import("@onereach/flow-sdk/types").IMergeField;
26
+ runStep(): Promise<any>;
27
+ onCall(event: IEvent<CallStartEvent>): Promise<any>;
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).
33
+ */
34
+ awaitConsultComplete(): Promise<void>;
35
+ /** Minimal routable envelope that carries completion commands on the LIVE A-leg. */
36
+ carrierEnvelope(x: DeskphoneXferState): CarrierEnvelope;
37
+ onConsultEvent(event: IEvent<VoiceEvent>): Promise<any>;
38
+ /**
39
+ * Job-2 completion wrapper around the SHARED `completeTransfer` helper (CC-5, DESIGN §4.3). The
40
+ * leg-choreography (joinBot C -> listMembers -> relate clear -> unvmute -> kick B -> clear) lives in
41
+ * 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.
45
+ */
46
+ completeDeskphoneTransfer(x: DeskphoneXferState): Promise<void>;
47
+ }
48
+ export {};
@@ -0,0 +1,172 @@
1
+ "use strict";
2
+ /* eslint-disable
3
+ @typescript-eslint/strict-boolean-expressions,
4
+ @typescript-eslint/explicit-function-return-type,
5
+ @typescript-eslint/no-misused-promises
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ const tslib_1 = require("tslib");
9
+ const voice_1 = tslib_1.__importDefault(require("./voice"));
10
+ const deskphoneCorrelation_1 = require("./deskphoneCorrelation");
11
+ const completeTransfer_1 = require("./completeTransfer");
12
+ const defaultSessionTimeout = 5 * 60 * 1000;
13
+ class WaitForDeskPhoneCall extends voice_1.default {
14
+ get conversation() {
15
+ if (this.step.dataOut == null)
16
+ throw new Error('missing step.dataOut');
17
+ return this.step.dataOut;
18
+ }
19
+ async runStep() {
20
+ const sipUsername = String(this.data.sipUsername ?? '').trim();
21
+ this.log.warn(sipUsername, "sipUsername - Wait for desk phone");
22
+ if (sipUsername) {
23
+ this.triggers.on(`in/voice/deskphone/${sipUsername}/call`, this.onCall);
24
+ }
25
+ // Resume guard: a consult is already in flight (persisted across a thread resume) -> go straight
26
+ // back to the waiting state and re-arm the completion listeners (named-state re-arm pattern).
27
+ if (this.state.deskphoneXfer?.carrierCallId) {
28
+ return this.gotoState('awaitConsultComplete');
29
+ }
30
+ }
31
+ async onCall(event) {
32
+ this.log.warn("onCall event triggered Wait for desk phone", event);
33
+ const { asr, tts, endOfInputTimeout } = this.data;
34
+ const accountId = this.helpers.providersAccountId;
35
+ // Trimming fromUser here is DELIBERATE and REQUIRED for the key match — the breakout emits the
36
+ // key trimmed but surfaces fromUser untrimmed. Do NOT simplify back to the untrimmed form.
37
+ const fromUser = String(event.params.fromUser ?? '').trim();
38
+ // On the inbound breakout leg the dialed PSTN number is the SIP To/req user, surfaced as
39
+ // `channel.to` (e.g. `+17202392838`). `fromUser` carries the desk-phone SIP username
40
+ // (e.g. `desk-2001`) — the caller, NEVER the dialed number. Confirmed against live FreeSWITCH
41
+ // CHANNEL_DATA (desk-2001 -> +17202392838): variable_sip_from_user = desk-2001,
42
+ // variable_sip_req_user / variable_sip_to_user = +17202392838. The dialed number MUST come from
43
+ // `channel.to`; using `fromUser` dials the literal desk username and yields UNALLOCATED_NUMBER.
44
+ const dialedNumber = event.params.channel.to ?? 'unknown';
45
+ const entry = await (0, deskphoneCorrelation_1.readDeskphoneConference)(this, accountId, fromUser);
46
+ const call = {
47
+ headers: event.params.headers,
48
+ // The dialed PSTN number is the owned/bot-facing side of the breakout, surfaced in `channel.to`
49
+ // (e.g. `+17202392838`), so it plays the "bot number" role.
50
+ // @ts-expect-error
51
+ botNumber: event.params.channel.to ?? 'unknown',
52
+ // The end user / caller is the desk phone, surfaced as `fromUser` (e.g. `desk-2001`).
53
+ // @ts-expect-error
54
+ endUserNumber: fromUser ?? event.params.channel?.from ?? 'unknown',
55
+ ...event.params.channel,
56
+ asr: asr.getSettings(),
57
+ tts: tts.getVoice()
58
+ };
59
+ delete call.from;
60
+ delete call.to;
61
+ call.dialedNumber = dialedNumber;
62
+ call.fromUser = fromUser;
63
+ this.log.warn(call, "call triggered Wait for desk phone");
64
+ // Ordinary breakout (no correlation entry) OR cross-account mismatch -> UNCHANGED existing path.
65
+ // A mismatch degrades safely to the ordinary breakout (A+B left intact); it is logged, not thrown.
66
+ if (!entry || entry.accountId !== accountId) {
67
+ if (entry && entry.accountId !== accountId) {
68
+ this.log.warn('deskphone transfer: account mismatch, ordinary breakout Wait for desk phone', { entryAccountId: entry.accountId, accountId });
69
+ }
70
+ const presetTime = (Number(endOfInputTimeout) || 0) * 60 * 1000;
71
+ const { sessionId: previousSessionId = '', beginningSessionId = '', } = event?.reporting ?? {};
72
+ await this.session.start({
73
+ timeout: presetTime || defaultSessionTimeout,
74
+ reporting: {
75
+ settingsKey: 'session',
76
+ startedBy: 'Visitor',
77
+ sessionType: 'Phone',
78
+ previousSessionId,
79
+ beginningSessionId
80
+ },
81
+ reportingSessions: [{
82
+ previousSessionId,
83
+ beginningSessionId
84
+ }]
85
+ });
86
+ await this.startConversation(call);
87
+ await this.transcript(call, {
88
+ action: 'Call Start',
89
+ reportingSettingsKey: 'transcript',
90
+ actionFromBot: false
91
+ });
92
+ this.log.warn('run exit Wait for desk phone');
93
+ return this.exitStep('trigger');
94
+ }
95
+ // TRANSFER. C = the dialed PSTN target (never the desk phone, never oct25sip).
96
+ // Stash the state machine and transition to the named waiting state (re-arm pattern).
97
+ // Do NOT splice, do NOT startConversation, do NOT arm a mid-handler local + bare return.
98
+ this.state.deskphoneXfer = {
99
+ fromUser,
100
+ entry,
101
+ C: event.params.channel.to,
102
+ consultCallId: call.id,
103
+ carrierCallId: entry.callId,
104
+ phase: 'await-bye'
105
+ };
106
+ return this.gotoState('awaitConsultComplete');
107
+ }
108
+ /**
109
+ * Named waiting state (resolves MEDIUM-1). Re-armed on every entry so the thread parks here across
110
+ * events: the consult-leg BYE surfaces on `in/voice/<consultCallId>`; C's join/list results surface
111
+ * on the A-leg stream `in/voice/<carrierCallId>`. Returns without exitStep/exitFlow so the step
112
+ * stays alive (mirrors Initiate Call.waitForCall).
113
+ */
114
+ async awaitConsultComplete() {
115
+ this.log.warn("awaitConsultComplete Wait for desk phone");
116
+ const { carrierCallId, consultCallId } = this.state.deskphoneXfer;
117
+ this.triggers.local(`in/voice/${carrierCallId}`, this.onConsultEvent);
118
+ this.triggers.local(`in/voice/${consultCallId}`, this.onConsultEvent);
119
+ }
120
+ /** Minimal routable envelope that carries completion commands on the LIVE A-leg. */
121
+ carrierEnvelope(x) {
122
+ return { id: x.carrierCallId, type: x.entry.callType, callback: x.entry.callback };
123
+ }
124
+ async onConsultEvent(event) {
125
+ this.log.warn(event, "onConsultEvent Wait for desk phone");
126
+ const x = this.state.deskphoneXfer;
127
+ if (!x)
128
+ return;
129
+ switch (event.params.type) {
130
+ case 'hangup': {
131
+ this.log.warn(event, "onConsultEvent hangup Wait for desk phone");
132
+ // Consult-leg BYE = COMPLETION START. Only act once, while awaiting the BYE.
133
+ if (x.phase !== 'await-bye')
134
+ return;
135
+ x.phase = 'completing';
136
+ // C is the dialed PSTN target; run the ONE shared completion path (CC-5, DESIGN §4.3) on the
137
+ // LIVE A-leg carrier: joinBot C -> listMembers -> relate clear -> unvmute -> kick B -> clear.
138
+ // No new INVITE toward the phone. Job 2 keeps its `exitStep('trigger')` terminal.
139
+ await this.completeDeskphoneTransfer(x);
140
+ return this.exitStep('trigger');
141
+ }
142
+ case 'error': {
143
+ this.log.warn(event, "onConsultEvent hangup Wait for desk phone");
144
+ this.log.error('deskphone transfer consult/join error; leaving A+B intact', { error: event.params.error });
145
+ return this.exitStep('trigger');
146
+ }
147
+ default:
148
+ return;
149
+ }
150
+ }
151
+ /**
152
+ * Job-2 completion wrapper around the SHARED `completeTransfer` helper (CC-5, DESIGN §4.3). The
153
+ * leg-choreography (joinBot C -> listMembers -> relate clear -> unvmute -> kick B -> clear) lives in
154
+ * the shared helper so Job 1 (`Conference Dial.ts`) and Job 2 use ONE code path. This wrapper only
155
+ * builds the helper args from the step's `DeskphoneXferState` and owns the terminal action; the
156
+ * caller (`onConsultEvent`) issues `exitStep('trigger')`. On a C-not-found abort the helper leaves
157
+ * A+B intact and this returns without any further action.
158
+ */
159
+ async completeDeskphoneTransfer(x) {
160
+ await (0, completeTransfer_1.completeTransfer)(this, {
161
+ carrier: this.carrierEnvelope(x),
162
+ room: x.entry.room,
163
+ accountId: x.entry.accountId,
164
+ targetC: x.C,
165
+ fromNumber: x.entry.callerId,
166
+ bMemberId: x.entry.memberId,
167
+ sipUser: x.fromUser
168
+ });
169
+ this.log.warn("completeDeskphoneTransfer Wait for desk phone");
170
+ }
171
+ }
172
+ exports.default = WaitForDeskPhoneCall;
@@ -0,0 +1,76 @@
1
+ import { TODO } from './voice';
2
+ /** A parsed conference member row as returned by the voicer `conference.listMembers` command. */
3
+ export interface MemberRow {
4
+ id: string;
5
+ who?: string;
6
+ callId?: string;
7
+ from?: string;
8
+ to?: string;
9
+ options?: string[];
10
+ }
11
+ /** Minimal routable envelope for carrying a command on the LIVE A-leg. */
12
+ export interface CarrierEnvelope {
13
+ id: string;
14
+ type: string;
15
+ callback: unknown;
16
+ }
17
+ /** Per-target-class gateway selector passed straight through to `conference.joinBot`. */
18
+ export interface CompleteTransferGateway {
19
+ host?: string;
20
+ user?: string;
21
+ username?: string;
22
+ password?: string;
23
+ profile?: 'internal' | 'external';
24
+ }
25
+ export interface CompleteTransferArgs {
26
+ /** The LIVE A-leg carrier (conference-owning channel) — every command runs on it. */
27
+ carrier: CarrierEnvelope;
28
+ /** The un-prefixed conference room (e.g. `conference_deskphone`). */
29
+ room: string;
30
+ /** The conference-owning account id. */
31
+ accountId: string;
32
+ /**
33
+ * The transfer target C per class. INTERNAL (e.g. 2222) MUST be a `sip:<user>@<host>` URI so
34
+ * `buildJoinBotDial` honors the embedded host over the internal profile (DESIGN §4.1); PSTN is the
35
+ * bare `+E164` number dialed over the external gateway (DESIGN §4.2).
36
+ */
37
+ targetC: string;
38
+ /**
39
+ * The member-list MATCH value for C. For an internal `sip:<user>@<host>` targetC this is the bare
40
+ * user (`2222`); for PSTN it equals `targetC`. Defaults to `targetC` when omitted.
41
+ */
42
+ targetMatch?: string;
43
+ /** Per-class joinBot gateway (internal profile | external gateway). */
44
+ gateway?: CompleteTransferGateway;
45
+ /** OWNED DID caller-ID for C — the conference-owning botNumber. NEVER the SIP user, NEVER oct25sip. */
46
+ fromNumber: string;
47
+ /** Desk-2001's (B's) stored conference member id — kicked after C is un-isolated. */
48
+ bMemberId: string;
49
+ /** The trimmed desk-phone SIP username (correlation key) to clear on success. */
50
+ sipUser: string;
51
+ }
52
+ /** The minimal step surface the helper drives (satisfied by any `VoiceStep`). */
53
+ export interface CompleteTransferStep {
54
+ sendCommands(envelope: TODO, commands: TODO[]): Promise<TODO>;
55
+ log: {
56
+ error: (...args: any[]) => void;
57
+ };
58
+ }
59
+ /**
60
+ * The ONE desk-phone attended-transfer COMPLETION code path (DESIGN §4.3 / CC-5), shared by both
61
+ * `Conference Dial.ts` (Job 1, driven off `conference-end`) and `Wait For Desk-Phone Call.ts`
62
+ * (Job 2 / legacy consult path). Every command is carried on the LIVE A-leg `carrier`:
63
+ *
64
+ * (1) joinBot C into `room` (per-class gateway) — NO fresh INVITE toward the desk phone
65
+ * (2) listMembers -> find C's member id (abort leaving A+B intact if not found)
66
+ * (3) relate C <-> all `clear` — un-isolate A<->C
67
+ * (4) unvmute all — inverse of the join's vmute
68
+ * (5) kick B (desk-2001) by its stored member id
69
+ * (6) clear the correlation entry
70
+ *
71
+ * The helper returns `void`; each CALLER owns its terminal action (DESIGN §4.3). On a C-not-found
72
+ * abort the helper logs and returns WITHOUT kicking B or clearing the correlation (A+B intact).
73
+ *
74
+ * @returns `true` when C was completed (kick + clear ran), `false` on the C-not-found abort.
75
+ */
76
+ export declare function completeTransfer(step: CompleteTransferStep, args: CompleteTransferArgs): Promise<boolean>;
@@ -0,0 +1,77 @@
1
+ "use strict";
2
+ /* eslint-disable
3
+ @typescript-eslint/strict-boolean-expressions,
4
+ @typescript-eslint/explicit-function-return-type,
5
+ @typescript-eslint/no-explicit-any
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.completeTransfer = void 0;
9
+ const tslib_1 = require("tslib");
10
+ const lodash_1 = tslib_1.__importDefault(require("lodash"));
11
+ const deskphoneCorrelation_1 = require("./deskphoneCorrelation");
12
+ /**
13
+ * The ONE desk-phone attended-transfer COMPLETION code path (DESIGN §4.3 / CC-5), shared by both
14
+ * `Conference Dial.ts` (Job 1, driven off `conference-end`) and `Wait For Desk-Phone Call.ts`
15
+ * (Job 2 / legacy consult path). Every command is carried on the LIVE A-leg `carrier`:
16
+ *
17
+ * (1) joinBot C into `room` (per-class gateway) — NO fresh INVITE toward the desk phone
18
+ * (2) listMembers -> find C's member id (abort leaving A+B intact if not found)
19
+ * (3) relate C <-> all `clear` — un-isolate A<->C
20
+ * (4) unvmute all — inverse of the join's vmute
21
+ * (5) kick B (desk-2001) by its stored member id
22
+ * (6) clear the correlation entry
23
+ *
24
+ * The helper returns `void`; each CALLER owns its terminal action (DESIGN §4.3). On a C-not-found
25
+ * abort the helper logs and returns WITHOUT kicking B or clearing the correlation (A+B intact).
26
+ *
27
+ * @returns `true` when C was completed (kick + clear ran), `false` on the C-not-found abort.
28
+ */
29
+ async function completeTransfer(step, args) {
30
+ const { carrier, room, accountId, targetC, gateway, fromNumber, bMemberId, sipUser } = args;
31
+ const targetMatch = args.targetMatch ?? targetC;
32
+ // (1) Dial C into room R on the LIVE A-leg carrier with the OWNED DID (never oct25sip / SIP user).
33
+ // No new INVITE toward the phone — this adds C as a conference member.
34
+ await step.sendCommands(carrier, [{
35
+ name: 'conference.joinBot',
36
+ params: {
37
+ accountId,
38
+ room,
39
+ botNumber: targetC,
40
+ fromNumber,
41
+ headers: {},
42
+ hearOnly: undefined,
43
+ ...(gateway != null ? { gateway } : {})
44
+ }
45
+ }]);
46
+ // (2) Resolve C's member id deterministically from the live member list.
47
+ const membersResult = await step.sendCommands(carrier, [{
48
+ name: 'conference.listMembers',
49
+ params: { accountId, room }
50
+ }]);
51
+ const members = (membersResult?.members ?? membersResult ?? []);
52
+ const cRow = lodash_1.default.find(members, m => m.to === targetMatch || m.from === targetMatch);
53
+ if (!cRow) {
54
+ step.log.error('deskphone transfer: C not found in member list; aborting, A+B intact', { targetMatch, members });
55
+ return false;
56
+ }
57
+ const cMemberId = cRow.id;
58
+ // (3) Clear the consult nohear relation whose SUBJECT is C's member id (un-isolate A<->C).
59
+ await step.sendCommands(carrier, [{
60
+ name: 'conference.relate',
61
+ params: { accountId, room, member: cMemberId, others: 'all', mode: 'clear' }
62
+ }]);
63
+ // (4) Deterministic video-unmute (vmute all off) — the inverse of the join's `vmute all`.
64
+ await step.sendCommands(carrier, [{
65
+ name: 'conference.unvmute',
66
+ params: { accountId, room, user: 'all' }
67
+ }]);
68
+ // (5) Kick B (desk-2001) by its stored member id.
69
+ await step.sendCommands(carrier, [{
70
+ name: 'conference.kick',
71
+ params: { accountId, room, user: bMemberId }
72
+ }]);
73
+ // (6) Clear the correlation entry.
74
+ await (0, deskphoneCorrelation_1.clearDeskphoneConference)(step, accountId, sipUser);
75
+ return true;
76
+ }
77
+ exports.completeTransfer = completeTransfer;
@@ -0,0 +1,46 @@
1
+ import { TODO } from './voice';
2
+ /**
3
+ * Correlation entry recorded when the platform dials the desk phone into a conference.
4
+ *
5
+ * Keyed, in the store, by the TRIMMED desk-phone SIP username (e.g. `desk-2001`) so it matches the
6
+ * breakout emit `in/voice/deskphone/${_.trim(variable_sip_from_user)}/call`. The `callId`/`callType`/
7
+ * `callback` fields identify the LIVE A-leg (the conference-owning channel) that carries the
8
+ * completion commands — a hung-up consult leg cannot execute `out/voice` commands — so they are
9
+ * load-bearing, not debug-only.
10
+ */
11
+ export interface DeskphoneConferenceEntry {
12
+ /** `this.helpers.providersAccountId` at write time (the conference-owning flow). */
13
+ accountId: string;
14
+ /** The un-prefixed conference room (Conference Dial's `this.data.sourceConf`). */
15
+ room: string;
16
+ /** desk-2001's (B's) conference member id (`conference-start` `event.params.user`). */
17
+ memberId: string;
18
+ /**
19
+ * OWNED outbound DID to dial C with — the conference-owning `call.botNumber`.
20
+ * NEVER the desk-phone SIP user, NEVER `oct25sip`.
21
+ */
22
+ callerId: string;
23
+ /** conference-owning (A-leg) `call.id` — the completion command CARRIER channel id. */
24
+ callId: string;
25
+ /** conference-owning `call.type` — carrier envelope `type` for `sendCommands`. */
26
+ callType: string;
27
+ /** conference-owning `call.callback` — carrier envelope `callback` for `sendCommands`. */
28
+ callback: unknown;
29
+ /** the conversation id that owns desk-2001's membership (debug/lifecycle). */
30
+ bConvId: string;
31
+ }
32
+ /**
33
+ * Record (or overwrite) the correlation entry for a desk-phone SIP username.
34
+ *
35
+ * Last-write-wins. The get->mutate->set runs within a single awaited critical section; the map is
36
+ * never held across an await to a FreeSWITCH command.
37
+ */
38
+ export declare function writeDeskphoneConference(self: TODO, accountId: string, sipUser: string, entry: DeskphoneConferenceEntry): Promise<void>;
39
+ /** Read the correlation entry for a desk-phone SIP username, or `undefined` if none exists. */
40
+ export declare function readDeskphoneConference(self: TODO, accountId: string, sipUser: string): Promise<DeskphoneConferenceEntry | undefined>;
41
+ /**
42
+ * Delete the correlation entry for a desk-phone SIP username.
43
+ *
44
+ * Idempotent: two concurrent clears converge on absent (the safe terminal state).
45
+ */
46
+ export declare function clearDeskphoneConference(self: TODO, accountId: string, sipUser: string): Promise<void>;
@@ -0,0 +1,62 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.clearDeskphoneConference = exports.readDeskphoneConference = exports.writeDeskphoneConference = void 0;
4
+ /**
5
+ * Dedicated key/value table for desk-phone transfer correlation, isolated from the default `.ssns`
6
+ * session table so these entries never collide with ordinary session storage.
7
+ */
8
+ const TABLE = '.deskphone-xfer';
9
+ /**
10
+ * Fixed, account-scoped storage key both flows compute identically. The account is folded into the
11
+ * KEY (exactly as it was folded into the thread name before) so the lookup is account-deterministic
12
+ * regardless of which flow/bot performs it.
13
+ */
14
+ const KEY = (accountId) => `deskphone-xfer:${accountId}`;
15
+ /**
16
+ * Bound the entry to the transfer window. The write happens when the desk phone joins the
17
+ * conference; the read happens seconds-to-minutes later on the independent inbound breakout.
18
+ */
19
+ const TTL_MS = 10 * 60 * 1000;
20
+ /**
21
+ * Account-scoped, cross-flow persistent key/value store (flow-sdk Session Storage over
22
+ * `@onereach/orb-storage` KeyValueStorage). Unlike `process.getSafeThread`, this is NOT per-process:
23
+ * a value written by the conference-owning flow is readable by the breakout flow in the same
24
+ * account/deployment. `process.sessionStorage` is scoped by `config.accountId`; the explicit
25
+ * account-folded KEY makes the record bot-independent, which is required because the conference and
26
+ * breakout flows are not guaranteed to share a botId.
27
+ */
28
+ function store(self) {
29
+ return self.process.sessionStorage;
30
+ }
31
+ /**
32
+ * Record (or overwrite) the correlation entry for a desk-phone SIP username.
33
+ *
34
+ * Last-write-wins. The get->mutate->set runs within a single awaited critical section; the map is
35
+ * never held across an await to a FreeSWITCH command.
36
+ */
37
+ async function writeDeskphoneConference(self, accountId, sipUser, entry) {
38
+ const kv = store(self);
39
+ const map = (await kv.get(KEY(accountId), undefined, { table: TABLE })) ?? {};
40
+ map[sipUser] = entry;
41
+ await kv.set(KEY(accountId), map, { expire: TTL_MS, table: TABLE });
42
+ }
43
+ exports.writeDeskphoneConference = writeDeskphoneConference;
44
+ /** Read the correlation entry for a desk-phone SIP username, or `undefined` if none exists. */
45
+ async function readDeskphoneConference(self, accountId, sipUser) {
46
+ const kv = store(self);
47
+ const map = (await kv.get(KEY(accountId), undefined, { table: TABLE })) ?? {};
48
+ return map[sipUser];
49
+ }
50
+ exports.readDeskphoneConference = readDeskphoneConference;
51
+ /**
52
+ * Delete the correlation entry for a desk-phone SIP username.
53
+ *
54
+ * Idempotent: two concurrent clears converge on absent (the safe terminal state).
55
+ */
56
+ async function clearDeskphoneConference(self, accountId, sipUser) {
57
+ const kv = store(self);
58
+ const map = (await kv.get(KEY(accountId), undefined, { table: TABLE })) ?? {};
59
+ delete map[sipUser];
60
+ await kv.set(KEY(accountId), map, { expire: TTL_MS, table: TABLE });
61
+ }
62
+ exports.clearDeskphoneConference = clearDeskphoneConference;
package/dst/voice.d.ts CHANGED
@@ -33,7 +33,7 @@ export interface IVoiceCall extends IConversationData {
33
33
  user: string;
34
34
  };
35
35
  }
36
- export type EventType = 'hangup' | 'ack' | 'error' | 'cancel' | 'background' | 'avm-detected' | 'recognition' | 'digit' | 'digits' | 'conference-start' | 'conference-end' | 'playback' | 'timeout' | 'record' | 'bridge' | 'bridge/ended' | 'is_flow_ready' | 'call' | 'dtmf-sent';
36
+ export type EventType = 'hangup' | 'ack' | 'error' | 'cancel' | 'background' | 'avm-detected' | 'recognition' | 'digit' | 'digits' | 'conference-start' | 'conference-end' | 'members' | 'playback' | 'timeout' | 'record' | 'bridge' | 'bridge/ended' | 'is_flow_ready' | 'call' | 'transfer' | 'dtmf-sent';
37
37
  export declare class VoiceStepError extends BasicError {
38
38
  }
39
39
  export type VoicerError = Error & {
@@ -61,6 +61,14 @@ export interface VoiceEvent {
61
61
  result?: {
62
62
  interruptionMetadata?: VoiceInterruptionMetadata;
63
63
  };
64
+ /**
65
+ * Desk-phone attended-transfer COMPLETION (Job 1): carried on a `transfer` event emitted by
66
+ * voicer (`in/voice/deskphone/<sipUser>/transfer`). `target` is the transfer target C parsed from
67
+ * the REFER `Refer-To`; `replaces` is the consult dialog identifier. Additive — present only on
68
+ * `transfer` events.
69
+ */
70
+ target?: string;
71
+ replaces?: string;
64
72
  }
65
73
  export interface CallStartEvent extends VoiceEvent {
66
74
  channel: IVoiceCall;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onereach/step-voice",
3
- "version": "7.0.45",
3
+ "version": "7.0.46-deskphoneintegration.10",
4
4
  "author": "Roman Zolotarov <roman.zolotarov@onereach.com>",
5
5
  "contributors": [
6
6
  "Roman Zolotarov",