@signalwire/sdk 2.0.4 → 3.5.0

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.
Files changed (656) hide show
  1. package/CHANGELOG.md +785 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +550 -163
  6. package/dist/AgentBase.js +1640 -514
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +158 -45
  21. package/dist/DataMap.js +167 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +277 -83
  24. package/dist/FunctionResult.js +444 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +163 -0
  30. package/dist/POM/PromptObjectModel.js +481 -0
  31. package/dist/POM/PromptObjectModel.js.map +1 -0
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +28 -0
  42. package/dist/PomBuilder.js +81 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +29 -1
  48. package/dist/PromptManager.js +37 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +265 -66
  58. package/dist/SWMLService.js +652 -112
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +55 -8
  64. package/dist/SecurityUtils.js +162 -49
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/ServerlessAdapter.d.ts +156 -7
  67. package/dist/ServerlessAdapter.js +399 -42
  68. package/dist/ServerlessAdapter.js.map +1 -1
  69. package/dist/SessionManager.d.ts +11 -2
  70. package/dist/SessionManager.js +50 -18
  71. package/dist/SessionManager.js.map +1 -1
  72. package/dist/SslConfig.d.ts +2 -1
  73. package/dist/SslConfig.js +4 -1
  74. package/dist/SslConfig.js.map +1 -1
  75. package/dist/SwaigActions.generated.d.ts +23 -0
  76. package/dist/SwaigActions.generated.js +8 -0
  77. package/dist/SwaigActions.generated.js.map +1 -0
  78. package/dist/SwaigContracts.d.ts +15 -0
  79. package/dist/SwaigContracts.generated.d.ts +264 -0
  80. package/dist/SwaigContracts.generated.js +12 -0
  81. package/dist/SwaigContracts.generated.js.map +1 -0
  82. package/dist/SwaigContracts.js +2 -0
  83. package/dist/SwaigContracts.js.map +1 -0
  84. package/dist/SwaigFunction.d.ts +110 -4
  85. package/dist/SwaigFunction.js +151 -19
  86. package/dist/SwaigFunction.js.map +1 -1
  87. package/dist/SwmlBuilder.d.ts +68 -19
  88. package/dist/SwmlBuilder.js +74 -38
  89. package/dist/SwmlBuilder.js.map +1 -1
  90. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  91. package/dist/SwmlVerbMethods.generated.js +1 -1
  92. package/dist/TypeInference.d.ts +39 -3
  93. package/dist/TypeInference.js +256 -16
  94. package/dist/TypeInference.js.map +1 -1
  95. package/dist/WebService.d.ts +79 -11
  96. package/dist/WebService.js +320 -109
  97. package/dist/WebService.js.map +1 -1
  98. package/dist/WebhookMiddleware.d.ts +119 -0
  99. package/dist/WebhookMiddleware.js +271 -0
  100. package/dist/WebhookMiddleware.js.map +1 -0
  101. package/dist/WebhookValidator.d.ts +92 -0
  102. package/dist/WebhookValidator.js +409 -0
  103. package/dist/WebhookValidator.js.map +1 -0
  104. package/dist/agents/BedrockAgent.d.ts +162 -0
  105. package/dist/agents/BedrockAgent.js +323 -0
  106. package/dist/agents/BedrockAgent.js.map +1 -0
  107. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  108. package/dist/ai-chat/AIChatClient.js +535 -0
  109. package/dist/ai-chat/AIChatClient.js.map +1 -0
  110. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  111. package/dist/ai-chat/ChatGateway.js +747 -0
  112. package/dist/ai-chat/ChatGateway.js.map +1 -0
  113. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  114. package/dist/ai-chat/HandoffRouter.js +518 -0
  115. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  116. package/dist/ai-chat/index.d.ts +12 -0
  117. package/dist/ai-chat/index.js +10 -0
  118. package/dist/ai-chat/index.js.map +1 -0
  119. package/dist/capabilities.d.ts +64 -0
  120. package/dist/capabilities.js +95 -0
  121. package/dist/capabilities.js.map +1 -0
  122. package/dist/cli/agent-loader.d.ts +32 -6
  123. package/dist/cli/agent-loader.js +95 -34
  124. package/dist/cli/agent-loader.js.map +1 -1
  125. package/dist/cli/datamap-exec.d.ts +175 -0
  126. package/dist/cli/datamap-exec.js +1284 -0
  127. package/dist/cli/datamap-exec.js.map +1 -0
  128. package/dist/cli/function-args.d.ts +40 -0
  129. package/dist/cli/function-args.js +146 -0
  130. package/dist/cli/function-args.js.map +1 -0
  131. package/dist/cli/simulation.d.ts +99 -0
  132. package/dist/cli/simulation.js +490 -0
  133. package/dist/cli/simulation.js.map +1 -0
  134. package/dist/cli/swaig-test.d.ts +12 -25
  135. package/dist/cli/swaig-test.js +935 -367
  136. package/dist/cli/swaig-test.js.map +1 -1
  137. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  138. package/dist/cli/tsdocs/agentsNote.js +92 -0
  139. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  140. package/dist/cli/tsdocs/api-index.json +1 -0
  141. package/dist/cli/tsdocs/api.d.ts +91 -0
  142. package/dist/cli/tsdocs/api.js +372 -0
  143. package/dist/cli/tsdocs/api.js.map +1 -0
  144. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  145. package/dist/cli/tsdocs/apiTypes.js +7 -0
  146. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  147. package/dist/cli/tsdocs/bin.d.ts +6 -0
  148. package/dist/cli/tsdocs/bin.js +23 -0
  149. package/dist/cli/tsdocs/bin.js.map +1 -0
  150. package/dist/cli/tsdocs/files.d.ts +108 -0
  151. package/dist/cli/tsdocs/files.js +287 -0
  152. package/dist/cli/tsdocs/files.js.map +1 -0
  153. package/dist/cli/tsdocs/index.d.ts +28 -0
  154. package/dist/cli/tsdocs/index.js +307 -0
  155. package/dist/cli/tsdocs/index.js.map +1 -0
  156. package/dist/cli/tsdocs/live.d.ts +41 -0
  157. package/dist/cli/tsdocs/live.js +202 -0
  158. package/dist/cli/tsdocs/live.js.map +1 -0
  159. package/dist/cli/tsdocs/locate.d.ts +51 -0
  160. package/dist/cli/tsdocs/locate.js +75 -0
  161. package/dist/cli/tsdocs/locate.js.map +1 -0
  162. package/dist/cli/tsdocs/render.d.ts +75 -0
  163. package/dist/cli/tsdocs/render.js +323 -0
  164. package/dist/cli/tsdocs/render.js.map +1 -0
  165. package/dist/cli/tsdocs/topics.d.ts +43 -0
  166. package/dist/cli/tsdocs/topics.js +916 -0
  167. package/dist/cli/tsdocs/topics.js.map +1 -0
  168. package/dist/index.d.ts +102 -39
  169. package/dist/index.js +107 -30
  170. package/dist/index.js.map +1 -1
  171. package/dist/livewire/index.d.ts +229 -155
  172. package/dist/livewire/index.js +298 -195
  173. package/dist/livewire/index.js.map +1 -1
  174. package/dist/llms.txt +65 -0
  175. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  176. package/dist/prefabs/CallSessionStore.js +72 -0
  177. package/dist/prefabs/CallSessionStore.js.map +1 -0
  178. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  179. package/dist/prefabs/ConciergeAgent.js +36 -31
  180. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  181. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  182. package/dist/prefabs/FAQBotAgent.js +113 -47
  183. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  184. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  185. package/dist/prefabs/InfoGathererAgent.js +67 -58
  186. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  187. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  188. package/dist/prefabs/ReceptionistAgent.js +39 -31
  189. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  190. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  191. package/dist/prefabs/SurveyAgent.js +84 -68
  192. package/dist/prefabs/SurveyAgent.js.map +1 -1
  193. package/dist/relay/Action.d.ts +44 -21
  194. package/dist/relay/Action.js +75 -17
  195. package/dist/relay/Action.js.map +1 -1
  196. package/dist/relay/Call.d.ts +312 -47
  197. package/dist/relay/Call.js +369 -18
  198. package/dist/relay/Call.js.map +1 -1
  199. package/dist/relay/Deferred.js.map +1 -1
  200. package/dist/relay/Message.d.ts +26 -5
  201. package/dist/relay/Message.js +36 -6
  202. package/dist/relay/Message.js.map +1 -1
  203. package/dist/relay/RelayClient.d.ts +79 -14
  204. package/dist/relay/RelayClient.js +268 -61
  205. package/dist/relay/RelayClient.js.map +1 -1
  206. package/dist/relay/RelayError.d.ts +14 -0
  207. package/dist/relay/RelayError.js +15 -0
  208. package/dist/relay/RelayError.js.map +1 -1
  209. package/dist/relay/RelayEvent.d.ts +96 -65
  210. package/dist/relay/RelayEvent.js +85 -56
  211. package/dist/relay/RelayEvent.js.map +1 -1
  212. package/dist/relay/closedSets.d.ts +111 -0
  213. package/dist/relay/closedSets.js +83 -0
  214. package/dist/relay/closedSets.js.map +1 -0
  215. package/dist/relay/index.d.ts +3 -1
  216. package/dist/relay/index.js +1 -0
  217. package/dist/relay/index.js.map +1 -1
  218. package/dist/relay/normalize.js.map +1 -1
  219. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  220. package/dist/relay/protocol.types.generated.js +8 -0
  221. package/dist/relay/protocol.types.generated.js.map +1 -0
  222. package/dist/relay/types.d.ts +81 -39
  223. package/dist/rest/HttpClient.d.ts +36 -8
  224. package/dist/rest/HttpClient.js +233 -40
  225. package/dist/rest/HttpClient.js.map +1 -1
  226. package/dist/rest/RequestOptions.d.ts +110 -0
  227. package/dist/rest/RequestOptions.js +113 -0
  228. package/dist/rest/RequestOptions.js.map +1 -0
  229. package/dist/rest/RestError.d.ts +52 -6
  230. package/dist/rest/RestError.js +89 -5
  231. package/dist/rest/RestError.js.map +1 -1
  232. package/dist/rest/base/CrudResource.d.ts +16 -26
  233. package/dist/rest/base/CrudResource.js +19 -33
  234. package/dist/rest/base/CrudResource.js.map +1 -1
  235. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  236. package/dist/rest/base/CrudWithAddresses.js +2 -2
  237. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  238. package/dist/rest/base/FabricResource.d.ts +15 -0
  239. package/dist/rest/base/FabricResource.js +16 -0
  240. package/dist/rest/base/FabricResource.js.map +1 -0
  241. package/dist/rest/base/ReadResource.d.ts +62 -0
  242. package/dist/rest/base/ReadResource.js +69 -0
  243. package/dist/rest/base/ReadResource.js.map +1 -0
  244. package/dist/rest/callHandler.d.ts +63 -0
  245. package/dist/rest/callHandler.js +62 -0
  246. package/dist/rest/callHandler.js.map +1 -0
  247. package/dist/rest/index.d.ts +19 -76
  248. package/dist/rest/index.js +49 -120
  249. package/dist/rest/index.js.map +1 -1
  250. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  251. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  252. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  253. package/dist/rest/namespaces/addresses.d.ts +3 -42
  254. package/dist/rest/namespaces/addresses.js +3 -50
  255. package/dist/rest/namespaces/addresses.js.map +1 -1
  256. package/dist/rest/namespaces/calling.d.ts +6 -378
  257. package/dist/rest/namespaces/calling.js +6 -473
  258. package/dist/rest/namespaces/calling.js.map +1 -1
  259. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  260. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  261. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  262. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  263. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  264. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  265. package/dist/rest/namespaces/chat.d.ts +4 -18
  266. package/dist/rest/namespaces/chat.js +4 -21
  267. package/dist/rest/namespaces/chat.js.map +1 -1
  268. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  269. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  270. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  271. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  272. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  273. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  274. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  275. package/dist/rest/namespaces/datasphere.js +6 -72
  276. package/dist/rest/namespaces/datasphere.js.map +1 -1
  277. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  278. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  279. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  280. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  281. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  282. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  283. package/dist/rest/namespaces/fabric.d.ts +11 -273
  284. package/dist/rest/namespaces/fabric.js +14 -363
  285. package/dist/rest/namespaces/fabric.js.map +1 -1
  286. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  287. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  288. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  289. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  290. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  291. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  293. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  294. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  296. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  297. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  298. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  299. package/dist/rest/namespaces/imported-numbers.js +3 -21
  300. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  301. package/dist/rest/namespaces/logs.d.ts +10 -101
  302. package/dist/rest/namespaces/logs.js +10 -128
  303. package/dist/rest/namespaces/logs.js.map +1 -1
  304. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  305. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  306. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  307. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  308. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  309. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  310. package/dist/rest/namespaces/lookup.d.ts +3 -25
  311. package/dist/rest/namespaces/lookup.js +3 -27
  312. package/dist/rest/namespaces/lookup.js.map +1 -1
  313. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  314. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  315. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  316. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  317. package/dist/rest/namespaces/message.types.generated.js +8 -0
  318. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  319. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  320. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  321. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  323. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  324. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  325. package/dist/rest/namespaces/mfa.d.ts +3 -42
  326. package/dist/rest/namespaces/mfa.js +3 -49
  327. package/dist/rest/namespaces/mfa.js.map +1 -1
  328. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  329. package/dist/rest/namespaces/number-groups.js +3 -53
  330. package/dist/rest/namespaces/number-groups.js.map +1 -1
  331. package/dist/rest/namespaces/phone-numbers.d.ts +9 -57
  332. package/dist/rest/namespaces/phone-numbers.js +9 -63
  333. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  334. package/dist/rest/namespaces/project.d.ts +6 -42
  335. package/dist/rest/namespaces/project.js +6 -51
  336. package/dist/rest/namespaces/project.js.map +1 -1
  337. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  338. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  339. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  340. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  341. package/dist/rest/namespaces/project.types.generated.js +8 -0
  342. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  343. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  344. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  345. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  347. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  348. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  349. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  350. package/dist/rest/namespaces/pubsub.js +4 -21
  351. package/dist/rest/namespaces/pubsub.js.map +1 -1
  352. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  353. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  354. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  355. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  356. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  357. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  358. package/dist/rest/namespaces/queues.d.ts +3 -38
  359. package/dist/rest/namespaces/queues.js +3 -44
  360. package/dist/rest/namespaces/queues.js.map +1 -1
  361. package/dist/rest/namespaces/recordings.d.ts +3 -34
  362. package/dist/rest/namespaces/recordings.js +3 -40
  363. package/dist/rest/namespaces/recordings.js.map +1 -1
  364. package/dist/rest/namespaces/registry.d.ts +6 -137
  365. package/dist/rest/namespaces/registry.js +6 -173
  366. package/dist/rest/namespaces/registry.js.map +1 -1
  367. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  368. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  369. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  370. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  371. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  372. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  373. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  374. package/dist/rest/namespaces/short-codes.js +3 -41
  375. package/dist/rest/namespaces/short-codes.js.map +1 -1
  376. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  377. package/dist/rest/namespaces/sip-profile.js +3 -29
  378. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  379. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  380. package/dist/rest/namespaces/verified-callers.js +3 -34
  381. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  382. package/dist/rest/namespaces/video.d.ts +10 -227
  383. package/dist/rest/namespaces/video.js +10 -288
  384. package/dist/rest/namespaces/video.js.map +1 -1
  385. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  386. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  387. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  388. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  389. package/dist/rest/namespaces/video.types.generated.js +8 -0
  390. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  391. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  392. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  393. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  395. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  396. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  397. package/dist/rest/pagination.d.ts +5 -1
  398. package/dist/rest/pagination.js +40 -20
  399. package/dist/rest/pagination.js.map +1 -1
  400. package/dist/rest/types.d.ts +21 -3
  401. package/dist/schema.json +299 -98
  402. package/dist/skills/SkillBase.d.ts +97 -20
  403. package/dist/skills/SkillBase.js +100 -17
  404. package/dist/skills/SkillBase.js.map +1 -1
  405. package/dist/skills/SkillManager.d.ts +66 -13
  406. package/dist/skills/SkillManager.js +101 -20
  407. package/dist/skills/SkillManager.js.map +1 -1
  408. package/dist/skills/SkillName.d.ts +44 -0
  409. package/dist/skills/SkillName.js +2 -0
  410. package/dist/skills/SkillName.js.map +1 -0
  411. package/dist/skills/SkillRegistry.d.ts +47 -7
  412. package/dist/skills/SkillRegistry.js +85 -13
  413. package/dist/skills/SkillRegistry.js.map +1 -1
  414. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  415. package/dist/skills/builtin/api_ninjas_trivia.js +24 -8
  416. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  417. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  418. package/dist/skills/builtin/ask_claude.js +36 -14
  419. package/dist/skills/builtin/ask_claude.js.map +1 -1
  420. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  421. package/dist/skills/builtin/claude_skills.js +19 -15
  422. package/dist/skills/builtin/claude_skills.js.map +1 -1
  423. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  424. package/dist/skills/builtin/custom_skills.js +26 -9
  425. package/dist/skills/builtin/custom_skills.js.map +1 -1
  426. package/dist/skills/builtin/datasphere.d.ts +5 -3
  427. package/dist/skills/builtin/datasphere.js +34 -25
  428. package/dist/skills/builtin/datasphere.js.map +1 -1
  429. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  430. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  431. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  432. package/dist/skills/builtin/datetime.d.ts +3 -1
  433. package/dist/skills/builtin/datetime.js +11 -7
  434. package/dist/skills/builtin/datetime.js.map +1 -1
  435. package/dist/skills/builtin/google_maps.d.ts +29 -14
  436. package/dist/skills/builtin/google_maps.js +89 -269
  437. package/dist/skills/builtin/google_maps.js.map +1 -1
  438. package/dist/skills/builtin/index.d.ts +8 -6
  439. package/dist/skills/builtin/index.js +8 -6
  440. package/dist/skills/builtin/index.js.map +1 -1
  441. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  442. package/dist/skills/builtin/info_gatherer.js +20 -12
  443. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  444. package/dist/skills/builtin/joke.d.ts +16 -6
  445. package/dist/skills/builtin/joke.js +54 -37
  446. package/dist/skills/builtin/joke.js.map +1 -1
  447. package/dist/skills/builtin/math.d.ts +3 -1
  448. package/dist/skills/builtin/math.js +14 -9
  449. package/dist/skills/builtin/math.js.map +1 -1
  450. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  451. package/dist/skills/builtin/mcp_gateway.js +77 -46
  452. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  453. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  454. package/dist/skills/builtin/native_vector_search.js +179 -61
  455. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  456. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  457. package/dist/skills/builtin/play_background_file.js +43 -122
  458. package/dist/skills/builtin/play_background_file.js.map +1 -1
  459. package/dist/skills/builtin/spider.d.ts +46 -1
  460. package/dist/skills/builtin/spider.js +317 -101
  461. package/dist/skills/builtin/spider.js.map +1 -1
  462. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  463. package/dist/skills/builtin/swml_transfer.js +45 -24
  464. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  465. package/dist/skills/builtin/weather_api.d.ts +24 -13
  466. package/dist/skills/builtin/weather_api.js +57 -31
  467. package/dist/skills/builtin/weather_api.js.map +1 -1
  468. package/dist/skills/builtin/web_search.d.ts +48 -10
  469. package/dist/skills/builtin/web_search.js +301 -84
  470. package/dist/skills/builtin/web_search.js.map +1 -1
  471. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  472. package/dist/skills/builtin/wikipedia_search.js +32 -14
  473. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  474. package/dist/skills/index.d.ts +3 -2
  475. package/dist/skills/index.js +1 -1
  476. package/dist/skills/index.js.map +1 -1
  477. package/dist/swml_verbs_generated.d.ts +2824 -0
  478. package/dist/swml_verbs_generated.js +12 -0
  479. package/dist/swml_verbs_generated.js.map +1 -0
  480. package/dist/types.d.ts +65 -6
  481. package/dist/web.d.ts +27 -0
  482. package/dist/web.js +20 -0
  483. package/dist/web.js.map +1 -0
  484. package/docs/agent-guide.md +1034 -0
  485. package/docs/ai_chat.md +560 -0
  486. package/docs/api-reference.md +3534 -0
  487. package/docs/architecture.md +846 -0
  488. package/docs/bedrock_agent.md +411 -0
  489. package/docs/cli-guide.md +403 -0
  490. package/docs/cloud_functions_guide.md +399 -0
  491. package/docs/configuration.md +548 -0
  492. package/docs/contexts-guide.md +884 -0
  493. package/docs/datamap-guide.md +1160 -0
  494. package/docs/developer_pain_points.md +548 -0
  495. package/docs/llm_parameters.md +298 -0
  496. package/docs/mcp_gateway_reference.md +354 -0
  497. package/docs/mcp_integration.md +162 -0
  498. package/docs/pgi_agent_guide.md +1820 -0
  499. package/docs/prefabs-guide.md +815 -0
  500. package/docs/programmatically_governed_inference.md +301 -0
  501. package/docs/sdk_features.md +501 -0
  502. package/docs/security.md +559 -0
  503. package/docs/serverless-guide.md +520 -0
  504. package/docs/skills-guide.md +1223 -0
  505. package/docs/skills-system.md +405 -0
  506. package/docs/skills_parameter_schema.md +417 -0
  507. package/docs/swaig-reference.md +1938 -0
  508. package/docs/swml_service_guide.md +573 -0
  509. package/docs/third_party_skills.md +410 -0
  510. package/docs/web_service.md +666 -0
  511. package/examples/README.md +202 -0
  512. package/examples/advanced-datamap.ts +108 -0
  513. package/examples/advanced-dynamic-config.ts +70 -0
  514. package/examples/auto-vivified.ts +95 -0
  515. package/examples/call-flow.ts +65 -0
  516. package/examples/comprehensive-dynamic.ts +125 -0
  517. package/examples/contexts-steps.ts +65 -0
  518. package/examples/custom-path.ts +45 -0
  519. package/examples/datamap-tools.ts +51 -0
  520. package/examples/datasphere-multi-instance.ts +66 -0
  521. package/examples/datasphere-serverless-env.ts +87 -0
  522. package/examples/datasphere-webhook-env.ts +65 -0
  523. package/examples/datasphere.ts +56 -0
  524. package/examples/declarative.ts +100 -0
  525. package/examples/dynamic-config.ts +54 -0
  526. package/examples/dynamic-info-gatherer.ts +69 -0
  527. package/examples/dynamic-swml-service.ts +67 -0
  528. package/examples/gather-info.ts +95 -0
  529. package/examples/gather-per-question-functions-demo.ts +139 -0
  530. package/examples/joke-agent.ts +34 -0
  531. package/examples/kubernetes-agent.ts +45 -0
  532. package/examples/llm-params.ts +75 -0
  533. package/examples/mcp-agent.ts +89 -0
  534. package/examples/mcp-gateway.ts +81 -0
  535. package/examples/multi-agent.ts +80 -0
  536. package/examples/multi-endpoint.ts +79 -0
  537. package/examples/pgi/case-domain.ts +114 -0
  538. package/examples/pgi/serve.ts +16 -0
  539. package/examples/pgi/support-agent.ts +265 -0
  540. package/examples/pom-prompt.ts +70 -0
  541. package/examples/prefab-concierge.ts +42 -0
  542. package/examples/prefab-faq.ts +58 -0
  543. package/examples/prefab-info-gatherer.ts +33 -0
  544. package/examples/prefab-receptionist.ts +36 -0
  545. package/examples/prefab-survey.ts +69 -0
  546. package/examples/quickstart-agent.ts +29 -0
  547. package/examples/quickstart-relay.ts +25 -0
  548. package/examples/quickstart-rest.ts +25 -0
  549. package/examples/record-call.ts +65 -0
  550. package/examples/relay-demo.ts +33 -0
  551. package/examples/room-and-sip.ts +93 -0
  552. package/examples/serverless-lambda.ts +43 -0
  553. package/examples/session-state.ts +83 -0
  554. package/examples/simple-agent.ts +36 -0
  555. package/examples/simple-static.ts +29 -0
  556. package/examples/skills-demo.ts +41 -0
  557. package/examples/step-function-inheritance-demo.ts +124 -0
  558. package/examples/swaig-features.ts +193 -0
  559. package/examples/swml-service-routing.ts +66 -0
  560. package/examples/swml-service.ts +38 -0
  561. package/examples/swmlservice_ai_sidecar.ts +104 -0
  562. package/examples/swmlservice_swaig_standalone.ts +79 -0
  563. package/examples/tap.ts +67 -0
  564. package/examples/typed-tools.ts +68 -0
  565. package/examples/verb-methods.ts +45 -0
  566. package/examples/web-search-multi-instance.ts +75 -0
  567. package/examples/web-search.ts +38 -0
  568. package/examples/wikipedia.ts +36 -0
  569. package/livewire/README.md +164 -0
  570. package/livewire/docs/migration-guide.md +251 -0
  571. package/livewire/examples/livewire-basic-agent.ts +74 -0
  572. package/livewire/examples/livewire-handoff.ts +196 -0
  573. package/livewire/examples/livewire-multi-tool.ts +121 -0
  574. package/package.json +88 -13
  575. package/relay/README.md +101 -0
  576. package/relay/docs/call-methods.md +622 -0
  577. package/relay/docs/client-reference.md +281 -0
  578. package/relay/docs/events.md +193 -0
  579. package/relay/docs/getting-started.md +221 -0
  580. package/relay/docs/guide.md +386 -0
  581. package/relay/docs/messaging.md +246 -0
  582. package/relay/examples/relay-inbound.ts +66 -0
  583. package/relay/examples/relay-messaging.ts +74 -0
  584. package/relay/examples/relay-outbound.ts +76 -0
  585. package/rest/README.md +141 -0
  586. package/rest/docs/calling.md +313 -0
  587. package/rest/docs/client-reference.md +149 -0
  588. package/rest/docs/fabric.md +192 -0
  589. package/rest/docs/getting-started.md +138 -0
  590. package/rest/docs/guide.md +421 -0
  591. package/rest/docs/namespaces.md +367 -0
  592. package/rest/docs/phone-binding.md +116 -0
  593. package/rest/examples/rest-10dlc-registration.ts +177 -0
  594. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  595. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  596. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  597. package/rest/examples/rest-client.ts +59 -0
  598. package/rest/examples/rest-datasphere-search.ts +81 -0
  599. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  600. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  601. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  602. package/rest/examples/rest-manage-resources.ts +64 -0
  603. package/rest/examples/rest-phone-number-management.ts +200 -0
  604. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  605. package/rest/examples/rest-video-rooms.ts +186 -0
  606. package/tutorial/fred/fred.ts +218 -0
  607. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  608. package/tutorial/fred/tutorial/02-setup.md +304 -0
  609. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  610. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  611. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  612. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  613. package/tutorial/fred/tutorial/README.md +56 -0
  614. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  615. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  616. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  617. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  618. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  619. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  620. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  621. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  622. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  623. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  624. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  625. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  626. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  627. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  628. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  629. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  630. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  631. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  632. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  633. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  634. package/tutorial/multi_agents/README.md +175 -0
  635. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  636. package/tutorial/multi_agents/extending_agents.ts +641 -0
  637. package/tutorial/multi_agents/knowledge.ts +59 -0
  638. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  639. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  640. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  641. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  642. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  643. package/tutorial/multi_agents/pc_builder.ts +529 -0
  644. package/tutorial/multi_agents/sales_agent.ts +88 -0
  645. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  646. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  647. package/tutorial/multi_agents/support_knowledge.md +256 -0
  648. package/dist/cli/mock-data.d.ts +0 -37
  649. package/dist/cli/mock-data.js +0 -80
  650. package/dist/cli/mock-data.js.map +0 -1
  651. package/dist/generateVerbTypes.d.ts +0 -11
  652. package/dist/generateVerbTypes.js +0 -265
  653. package/dist/generateVerbTypes.js.map +0 -1
  654. package/dist/rest/namespaces/compat.d.ts +0 -585
  655. package/dist/rest/namespaces/compat.js +0 -735
  656. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,1109 @@
1
+ /**
2
+ * The Copper Pot reservation book: every business rule, and no SignalWire import.
3
+ *
4
+ * This module decides what is available, what a party may book, who has proved
5
+ * they own a reservation, what is on hold, and what is committed. The voice
6
+ * agent can only *ask* it to do those things. If the language model were swapped
7
+ * for a web form tomorrow, every rule here would still hold.
8
+ *
9
+ * It uses Node's built-in SQLite module (node:sqlite), so it needs Node.js
10
+ * 22.16 or later and no package.
11
+ *
12
+ * Copyright (c) 2025 SignalWire. Licensed under the MIT License.
13
+ * See LICENSE file in the project root for full license information.
14
+ */
15
+
16
+ import { randomInt } from 'node:crypto';
17
+ import { mkdirSync } from 'node:fs';
18
+ import { dirname } from 'node:path';
19
+ import { DatabaseSync } from 'node:sqlite';
20
+
21
+ export const RESTAURANT_TZ = 'America/New_York';
22
+
23
+ // region: policy
24
+ // The whole house policy. The model is never shown any of it.
25
+ export const TABLES = { T1: 2, T2: 2, T3: 2, T4: 4, T5: 4, T6: 4, T7: 6, T8: 6 };
26
+ export const SEATINGS = Array.from({ length: 8 }, (_, i) => 17 * 60 + 30 * i); // 5:00 PM to 8:30 PM, every 30 minutes
27
+ export const DINING_MINUTES = 90; // a table is busy for 90 minutes after seating
28
+ export const MAX_PHONE_PARTY = 6; // larger parties are booked by the events team
29
+ export const MAX_EXTRA_SEATS = 2; // never seat a party of 2 at a 6-top
30
+ export const BOOKING_WINDOW_DAYS = 30;
31
+ export const CLOSED_WEEKDAYS = new Set([0]); // Monday
32
+ export const SAME_DAY_LEAD_MINUTES = 30; // no seating sooner than 30 minutes from now
33
+ export const HOLD_SECONDS = 300; // a proposal holds its table for 5 minutes
34
+ export const MAX_VERIFY_ATTEMPTS = 3;
35
+ export const HOST_STAND_HOURS = [16 * 60, 22 * 60] as const; // a person answers 4 PM to 10 PM, Tuesday to Sunday
36
+ export const SMS_RESEND_SECONDS = 120; // a repeat request sooner than this is a duplicate
37
+ export const MAX_SMS_PER_BOOKING = 3;
38
+ // endregion: policy
39
+
40
+ // Short, speakable facts the agent may look up. Nothing here is a promise the
41
+ // kitchen or the host stand has to keep, so it is safe to say verbatim.
42
+ export const HOUSE_FACTS: Record<string, string> = {
43
+ hours:
44
+ 'Dinner is served Tuesday through Sunday, with seatings from 5 PM to 8:30 PM. We are closed on Mondays.',
45
+ location: "We're at 14 Worcester Street, across from the old train station.",
46
+ parking: 'There is free street parking after 6 PM and a paid garage half a block away.',
47
+ dress_code: 'There is no dress code. Come as you are.',
48
+ large_parties:
49
+ 'Parties larger than six are booked by our events team, who can arrange a private room.',
50
+ cancellation_policy: 'You can cancel any time before your reservation at no charge.',
51
+ dietary:
52
+ 'The kitchen can adapt most dishes for vegetarian, vegan and gluten-free diets. Mention allergies to your server.',
53
+ };
54
+
55
+ const CODE_ALPHABET = 'ACDEFHJKMNPQRTUVWXY34679'; // no 0/O, 1/I, 2/Z, 5/S or 8/B to mishear
56
+ const WEEKDAYS = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'];
57
+ // prettier-ignore
58
+ const MONTH_NAMES = [
59
+ 'January', 'February', 'March', 'April', 'May', 'June',
60
+ 'July', 'August', 'September', 'October', 'November', 'December',
61
+ ];
62
+ // prettier-ignore
63
+ const MONTHS: Record<string, number> = {
64
+ jan: 1, january: 1, feb: 2, february: 2, mar: 3, march: 3,
65
+ apr: 4, april: 4, may: 5, jun: 6, june: 6, jul: 7, july: 7,
66
+ aug: 8, august: 8, sep: 9, sept: 9, september: 9, oct: 10,
67
+ october: 10, nov: 11, november: 11, dec: 12, december: 12,
68
+ };
69
+ const FILLER = new Set(['on', 'the', 'for', 'this', 'coming', 'day', 'night', 'evening', 'of']);
70
+
71
+ /**
72
+ * A request the house cannot honor.
73
+ *
74
+ * `fact` is what is true; `ask` is what the agent should do about it.
75
+ * Handlers pass them to the model as tool_result and tool_prompt.
76
+ */
77
+ export class PolicyError extends Error {
78
+ constructor(
79
+ readonly fact: string,
80
+ readonly ask: string,
81
+ ) {
82
+ super(fact);
83
+ this.name = new.target.name;
84
+ }
85
+ }
86
+
87
+ /** The party is bigger than the phone line may book. */
88
+ export class LargePartyError extends PolicyError {}
89
+
90
+ /** Too many failed verification attempts on this call. */
91
+ export class LockedOutError extends PolicyError {}
92
+
93
+ // -----------------------------------------------------------------------------
94
+ // Calendar days and the restaurant's clock
95
+ // -----------------------------------------------------------------------------
96
+
97
+ /** A calendar day, written as an ISO date such as "2026-09-25". */
98
+ export type Day = string;
99
+
100
+ const DAY_MS = 86_400_000;
101
+
102
+ function dayOf(year: number, month: number, day: number): Day | null {
103
+ if (month < 1 || month > 12 || day < 1 || day > 31) return null;
104
+ const date = new Date(Date.UTC(year, month - 1, day));
105
+ if (date.getUTCMonth() !== month - 1) return null; // February 30th rolls into March
106
+ return date.toISOString().slice(0, 10);
107
+ }
108
+
109
+ function parts(day: Day): [number, number, number] {
110
+ const [year, month, date] = day.split('-').map(Number);
111
+ return [year ?? 0, month ?? 0, date ?? 0];
112
+ }
113
+
114
+ /** The day `count` days after `day`. */
115
+ export function addDays(day: Day, count: number): Day {
116
+ const [year, month, date] = parts(day);
117
+ return new Date(Date.UTC(year, month - 1, date) + count * DAY_MS).toISOString().slice(0, 10);
118
+ }
119
+
120
+ /** 0 for Monday through 6 for Sunday. */
121
+ export function weekday(day: Day): number {
122
+ const [year, month, date] = parts(day);
123
+ return (new Date(Date.UTC(year, month - 1, date)).getUTCDay() + 6) % 7;
124
+ }
125
+
126
+ const WALL_CLOCK = new Intl.DateTimeFormat('en-US', {
127
+ timeZone: RESTAURANT_TZ,
128
+ hourCycle: 'h23',
129
+ year: 'numeric',
130
+ month: 'numeric',
131
+ day: 'numeric',
132
+ hour: 'numeric',
133
+ minute: 'numeric',
134
+ second: 'numeric',
135
+ });
136
+
137
+ /** What the restaurant's clock reads at `instant`: the day, and seconds since midnight. */
138
+ function wallClock(instant: Date): { day: Day; seconds: number } {
139
+ const field = (type: string): number =>
140
+ Number(WALL_CLOCK.formatToParts(instant).find((p) => p.type === type)?.value ?? 0);
141
+ return {
142
+ day: dayOf(field('year'), field('month'), field('day')) ?? '',
143
+ seconds: field('hour') * 3600 + field('minute') * 60 + field('second'),
144
+ };
145
+ }
146
+
147
+ // -----------------------------------------------------------------------------
148
+ // Speaking and hearing dates, times and codes
149
+ // -----------------------------------------------------------------------------
150
+
151
+ // region: resolve-date
152
+ /**
153
+ * Turn the caller's own words for a date into a date, or null.
154
+ *
155
+ * The model passes along what the caller said ("next Friday", "the 26th");
156
+ * code does the calendar arithmetic, and the caller confirms the result when
157
+ * it is read back. The model never does date math.
158
+ */
159
+ export function resolveDate(text: string, today: Day): Day | null {
160
+ let t = (text || '').toLowerCase().replace(/[,.]/g, ' ');
161
+ t = t.replace(/(\d+)(st|nd|rd|th)\b/g, '$1');
162
+ let words = t.split(/\s+/).filter((w) => w && !FILLER.has(w));
163
+ if (words.length === 0) return null;
164
+ const joined = words.join(' ');
165
+
166
+ if (joined === 'today' || joined === 'tonight') return today;
167
+ if (joined === 'tomorrow') return addDays(today, 1);
168
+
169
+ const iso = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(joined);
170
+ if (iso) return dayOf(Number(iso[1]), Number(iso[2]), Number(iso[3]));
171
+
172
+ const strictlyAfter = words[0] === 'next';
173
+ if (strictlyAfter) words = words.slice(1);
174
+ const prefixes = WEEKDAYS.map((d) => d.slice(0, 3));
175
+ if (words.length === 1 && prefixes.includes(words[0]!.slice(0, 3))) {
176
+ let ahead = (prefixes.indexOf(words[0]!.slice(0, 3)) - weekday(today) + 7) % 7;
177
+ if (ahead === 0 && strictlyAfter) ahead = 7;
178
+ return addDays(today, ahead);
179
+ }
180
+
181
+ const numeric = /^(\d{1,2})[/-](\d{1,2})$/.exec(joined);
182
+ if (numeric) return upcoming(Number(numeric[1]), Number(numeric[2]), today);
183
+
184
+ const month = words.map((w) => MONTHS[w]).find((m) => m !== undefined);
185
+ const day = words
186
+ .filter((w) => /^\d+$/.test(w))
187
+ .map(Number)
188
+ .find((d) => d >= 1 && d <= 31);
189
+ if (day !== undefined && month !== undefined) return upcoming(month, day, today);
190
+ if (day !== undefined && words.length === 1) {
191
+ // "the 26th" alone means the next 26th.
192
+ return nextDayOfMonth(day, today);
193
+ }
194
+ return null;
195
+ }
196
+ // endregion: resolve-date
197
+
198
+ /** The first date on or after today that falls on `day` of its month. */
199
+ function nextDayOfMonth(day: number, today: Day): Day | null {
200
+ let [year, month] = parts(today);
201
+ for (let i = 0; i < 13; i++) {
202
+ const candidate = dayOf(year, month, day);
203
+ if (candidate !== null && candidate >= today) return candidate;
204
+ [year, month] = month === 12 ? [year + 1, 1] : [year, month + 1];
205
+ }
206
+ return null;
207
+ }
208
+
209
+ /** The next `month`/`day` on or after today. */
210
+ function upcoming(month: number, day: number, today: Day): Day | null {
211
+ const [year] = parts(today);
212
+ const candidate = dayOf(year, month, day);
213
+ if (candidate !== null && candidate < today) return dayOf(year + 1, month, day);
214
+ return candidate;
215
+ }
216
+
217
+ /**
218
+ * Minutes after midnight for "7:30 pm", "19:30" or "7", or null.
219
+ *
220
+ * Dinner only: a bare "7:30" means 7:30 in the evening.
221
+ */
222
+ export function resolveTime(text: string): number | null {
223
+ const t = (text || '').toLowerCase().replaceAll('.', '').replaceAll("o'clock", '').trim();
224
+ const m = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm|a|p)?$/.exec(t);
225
+ if (!m) return null;
226
+ let hour = Number(m[1]);
227
+ const minute = Number(m[2] ?? 0);
228
+ const meridiem = m[3];
229
+ if (hour > 23 || minute > 59) return null;
230
+ if ((meridiem === 'pm' || meridiem === 'p') && hour < 12) hour += 12;
231
+ else if ((meridiem === 'am' || meridiem === 'a') && hour === 12) hour = 0;
232
+ else if (meridiem === undefined && hour >= 1 && hour <= 11) hour += 12;
233
+ return hour * 60 + minute;
234
+ }
235
+
236
+ /** "Friday, September 25". */
237
+ export function spokenDate(day: Day): string {
238
+ const [, month, date] = parts(day);
239
+ const name = WEEKDAYS[weekday(day)]!;
240
+ return `${name[0]!.toUpperCase()}${name.slice(1)}, ${MONTH_NAMES[month - 1]} ${date}`;
241
+ }
242
+
243
+ /** "7:30 PM", or "7 PM" on the hour. */
244
+ export function spokenTime(minutes: number): string {
245
+ const hour = Math.floor(minutes / 60);
246
+ const minute = minutes % 60;
247
+ const suffix = hour >= 12 ? 'PM' : 'AM';
248
+ const hour12 = hour > 12 ? hour - 12 : hour === 0 ? 12 : hour;
249
+ return minute ? `${hour12}:${String(minute).padStart(2, '0')} ${suffix}` : `${hour12} ${suffix}`;
250
+ }
251
+
252
+ /** "K7QP4M" becomes "K 7 Q P 4 M", so text-to-speech reads it one character at a time. */
253
+ export function spokenCode(code: string): string {
254
+ return [...code].join(' ');
255
+ }
256
+
257
+ export function normalizeCode(text: unknown): string {
258
+ return String(text ?? '')
259
+ .toUpperCase()
260
+ .replace(/[^A-Z0-9]/g, '');
261
+ }
262
+
263
+ // -----------------------------------------------------------------------------
264
+ // Values handed to the agent
265
+ // -----------------------------------------------------------------------------
266
+
267
+ export class Option {
268
+ constructor(
269
+ readonly number: number, // what the model and caller see
270
+ readonly tableId: string, // what they never see
271
+ readonly day: Day,
272
+ readonly start: number,
273
+ ) {}
274
+
275
+ spoken(): string {
276
+ return `option ${this.number}, ${spokenTime(this.start)}`;
277
+ }
278
+ }
279
+
280
+ export class Request {
281
+ constructor(
282
+ readonly partySize: number,
283
+ readonly day: Day,
284
+ readonly start: number,
285
+ readonly name: string,
286
+ ) {}
287
+
288
+ spoken(): string {
289
+ return (
290
+ `a table for ${this.partySize} on ${spokenDate(this.day)} ` +
291
+ `around ${spokenTime(this.start)}, under ${this.name}`
292
+ );
293
+ }
294
+ }
295
+
296
+ export class Proposal {
297
+ constructor(
298
+ readonly revision: number,
299
+ readonly day: Day,
300
+ readonly start: number,
301
+ readonly partySize: number,
302
+ readonly name: string,
303
+ ) {}
304
+
305
+ spoken(): string {
306
+ return (
307
+ `a table for ${this.partySize} on ${spokenDate(this.day)} ` +
308
+ `at ${spokenTime(this.start)}, under ${this.name}`
309
+ );
310
+ }
311
+ }
312
+
313
+ export class Reservation {
314
+ constructor(
315
+ readonly code: string,
316
+ readonly day: Day,
317
+ readonly start: number,
318
+ readonly partySize: number,
319
+ readonly name: string,
320
+ readonly status: string,
321
+ ) {}
322
+
323
+ spoken(): string {
324
+ return (
325
+ `a table for ${this.partySize} on ${spokenDate(this.day)} ` +
326
+ `at ${spokenTime(this.start)}, under ${this.name}`
327
+ );
328
+ }
329
+ }
330
+
331
+ // -----------------------------------------------------------------------------
332
+ // The store
333
+ // -----------------------------------------------------------------------------
334
+
335
+ const SCHEMA = `
336
+ CREATE TABLE IF NOT EXISTS sessions (
337
+ call_id TEXT PRIMARY KEY,
338
+ draft TEXT NOT NULL DEFAULT '{}',
339
+ request TEXT NOT NULL DEFAULT '{}',
340
+ offers TEXT NOT NULL DEFAULT '[]',
341
+ proposal_counter INTEGER NOT NULL DEFAULT 0,
342
+ verified_code TEXT,
343
+ verify_failures INTEGER NOT NULL DEFAULT 0,
344
+ cancel_revision INTEGER,
345
+ cancel_counter INTEGER NOT NULL DEFAULT 0
346
+ );
347
+ CREATE TABLE IF NOT EXISTS holds (
348
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
349
+ call_id TEXT NOT NULL,
350
+ table_id TEXT NOT NULL,
351
+ day TEXT NOT NULL,
352
+ start INTEGER NOT NULL,
353
+ party_size INTEGER NOT NULL,
354
+ name TEXT NOT NULL,
355
+ revision INTEGER NOT NULL,
356
+ expires_at REAL NOT NULL,
357
+ status TEXT NOT NULL
358
+ );
359
+ CREATE TABLE IF NOT EXISTS reservations (
360
+ code TEXT PRIMARY KEY,
361
+ hold_id INTEGER UNIQUE,
362
+ call_id TEXT,
363
+ table_id TEXT NOT NULL,
364
+ day TEXT NOT NULL,
365
+ start INTEGER NOT NULL,
366
+ party_size INTEGER NOT NULL,
367
+ name TEXT NOT NULL,
368
+ status TEXT NOT NULL,
369
+ sms_requests INTEGER NOT NULL DEFAULT 0,
370
+ sms_requested_at REAL NOT NULL DEFAULT 0
371
+ );
372
+ CREATE TABLE IF NOT EXISTS messages (
373
+ call_id TEXT PRIMARY KEY,
374
+ name TEXT NOT NULL,
375
+ callback TEXT NOT NULL,
376
+ body TEXT NOT NULL
377
+ );
378
+ CREATE TABLE IF NOT EXISTS call_records (
379
+ call_id TEXT PRIMARY KEY,
380
+ turns INTEGER NOT NULL,
381
+ outcome TEXT NOT NULL
382
+ );
383
+ `;
384
+
385
+ interface SessionRow {
386
+ call_id: string;
387
+ draft: string;
388
+ request: string;
389
+ offers: string;
390
+ proposal_counter: number;
391
+ verified_code: string | null;
392
+ verify_failures: number;
393
+ cancel_revision: number | null;
394
+ cancel_counter: number;
395
+ }
396
+
397
+ interface HoldRow {
398
+ id: number;
399
+ call_id: string;
400
+ table_id: string;
401
+ day: Day;
402
+ start: number;
403
+ party_size: number;
404
+ name: string;
405
+ revision: number;
406
+ expires_at: number;
407
+ status: string;
408
+ }
409
+
410
+ interface ReservationRow {
411
+ code: string;
412
+ day: Day;
413
+ start: number;
414
+ party_size: number;
415
+ name: string;
416
+ status: string;
417
+ sms_requests: number;
418
+ sms_requested_at: number;
419
+ }
420
+
421
+ interface Offer {
422
+ number: number;
423
+ table_id: string;
424
+ day: Day;
425
+ start: number;
426
+ }
427
+
428
+ /** The details a caller has asked for so far. Each one is caller input until checked. */
429
+ export type Draft = Record<'party_size' | 'date' | 'time' | 'name', unknown>;
430
+
431
+ const DRAFT_KEYS = ['party_size', 'date', 'time', 'name'] as const;
432
+
433
+ const isBlank = (value: unknown): boolean => value === undefined || value === null || value === '';
434
+
435
+ /**
436
+ * The system of record. One SQLite file; every write is a transaction.
437
+ *
438
+ * State is keyed by `callId` so it survives restarts and never depends on
439
+ * what the conversation remembers. A call id correlates a session; it is not
440
+ * proof of who is calling.
441
+ */
442
+ export class ReservationStore {
443
+ private readonly db: DatabaseSync;
444
+
445
+ constructor(
446
+ readonly path: string,
447
+ readonly clock: () => Date = () => new Date(),
448
+ ) {
449
+ mkdirSync(dirname(path), { recursive: true });
450
+ this.db = new DatabaseSync(path, { timeout: 5000 });
451
+ this.db.exec(SCHEMA);
452
+ }
453
+
454
+ /** Run `work` in one write transaction: all of it commits, or none of it does. */
455
+ private tx<T>(work: (db: DatabaseSync) => T): T {
456
+ this.db.exec('BEGIN IMMEDIATE');
457
+ try {
458
+ const result = work(this.db);
459
+ this.db.exec('COMMIT');
460
+ return result;
461
+ } catch (err) {
462
+ if (this.db.isTransaction) this.db.exec('ROLLBACK');
463
+ throw err;
464
+ }
465
+ }
466
+
467
+ /** Close the database. The store can't be used afterwards. */
468
+ close(): void {
469
+ this.db.close();
470
+ }
471
+
472
+ private static checkCall(callId: unknown): asserts callId is string {
473
+ if (typeof callId !== 'string' || !callId || callId.length > 256) {
474
+ throw new Error('Missing or invalid call context.');
475
+ }
476
+ }
477
+
478
+ private session(db: DatabaseSync, callId: string): SessionRow {
479
+ ReservationStore.checkCall(callId);
480
+ db.prepare('INSERT OR IGNORE INTO sessions (call_id) VALUES (?)').run(callId);
481
+ return db
482
+ .prepare('SELECT * FROM sessions WHERE call_id=?')
483
+ .get(callId) as unknown as SessionRow;
484
+ }
485
+
486
+ private now(): Date {
487
+ return this.clock();
488
+ }
489
+
490
+ /** The restaurant's date today. */
491
+ today(): Day {
492
+ return wallClock(this.now()).day;
493
+ }
494
+
495
+ // ---------------------------------------------------------------------------
496
+ // Availability
497
+ // ---------------------------------------------------------------------------
498
+
499
+ private tableFree(
500
+ db: DatabaseSync,
501
+ tableId: string,
502
+ day: Day,
503
+ start: number,
504
+ callId: string,
505
+ ): boolean {
506
+ const busy = db
507
+ .prepare(
508
+ "SELECT 1 FROM reservations WHERE table_id=? AND day=? AND status='confirmed' " +
509
+ 'AND ABS(start - ?) < ?',
510
+ )
511
+ .get(tableId, day, start, DINING_MINUTES);
512
+ const held = db
513
+ .prepare(
514
+ "SELECT 1 FROM holds WHERE table_id=? AND day=? AND status='live' AND call_id<>? " +
515
+ 'AND expires_at > ? AND ABS(start - ?) < ?',
516
+ )
517
+ .get(tableId, day, callId, this.now().getTime() / 1000, start, DINING_MINUTES);
518
+ return busy === undefined && held === undefined;
519
+ }
520
+
521
+ /**
522
+ * Whether a seating starts less than SAME_DAY_LEAD_MINUTES from now.
523
+ *
524
+ * Both sides are wall-clock times in the restaurant's zone. Seatings are in
525
+ * the evening, hours away from a daylight-saving change, so that's exact.
526
+ */
527
+ private tooSoon(day: Day, start: number): boolean {
528
+ const now = wallClock(this.now());
529
+ const [ny, nm, nd] = parts(now.day);
530
+ const [sy, sm, sd] = parts(day);
531
+ const nowAt = Date.UTC(ny, nm - 1, nd) / 1000 + now.seconds;
532
+ const startsAt = Date.UTC(sy, sm - 1, sd) / 1000 + start * 60;
533
+ return startsAt < nowAt + SAME_DAY_LEAD_MINUTES * 60;
534
+ }
535
+
536
+ /** Refuse a seating that is no longer far enough ahead to book. */
537
+ private checkNotice(day: Day, start: number): void {
538
+ if (this.tooSoon(day, start)) {
539
+ throw new PolicyError(
540
+ 'That seating is too soon to book now.',
541
+ 'Apologize and check availability again.',
542
+ );
543
+ }
544
+ }
545
+
546
+ private validateRequest(
547
+ partySize: unknown,
548
+ dateText: unknown,
549
+ timeText: unknown,
550
+ name: unknown,
551
+ ): [number, Day, number, string] {
552
+ let party = partySize;
553
+ if (typeof party === 'string' && /^\s*\d+\s*$/.test(party)) party = Number(party);
554
+ if (typeof party !== 'number' || !Number.isInteger(party) || party < 1) {
555
+ throw new PolicyError(
556
+ "The party size wasn't a number of people.",
557
+ 'Ask how many people will be dining.',
558
+ );
559
+ }
560
+ if (party > MAX_PHONE_PARTY) {
561
+ throw new LargePartyError(
562
+ `Parties larger than ${MAX_PHONE_PARTY} are booked by the events team.`,
563
+ 'Explain that, and offer to connect them with a person.',
564
+ );
565
+ }
566
+ const today = this.today();
567
+ const day = resolveDate(String(dateText ?? ''), today);
568
+ if (day === null) {
569
+ throw new PolicyError(
570
+ "That date couldn't be understood.",
571
+ "Ask for the date again, for example 'Friday' or 'September 26'.",
572
+ );
573
+ }
574
+ if (day < today) {
575
+ throw new PolicyError(
576
+ `${spokenDate(day)} has already passed.`,
577
+ 'Ask for a date from today onward.',
578
+ );
579
+ }
580
+ if (day > addDays(today, BOOKING_WINDOW_DAYS)) {
581
+ throw new PolicyError(
582
+ `Reservations open ${BOOKING_WINDOW_DAYS} days ahead.`,
583
+ 'Ask for a date within the next month.',
584
+ );
585
+ }
586
+ if (CLOSED_WEEKDAYS.has(weekday(day))) {
587
+ const [, month, date] = parts(day);
588
+ throw new PolicyError(
589
+ `We're closed on Mondays, and ${MONTH_NAMES[month - 1]} ${date} is a Monday.`,
590
+ 'Ask for another date.',
591
+ );
592
+ }
593
+ const start = resolveTime(String(timeText ?? ''));
594
+ if (start === null) {
595
+ throw new PolicyError(
596
+ "That time couldn't be understood.",
597
+ "Ask what time they'd like, for example '7:30 PM'.",
598
+ );
599
+ }
600
+ const cleanName = String(name ?? '')
601
+ .split(/\s+/)
602
+ .filter(Boolean)
603
+ .join(' ');
604
+ if (!cleanName || cleanName.length > 60) {
605
+ throw new PolicyError(
606
+ 'The reservation needs a name.',
607
+ 'Ask for the name for the reservation.',
608
+ );
609
+ }
610
+ return [party, day, start, cleanName];
611
+ }
612
+
613
+ // region: find-options
614
+ /**
615
+ * Up to three bookable seatings near the requested time.
616
+ *
617
+ * Tables are chosen here and never leave this module: the caller and the
618
+ * model only ever see option numbers.
619
+ */
620
+ findOptions(
621
+ callId: string,
622
+ partySize: unknown,
623
+ dateText: unknown,
624
+ timeText: unknown,
625
+ name: unknown,
626
+ ): [Request, Option[]] {
627
+ const [party, day, wanted, cleanName] = this.validateRequest(
628
+ partySize,
629
+ dateText,
630
+ timeText,
631
+ name,
632
+ );
633
+ return this.tx((db) => {
634
+ this.session(db, callId);
635
+ // A new search supersedes this call's old proposal.
636
+ db.prepare("UPDATE holds SET status='released' WHERE call_id=? AND status='live'").run(
637
+ callId,
638
+ );
639
+ const options: Option[] = [];
640
+ const nearby = SEATINGS.filter(
641
+ (s) => Math.abs(s - wanted) <= 60 && !this.tooSoon(day, s),
642
+ ).sort((a, b) => Math.abs(a - wanted) - Math.abs(b - wanted) || a - b);
643
+ for (const seating of nearby) {
644
+ const fits = Object.entries(TABLES)
645
+ .filter(([, cap]) => party <= cap && cap <= party + MAX_EXTRA_SEATS)
646
+ .sort(([ta, ca], [tb, cb]) => ca - cb || ta.localeCompare(tb));
647
+ const table = fits.find(([tid]) => this.tableFree(db, tid, day, seating, callId));
648
+ if (table) options.push(new Option(options.length + 1, table[0], day, seating));
649
+ if (options.length === 3) break;
650
+ }
651
+ const request = { party_size: party, day, start: wanted, name: cleanName };
652
+ db.prepare('UPDATE sessions SET request=?, offers=? WHERE call_id=?').run(
653
+ JSON.stringify(request),
654
+ JSON.stringify(
655
+ options.map((o) => ({
656
+ number: o.number,
657
+ table_id: o.tableId,
658
+ day: o.day,
659
+ start: o.start,
660
+ })),
661
+ ),
662
+ callId,
663
+ );
664
+ return [new Request(party, day, wanted, cleanName), options];
665
+ });
666
+ }
667
+ // endregion: find-options
668
+
669
+ // region: update-draft
670
+ /**
671
+ * Apply a correction to what this call has asked for, and return the result.
672
+ *
673
+ * The draft is kept whether or not a search passes the rules, so a correction
674
+ * to a refused search isn't lost. The first search starts from `gathered`.
675
+ */
676
+ updateDraft(
677
+ callId: string,
678
+ changes: Record<string, unknown>,
679
+ gathered: Record<string, unknown>,
680
+ ): Draft {
681
+ return this.tx((db) => {
682
+ let draft = JSON.parse(this.session(db, callId).draft) as Draft;
683
+ if (Object.keys(draft).length === 0) {
684
+ draft = Object.fromEntries(DRAFT_KEYS.map((key) => [key, gathered[key] ?? null])) as Draft;
685
+ }
686
+ for (const key of DRAFT_KEYS) {
687
+ if (!isBlank(changes[key])) draft[key] = changes[key];
688
+ }
689
+ db.prepare('UPDATE sessions SET draft=? WHERE call_id=?').run(JSON.stringify(draft), callId);
690
+ return draft;
691
+ });
692
+ }
693
+ // endregion: update-draft
694
+
695
+ /** Forget this call's booking in progress, so a new one starts from gathered answers. */
696
+ resetRequest(callId: string): void {
697
+ this.tx((db) => {
698
+ this.session(db, callId);
699
+ db.prepare("UPDATE sessions SET draft='{}', request='{}', offers='[]' WHERE call_id=?").run(
700
+ callId,
701
+ );
702
+ db.prepare("UPDATE holds SET status='released' WHERE call_id=? AND status='live'").run(
703
+ callId,
704
+ );
705
+ });
706
+ }
707
+
708
+ // region: hold-option
709
+ /**
710
+ * Reserve one offered option for HOLD_SECONDS and return a numbered proposal.
711
+ *
712
+ * Re-holding the option this call already holds returns the same proposal,
713
+ * so a model that fires the tool twice changes nothing.
714
+ */
715
+ holdOption(callId: string, number: unknown): Proposal {
716
+ if (typeof number !== 'number' || !Number.isInteger(number)) {
717
+ throw new PolicyError('No option number was given.', "Ask which option they'd like.");
718
+ }
719
+ return this.tx((db) => {
720
+ const session = this.session(db, callId);
721
+ const offer = (JSON.parse(session.offers) as Offer[]).find((o) => o.number === number);
722
+ if (offer === undefined) {
723
+ throw new PolicyError(
724
+ `There is no option ${number} on the list that was offered.`,
725
+ 'Offer the options again by number.',
726
+ );
727
+ }
728
+ const request = JSON.parse(session.request) as { party_size: number; name: string };
729
+ const nowTs = this.now().getTime() / 1000;
730
+ const live = db
731
+ .prepare("SELECT * FROM holds WHERE call_id=? AND status='live' AND expires_at > ?")
732
+ .get(callId, nowTs) as HoldRow | undefined;
733
+ if (
734
+ live &&
735
+ live.table_id === offer.table_id &&
736
+ live.start === offer.start &&
737
+ live.day === offer.day
738
+ ) {
739
+ return ReservationStore.proposal(live);
740
+ }
741
+ db.prepare("UPDATE holds SET status='released' WHERE call_id=? AND status='live'").run(
742
+ callId,
743
+ );
744
+ this.checkNotice(offer.day, offer.start);
745
+ if (!this.tableFree(db, offer.table_id, offer.day, offer.start, callId)) {
746
+ throw new PolicyError(
747
+ 'That seating was just taken by another guest.',
748
+ 'Apologize and check availability again.',
749
+ );
750
+ }
751
+ const revision = session.proposal_counter + 1;
752
+ db.prepare('UPDATE sessions SET proposal_counter=? WHERE call_id=?').run(revision, callId);
753
+ const inserted = db
754
+ .prepare(
755
+ 'INSERT INTO holds (call_id, table_id, day, start, party_size, name, revision, ' +
756
+ "expires_at, status) VALUES (?,?,?,?,?,?,?,?, 'live')",
757
+ )
758
+ .run(
759
+ callId,
760
+ offer.table_id,
761
+ offer.day,
762
+ offer.start,
763
+ request.party_size,
764
+ request.name,
765
+ revision,
766
+ nowTs + HOLD_SECONDS,
767
+ );
768
+ const row = db
769
+ .prepare('SELECT * FROM holds WHERE id=?')
770
+ .get(inserted.lastInsertRowid) as unknown as HoldRow;
771
+ return ReservationStore.proposal(row);
772
+ });
773
+ }
774
+ // endregion: hold-option
775
+
776
+ private static proposal(row: HoldRow): Proposal {
777
+ return new Proposal(row.revision, row.day, row.start, row.party_size, row.name);
778
+ }
779
+
780
+ private static reservation(row: ReservationRow): Reservation {
781
+ return new Reservation(row.code, row.day, row.start, row.party_size, row.name, row.status);
782
+ }
783
+
784
+ // region: confirm
785
+ /**
786
+ * Commit the proposal the caller agreed to, exactly once.
787
+ *
788
+ * `revision` binds the commitment to the proposal that was read back:
789
+ * if anything changed since, the old revision no longer commits.
790
+ */
791
+ confirm(callId: string, revision: unknown): Reservation {
792
+ if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 1) {
793
+ throw new PolicyError(
794
+ 'No proposal revision was given.',
795
+ 'Read back the current proposal and ask the caller to confirm it.',
796
+ );
797
+ }
798
+ return this.tx((db) => {
799
+ this.session(db, callId);
800
+ const done = db
801
+ .prepare(
802
+ 'SELECT r.* FROM reservations r JOIN holds h ON r.hold_id = h.id ' +
803
+ 'WHERE h.call_id=? AND h.revision=?',
804
+ )
805
+ .get(callId, revision) as ReservationRow | undefined;
806
+ if (done) return ReservationStore.reservation(done); // a repeated confirm returns the same booking
807
+ const hold = db
808
+ .prepare("SELECT * FROM holds WHERE call_id=? AND status='live' ORDER BY id DESC LIMIT 1")
809
+ .get(callId) as HoldRow | undefined;
810
+ if (hold === undefined) {
811
+ throw new PolicyError('No table is on hold.', 'Check availability again.');
812
+ }
813
+ if (hold.revision !== revision) {
814
+ throw new PolicyError(
815
+ 'The proposal changed since it was read back.',
816
+ 'Read back the current proposal and ask again.',
817
+ );
818
+ }
819
+ if (hold.expires_at <= this.now().getTime() / 1000) {
820
+ db.prepare("UPDATE holds SET status='released' WHERE id=?").run(hold.id);
821
+ throw new PolicyError('The hold on that table expired.', 'Check availability again.');
822
+ }
823
+ this.checkNotice(hold.day, hold.start);
824
+ const code = ReservationStore.newCode(db);
825
+ db.prepare(
826
+ 'INSERT INTO reservations (code, hold_id, call_id, table_id, day, start, ' +
827
+ "party_size, name, status) VALUES (?,?,?,?,?,?,?,?, 'confirmed')",
828
+ ).run(code, hold.id, callId, hold.table_id, hold.day, hold.start, hold.party_size, hold.name);
829
+ db.prepare("UPDATE holds SET status='confirmed' WHERE id=?").run(hold.id);
830
+ const row = db.prepare('SELECT * FROM reservations WHERE code=?').get(code);
831
+ return ReservationStore.reservation(row as unknown as ReservationRow);
832
+ });
833
+ }
834
+ // endregion: confirm
835
+
836
+ private static newCode(db: DatabaseSync): string {
837
+ for (;;) {
838
+ const code = Array.from(
839
+ { length: 6 },
840
+ () => CODE_ALPHABET[randomInt(CODE_ALPHABET.length)],
841
+ ).join('');
842
+ if (db.prepare('SELECT 1 FROM reservations WHERE code=?').get(code) === undefined)
843
+ return code;
844
+ }
845
+ }
846
+
847
+ /** The most recent reservation this call created, if any. */
848
+ bookingForCall(callId: string): Reservation | null {
849
+ ReservationStore.checkCall(callId);
850
+ return this.tx((db) => {
851
+ const row = db
852
+ .prepare(
853
+ "SELECT * FROM reservations WHERE call_id=? AND status='confirmed' " +
854
+ 'ORDER BY rowid DESC LIMIT 1',
855
+ )
856
+ .get(callId) as ReservationRow | undefined;
857
+ return row ? ReservationStore.reservation(row) : null;
858
+ });
859
+ }
860
+
861
+ // region: request-sms
862
+ /**
863
+ * Record a request to text a booking, and say whether to send it.
864
+ *
865
+ * The platform sends the text after the tool returns, so nothing here can
866
+ * know it arrived. A repeat within SMS_RESEND_SECONDS is a duplicate and
867
+ * isn't sent. After that, a caller who didn't get it may ask again, up to
868
+ * MAX_SMS_PER_BOOKING times. Returns "send", "duplicate" or "limit".
869
+ */
870
+ requestSms(code: string): 'send' | 'duplicate' | 'limit' {
871
+ const now = this.now().getTime() / 1000;
872
+ return this.tx((db) => {
873
+ const row = db
874
+ .prepare('SELECT sms_requests, sms_requested_at FROM reservations WHERE code=?')
875
+ .get(code) as unknown as ReservationRow;
876
+ if (row.sms_requests >= MAX_SMS_PER_BOOKING) return 'limit';
877
+ if (row.sms_requests && now - row.sms_requested_at < SMS_RESEND_SECONDS) return 'duplicate';
878
+ db.prepare(
879
+ 'UPDATE reservations SET sms_requests = sms_requests + 1, sms_requested_at = ? WHERE code=?',
880
+ ).run(now, code);
881
+ return 'send';
882
+ });
883
+ }
884
+ // endregion: request-sms
885
+
886
+ // ---------------------------------------------------------------------------
887
+ // Managing an existing reservation
888
+ // ---------------------------------------------------------------------------
889
+
890
+ // region: verify
891
+ /**
892
+ * Bind a reservation to this call if the caller knows its code and name.
893
+ *
894
+ * A wrong answer never says which half was wrong, and the third failure
895
+ * on a call locks the lookup for the rest of that call.
896
+ */
897
+ verify(callId: string, codeText: unknown, lastName: unknown): Reservation {
898
+ const failures = this.tx((db) => {
899
+ const session = this.session(db, callId);
900
+ if (session.verify_failures >= MAX_VERIFY_ATTEMPTS) {
901
+ throw new LockedOutError(
902
+ 'Too many attempts on this call.',
903
+ "Say you can't look it up by phone right now, and offer a person.",
904
+ );
905
+ }
906
+ const row = db
907
+ .prepare('SELECT * FROM reservations WHERE code=?')
908
+ .get(normalizeCode(codeText)) as ReservationRow | undefined;
909
+ const said = String(lastName ?? '')
910
+ .toLowerCase()
911
+ .split(/\s+/)
912
+ .filter(Boolean)
913
+ .join(' ');
914
+ const onFile = row ? row.name.toLowerCase().split(/\s+/).filter(Boolean) : [];
915
+ if (row && said && (said === onFile.join(' ') || said === onFile.at(-1))) {
916
+ db.prepare('UPDATE sessions SET verified_code=?, cancel_revision=NULL WHERE call_id=?').run(
917
+ row.code,
918
+ callId,
919
+ );
920
+ return ReservationStore.reservation(row);
921
+ }
922
+ const count = session.verify_failures + 1;
923
+ db.prepare('UPDATE sessions SET verify_failures=? WHERE call_id=?').run(count, callId);
924
+ return count;
925
+ });
926
+ if (failures instanceof Reservation) return failures;
927
+ // Thrown after the transaction commits, so the failed attempt is counted.
928
+ if (failures >= MAX_VERIFY_ATTEMPTS) {
929
+ throw new LockedOutError(
930
+ 'Too many attempts on this call.',
931
+ "Say you can't look it up by phone right now, and offer a person.",
932
+ );
933
+ }
934
+ throw new PolicyError(
935
+ "That code and last name don't match a reservation.",
936
+ 'Ask the caller to check the code and say it again.',
937
+ );
938
+ }
939
+ // endregion: verify
940
+
941
+ // region: verified
942
+ /** Every manage operation starts here: what has *this* call verified? */
943
+ private verified(db: DatabaseSync, callId: string): [SessionRow, ReservationRow] {
944
+ const session = this.session(db, callId);
945
+ if (!session.verified_code) {
946
+ throw new PolicyError(
947
+ "This call hasn't verified a reservation.",
948
+ 'Ask for the confirmation code and last name first.',
949
+ );
950
+ }
951
+ const row = db
952
+ .prepare('SELECT * FROM reservations WHERE code=?')
953
+ .get(session.verified_code) as unknown as ReservationRow;
954
+ return [session, row];
955
+ }
956
+ // endregion: verified
957
+
958
+ verifiedReservation(callId: string): Reservation {
959
+ return this.tx((db) => ReservationStore.reservation(this.verified(db, callId)[1]));
960
+ }
961
+
962
+ // region: cancel
963
+ /** Stage a cancellation and return the revision that must confirm it. */
964
+ requestCancel(callId: string): [Reservation, number] {
965
+ return this.tx((db) => {
966
+ const [session, row] = this.verified(db, callId);
967
+ if (row.status === 'cancelled') {
968
+ throw new PolicyError(
969
+ 'That reservation is already cancelled.',
970
+ "Tell the caller, and ask if there's anything else.",
971
+ );
972
+ }
973
+ const revision = session.cancel_counter + 1;
974
+ db.prepare('UPDATE sessions SET cancel_counter=?, cancel_revision=? WHERE call_id=?').run(
975
+ revision,
976
+ revision,
977
+ callId,
978
+ );
979
+ return [ReservationStore.reservation(row), revision];
980
+ });
981
+ }
982
+
983
+ /** Cancel, but only the staged cancellation the caller agreed to. */
984
+ confirmCancel(callId: string, revision: unknown): Reservation {
985
+ return this.tx((db) => {
986
+ const [session, row] = this.verified(db, callId);
987
+ if (row.status === 'cancelled') return ReservationStore.reservation(row); // a repeated confirm is harmless
988
+ if (typeof revision !== 'number' || session.cancel_revision !== revision) {
989
+ throw new PolicyError(
990
+ "There's no matching cancellation waiting to be confirmed.",
991
+ 'Read the reservation back and ask whether to cancel it.',
992
+ );
993
+ }
994
+ db.prepare("UPDATE reservations SET status='cancelled' WHERE code=?").run(row.code);
995
+ db.prepare('UPDATE sessions SET cancel_revision=NULL WHERE call_id=?').run(callId);
996
+ const cancelled = db.prepare('SELECT * FROM reservations WHERE code=?').get(row.code);
997
+ return ReservationStore.reservation(cancelled as unknown as ReservationRow);
998
+ });
999
+ }
1000
+ // endregion: cancel
1001
+
1002
+ keepReservation(callId: string): Reservation {
1003
+ return this.tx((db) => {
1004
+ const [, row] = this.verified(db, callId);
1005
+ db.prepare('UPDATE sessions SET cancel_revision=NULL WHERE call_id=?').run(callId);
1006
+ return ReservationStore.reservation(row);
1007
+ });
1008
+ }
1009
+
1010
+ // ---------------------------------------------------------------------------
1011
+ // Messages, the host stand, and call records
1012
+ // ---------------------------------------------------------------------------
1013
+
1014
+ /** Store one message per call; saving again returns the first one. */
1015
+ saveMessage(
1016
+ callId: string,
1017
+ name: string,
1018
+ callback: string,
1019
+ body: string,
1020
+ ): { name: string; callback: string; body: string } {
1021
+ const digits = (callback || '').replace(/\D/g, '');
1022
+ if (digits.length < 10 || digits.length > 15) {
1023
+ throw new PolicyError(
1024
+ "The callback number didn't have enough digits.",
1025
+ 'Ask for a callback number including the area code.',
1026
+ );
1027
+ }
1028
+ const clean = (text: string): string => (text || '').split(/\s+/).filter(Boolean).join(' ');
1029
+ const [cleanName, cleanBody] = [clean(name), clean(body)];
1030
+ if (!cleanName || !cleanBody) {
1031
+ throw new PolicyError(
1032
+ 'The message needs a name and a few words.',
1033
+ 'Ask for whatever is missing.',
1034
+ );
1035
+ }
1036
+ return this.tx((db) => {
1037
+ this.session(db, callId);
1038
+ db.prepare('INSERT OR IGNORE INTO messages VALUES (?,?,?,?)').run(
1039
+ callId,
1040
+ cleanName.slice(0, 60),
1041
+ digits,
1042
+ cleanBody.slice(0, 500),
1043
+ );
1044
+ const row = db.prepare('SELECT * FROM messages WHERE call_id=?').get(callId) as {
1045
+ name: string;
1046
+ callback: string;
1047
+ body: string;
1048
+ };
1049
+ return { name: row.name, callback: row.callback, body: row.body };
1050
+ });
1051
+ }
1052
+
1053
+ hostStandOpen(): boolean {
1054
+ const now = wallClock(this.now());
1055
+ const minute = Math.floor(now.seconds / 60);
1056
+ return (
1057
+ !CLOSED_WEEKDAYS.has(weekday(now.day)) &&
1058
+ HOST_STAND_HOURS[0] <= minute &&
1059
+ minute < HOST_STAND_HOURS[1]
1060
+ );
1061
+ }
1062
+
1063
+ /** Write what actually happened on this call, from the store, not the transcript. */
1064
+ recordCallEnd(callId: string, turns: number): string {
1065
+ return this.tx((db) => {
1066
+ this.session(db, callId);
1067
+ let outcome: string;
1068
+ if (
1069
+ db.prepare("SELECT 1 FROM reservations WHERE call_id=? AND status='confirmed'").get(callId)
1070
+ ) {
1071
+ outcome = 'booked';
1072
+ } else if (
1073
+ db
1074
+ .prepare(
1075
+ 'SELECT 1 FROM sessions s JOIN reservations r ON r.code = s.verified_code ' +
1076
+ "WHERE s.call_id=? AND r.status='cancelled'",
1077
+ )
1078
+ .get(callId)
1079
+ ) {
1080
+ outcome = 'cancelled';
1081
+ } else if (db.prepare('SELECT 1 FROM messages WHERE call_id=?').get(callId)) {
1082
+ outcome = 'message';
1083
+ } else {
1084
+ outcome = 'no_change';
1085
+ }
1086
+ db.prepare('INSERT OR REPLACE INTO call_records VALUES (?,?,?)').run(
1087
+ callId,
1088
+ Math.trunc(turns),
1089
+ outcome,
1090
+ );
1091
+ return outcome;
1092
+ });
1093
+ }
1094
+
1095
+ /** Add one known reservation (code K7QP4M, Rivera) so the manage flow can be tried. */
1096
+ seedDemo(): string | null {
1097
+ return this.tx((db) => {
1098
+ if (db.prepare('SELECT 1 FROM reservations').get()) return null;
1099
+ let day = addDays(this.today(), 2);
1100
+ while (CLOSED_WEEKDAYS.has(weekday(day))) day = addDays(day, 1);
1101
+ db.prepare(
1102
+ 'INSERT INTO reservations (code, hold_id, call_id, table_id, day, start, ' +
1103
+ "party_size, name, status) VALUES ('K7QP4M', NULL, 'seed', 'T4', ?, ?, 4, " +
1104
+ "'Maria Rivera', 'confirmed')",
1105
+ ).run(day, 19 * 60);
1106
+ return 'K7QP4M';
1107
+ });
1108
+ }
1109
+ }