@openclaw/discord 2026.6.8 → 2026.6.9

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 (114) hide show
  1. package/dist/action-runtime-api.js +1 -1
  2. package/dist/{api-BmXlcjYW.js → api-4GFMoWu0.js} +4 -1
  3. package/dist/api.js +15 -15
  4. package/dist/{approval-handler.runtime-B3gyUd-L.js → approval-handler.runtime-20qhf0uH.js} +3 -3
  5. package/dist/{audit-BlfewK04.js → audit-CCffO6o7.js} +3 -3
  6. package/dist/{channel-actions-BnPHwCZ_.js → channel-actions-DDT9kJXw.js} +12 -6
  7. package/dist/{channel-actions.runtime-DX5iW6ut.js → channel-actions.runtime-CfMUtfAv.js} +5 -5
  8. package/dist/{channel-b0hY1EJw.js → channel-fEBKaO2Q.js} +28 -20
  9. package/dist/channel-plugin-api.js +1 -1
  10. package/dist/{channel.setup-By5cfELZ.js → channel.setup-DRJiHe7I.js} +2 -3
  11. package/dist/{components-D-CYw0-b.js → components-CXEorOhu.js} +1 -1
  12. package/dist/{conversation-identity-CKzQAqFF.js → conversation-identity-BvlP-djn.js} +2 -2
  13. package/dist/{directory-config-Bu7FYOsl.js → directory-config-Bg8bulWB.js} +1 -1
  14. package/dist/directory-contract-api.js +1 -1
  15. package/dist/{directory-live-LjENjK6L.js → directory-live-BAJw6kS2.js} +2 -2
  16. package/dist/{handle-action.guild-admin-BS2qnhXF.js → handle-action.guild-admin-RxnJFLgU.js} +14 -9
  17. package/dist/index.js +1 -1
  18. package/dist/{manager.runtime-BU1vkOeO.js → manager.runtime-Bh5X0o8P.js} +12 -4
  19. package/dist/{message-handler-CQVkXHMN.js → message-handler-Dg3DRD0e.js} +6 -6
  20. package/dist/{message-handler.preflight-DAnLOeDA.js → message-handler.preflight-CcexCYuy.js} +10 -10
  21. package/dist/{message-handler.process-Dp5NQT05.js → message-handler.process-CN8bVDxj.js} +37 -45
  22. package/dist/{message-utils-Bx993JLN.js → message-utils-ConlUKCU.js} +1 -1
  23. package/dist/{outbound-adapter-CmN7ao1t.js → outbound-adapter-XuMiR77A.js} +6 -6
  24. package/dist/{pluralkit-SYmlmerw.js → pluralkit-o6s-EP9g.js} +4 -2
  25. package/dist/{probe-2MdGjUAf.js → probe-CxnDikWm.js} +5 -2
  26. package/dist/{probe.runtime-J927koKG.js → probe.runtime-DLFkSDVB.js} +1 -1
  27. package/dist/{provider-DrScDA1p.js → provider-4VG5CvC-.js} +98 -69
  28. package/dist/{provider-session.runtime-DXTzSYOJ.js → provider-session.runtime-ChdHgGCo.js} +3 -3
  29. package/dist/provider.runtime-B4QuZl_o.js +2 -0
  30. package/dist/{resolve-allowlist-common-B3p7cT8F.js → resolve-allowlist-common-BDpBb8dF.js} +1 -1
  31. package/dist/{resolve-channels-Rautpk8n.js → resolve-channels-DpM2v0Am.js} +3 -3
  32. package/dist/{resolve-users-Bw7vvtsi.js → resolve-users-Dl6np4pH.js} +3 -3
  33. package/dist/{runtime-C80YEJ7Z.js → runtime-CkdyyjTb.js} +24 -10
  34. package/dist/runtime-api.actions.js +2 -2
  35. package/dist/runtime-api.js +19 -19
  36. package/dist/runtime-api.lookup.js +5 -5
  37. package/dist/runtime-api.monitor-9pShEBWs.js +6 -0
  38. package/dist/runtime-api.monitor.js +4 -4
  39. package/dist/runtime-api.send.js +5 -5
  40. package/dist/runtime-api.threads.js +3 -3
  41. package/dist/{send-zGsXF-up.js → send-CIhsDMqs.js} +8 -5
  42. package/dist/{send.components-ktzrUTkt.js → send.components-DxoGyTkn.js} +4 -4
  43. package/dist/{send.outbound-C8oC51um.js → send.outbound-DaUyYuZa.js} +53 -10
  44. package/dist/{send.receipt-DsQWEQ2O.js → send.receipt-De_2iEWU.js} +2 -24
  45. package/dist/{send.shared-Dvo2ZCVG.js → send.shared-gtgBGDuV.js} +13 -5
  46. package/dist/session-binding-contract-api.js +1 -1
  47. package/dist/setup-plugin-api.js +1 -1
  48. package/dist/{subagent-hooks-kjrWDeDg.js → subagent-hooks-DPCipg2M.js} +2 -2
  49. package/dist/subagent-hooks-api.js +1 -1
  50. package/dist/{system-events-CvU3Aduf.js → system-events-4vmuyaBF.js} +1 -1
  51. package/dist/{target-resolver-DMPTzuo7.js → target-resolver-CVrOhQyC.js} +2 -2
  52. package/dist/targets-CRGgRKs7.js +3 -0
  53. package/dist/{thread-bindings-DO32M2kW.js → thread-bindings-D2SBj6F8.js} +4 -4
  54. package/dist/{thread-bindings.discord-api-304M1PMr.js → thread-bindings.discord-api-C7STOVXm.js} +4 -4
  55. package/dist/{thread-bindings.manager-C9YT7wF2.js → thread-bindings.manager-CN4MIGoJ.js} +3 -3
  56. package/dist/{transcripts-source-Chy2OrO_.js → transcripts-source-39NBdNeE.js} +1 -1
  57. package/dist/transcripts-source-api.js +1 -1
  58. package/dist/{typing-BaivbXIG.js → typing-CxIYS3vQ.js} +1 -1
  59. package/node_modules/undici/README.md +59 -18
  60. package/node_modules/undici/docs/docs/GettingStarted.md +278 -0
  61. package/node_modules/undici/docs/docs/api/Agent.md +3 -0
  62. package/node_modules/undici/docs/docs/api/BalancedPool.md +1 -1
  63. package/node_modules/undici/docs/docs/api/Client.md +44 -5
  64. package/node_modules/undici/docs/docs/api/Connector.md +1 -0
  65. package/node_modules/undici/docs/docs/api/Cookies.md +28 -1
  66. package/node_modules/undici/docs/docs/api/Dispatcher.md +22 -5
  67. package/node_modules/undici/docs/docs/api/EnvHttpProxyAgent.md +6 -9
  68. package/node_modules/undici/docs/docs/api/Errors.md +12 -0
  69. package/node_modules/undici/docs/docs/api/EventSource.md +50 -3
  70. package/node_modules/undici/docs/docs/api/Fetch.md +5 -3
  71. package/node_modules/undici/docs/docs/api/H2CClient.md +3 -3
  72. package/node_modules/undici/docs/docs/api/MockAgent.md +1 -1
  73. package/node_modules/undici/docs/docs/api/MockCallHistory.md +1 -1
  74. package/node_modules/undici/docs/docs/api/Pool.md +4 -1
  75. package/node_modules/undici/docs/docs/api/RedirectHandler.md +4 -1
  76. package/node_modules/undici/docs/docs/api/RetryAgent.md +3 -3
  77. package/node_modules/undici/docs/docs/api/RetryHandler.md +6 -6
  78. package/node_modules/undici/docs/docs/api/RoundRobinPool.md +1 -1
  79. package/node_modules/undici/docs/docs/api/SnapshotAgent.md +3 -3
  80. package/node_modules/undici/docs/docs/api/Socks5ProxyAgent.md +1 -0
  81. package/node_modules/undici/docs/docs/api/api-lifecycle.md +4 -4
  82. package/node_modules/undici/lib/core/connect.js +29 -4
  83. package/node_modules/undici/lib/core/util.js +8 -6
  84. package/node_modules/undici/lib/dispatcher/client-h1.js +69 -2
  85. package/node_modules/undici/lib/dispatcher/client-h2.js +160 -37
  86. package/node_modules/undici/lib/dispatcher/client.js +36 -7
  87. package/node_modules/undici/lib/dispatcher/dispatcher-base.js +1 -0
  88. package/node_modules/undici/lib/dispatcher/proxy-agent.js +2 -1
  89. package/node_modules/undici/lib/dispatcher/socks5-proxy-agent.js +4 -2
  90. package/node_modules/undici/lib/handler/redirect-handler.js +36 -11
  91. package/node_modules/undici/lib/interceptor/dns.js +4 -0
  92. package/node_modules/undici/lib/interceptor/redirect.js +3 -3
  93. package/node_modules/undici/lib/mock/mock-call-history.js +1 -1
  94. package/node_modules/undici/lib/mock/snapshot-agent.js +9 -1
  95. package/node_modules/undici/lib/util/cache.js +8 -2
  96. package/node_modules/undici/lib/web/cookies/parse.js +17 -25
  97. package/node_modules/undici/lib/web/eventsource/eventsource.js +7 -18
  98. package/node_modules/undici/lib/web/eventsource/util.js +32 -1
  99. package/node_modules/undici/lib/web/fetch/body.js +43 -0
  100. package/node_modules/undici/lib/web/fetch/index.js +17 -3
  101. package/node_modules/undici/lib/web/fetch/request.js +33 -3
  102. package/node_modules/undici/lib/web/websocket/receiver.js +20 -3
  103. package/node_modules/undici/lib/web/websocket/stream/websocketstream.js +8 -1
  104. package/node_modules/undici/lib/web/websocket/websocket.js +3 -1
  105. package/node_modules/undici/package.json +1 -1
  106. package/node_modules/undici/types/client.d.ts +5 -0
  107. package/node_modules/undici/types/connector.d.ts +1 -0
  108. package/node_modules/undici/types/fetch.d.ts +5 -1
  109. package/node_modules/undici/types/interceptors.d.ts +1 -1
  110. package/npm-shrinkwrap.json +7 -7
  111. package/package.json +5 -5
  112. package/dist/provider.runtime-nb-6cRoy.js +0 -2
  113. package/dist/runtime-api.monitor-D8KNDAd5.js +0 -6
  114. package/dist/targets-CKaNidbk.js +0 -3
@@ -1,7 +1,7 @@
1
- import { Ut as resolveDiscordChannelId, pt as getChannel, tt as createChannelWebhook } from "./send.receipt-DsQWEQ2O.js";
2
- import { I as createDiscordRestClient } from "./send.shared-Dvo2ZCVG.js";
3
- import { c as sendWebhookMessageDiscord, u as createThreadDiscord } from "./send-zGsXF-up.js";
4
- import { t as sendMessageDiscord } from "./send.outbound-C8oC51um.js";
1
+ import { Ut as resolveDiscordChannelId, pt as getChannel, tt as createChannelWebhook } from "./send.receipt-De_2iEWU.js";
2
+ import { I as createDiscordRestClient } from "./send.shared-gtgBGDuV.js";
3
+ import { c as sendWebhookMessageDiscord, u as createThreadDiscord } from "./send-CIhsDMqs.js";
4
+ import { t as sendMessageDiscord } from "./send.outbound-DaUyYuZa.js";
5
5
  import { M as toReusableWebhookKey, _ as rememberReusableWebhook, i as REUSABLE_WEBHOOKS_BY_ACCOUNT_CHANNEL, t as BINDINGS_BY_THREAD_ID } from "./thread-bindings.state-iSWjCYjB.js";
6
6
  import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
7
7
  import { ChannelType } from "discord-api-types/v10";
@@ -1,7 +1,7 @@
1
- import { Ut as resolveDiscordChannelId, Wt as __exportAll, pt as getChannel } from "./send.receipt-DsQWEQ2O.js";
2
- import { I as createDiscordRestClient } from "./send.shared-Dvo2ZCVG.js";
1
+ import { Ut as resolveDiscordChannelId, Wt as __exportAll, pt as getChannel } from "./send.receipt-De_2iEWU.js";
2
+ import { I as createDiscordRestClient } from "./send.shared-gtgBGDuV.js";
3
3
  import { C as resolveThreadBindingIdleTimeoutMs$1, D as saveBindingsToDisk, E as resolveThreadBindingMaxAgeMs$1, F as THREAD_BINDINGS_SWEEP_INTERVAL_MS, N as DEFAULT_THREAD_BINDING_IDLE_TIMEOUT_MS, O as setBindingRecord, S as resolveBindingRecordKey, T as resolveThreadBindingMaxAgeExpiresAt, b as resetThreadBindingsForTests, c as ensureBindingsLoaded, g as rememberRecentUnboundWebhookEcho, h as normalizeThreadId, k as shouldDefaultPersist, l as forgetThreadBindingToken, m as normalizeThreadBindingDurationMs, n as MANAGERS_BY_ACCOUNT_ID, p as normalizeTargetKind, r as PERSIST_BY_ACCOUNT_ID, s as THREAD_BINDING_TOUCH_PERSIST_MIN_INTERVAL_MS, t as BINDINGS_BY_THREAD_ID, u as getThreadBindingToken, v as rememberThreadBindingToken, w as resolveThreadBindingInactivityExpiresAt, x as resolveBindingIdsForSession, y as removeBindingRecord } from "./thread-bindings.state-iSWjCYjB.js";
4
- import { a as isThreadArchived, b as resolveThreadBindingThreadName, c as summarizeDiscordError, i as isDiscordThreadGoneError, n as createWebhookForChannel, o as maybeSendBindingMessage, r as findReusableWebhook, s as resolveChannelIdForBinding, t as createThreadForBinding, v as resolveThreadBindingFarewellText } from "./thread-bindings.discord-api-304M1PMr.js";
4
+ import { a as isThreadArchived, b as resolveThreadBindingThreadName, c as summarizeDiscordError, i as isDiscordThreadGoneError, n as createWebhookForChannel, o as maybeSendBindingMessage, r as findReusableWebhook, s as resolveChannelIdForBinding, t as createThreadForBinding, v as resolveThreadBindingFarewellText } from "./thread-bindings.discord-api-C7STOVXm.js";
5
5
  import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
6
6
  import { normalizeAccountId, resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
7
7
  import { getRuntimeConfigSnapshot } from "openclaw/plugin-sdk/runtime-config-snapshot";
@@ -1,4 +1,4 @@
1
- import { Wt as __exportAll } from "./send.receipt-DsQWEQ2O.js";
1
+ import { Wt as __exportAll } from "./send.receipt-De_2iEWU.js";
2
2
  //#region extensions/discord/src/voice/transcripts-source.ts
3
3
  var transcripts_source_exports = /* @__PURE__ */ __exportAll({
4
4
  discordVoiceTranscriptsSourceProvider: () => discordVoiceTranscriptsSourceProvider,
@@ -1,2 +1,2 @@
1
- import { t as discordVoiceTranscriptsSourceProvider } from "./transcripts-source-Chy2OrO_.js";
1
+ import { t as discordVoiceTranscriptsSourceProvider } from "./transcripts-source-39NBdNeE.js";
2
2
  export { discordVoiceTranscriptsSourceProvider };
@@ -1,4 +1,4 @@
1
- import { Wt as __exportAll, bt as sendChannelTyping } from "./send.receipt-DsQWEQ2O.js";
1
+ import { Wt as __exportAll, bt as sendChannelTyping } from "./send.receipt-De_2iEWU.js";
2
2
  import { l as raceWithTimeout } from "./timeouts-C5TBc_9x.js";
3
3
  //#region extensions/discord/src/monitor/typing.ts
4
4
  var typing_exports = /* @__PURE__ */ __exportAll({ sendTyping: () => sendTyping });
@@ -21,28 +21,65 @@ npm i undici
21
21
 
22
22
  ## Benchmarks
23
23
 
24
- The benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using a
25
- 50 TCP connections with a pipelining depth of 10 running on Node 22.11.0.
24
+ The benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using
25
+ 50 TCP connections with a pipelining depth of 10 running on Node 24.14.1.
26
+
27
+ ### HTTP/1.1
26
28
 
27
29
  ```
28
30
  ┌────────────────────────┬─────────┬────────────────────┬────────────┬─────────────────────────┐
29
31
  │ Tests │ Samples │ Result │ Tolerance │ Difference with slowest │
30
32
  ├────────────────────────┼─────────┼────────────────────┼────────────┼─────────────────────────┤
31
- │ 'axios' 15 │ '5708.26 req/sec' │ '± 2.91 %' │ '-' │
32
- │ 'http - no keepalive' 10 │ '5809.80 req/sec' │ '± 2.30 %' │ '+ 1.78 %'
33
- │ 'request' 30 │ '5828.80 req/sec' │ '± 2.91 %' │ '+ 2.11 %'
34
- │ 'undici - fetch' 40 │ '5903.78 req/sec' │ '± 2.87 %' │ '+ 3.43 %'
35
- │ 'node-fetch' 10 │ '5945.40 req/sec' │ '± 2.13 %' │ '+ 4.15 %'
36
- │ 'got' │ 35 │ '6511.45 req/sec' │ '± 2.84 %' │ '+ 14.07 %' │
37
- │ 'http - keepalive' 65 │ '9193.24 req/sec' │ '± 2.92 %' │ '+ 61.05 %' │
38
- │ 'superagent' 35 │ '9339.43 req/sec' │ '± 2.95 %' │ '+ 63.61 %' │
39
- │ 'undici - pipeline' │ 50 │ '13364.62 req/sec' │ '± 2.93 %' │ '+ 134.13 %' │
40
- │ 'undici - stream' 95 │ '18245.36 req/sec' │ '± 2.99 %' │ '+ 219.63 %' │
41
- │ 'undici - request' 50 │ '18340.17 req/sec' │ '± 2.84 %' │ '+ 221.29 %' │
42
- │ 'undici - dispatch' │ 40 │ '22234.42 req/sec' │ '± 2.94 %' │ '+ 289.51 %' │
33
+ │ 'node-fetch' 50 │ '4711.86 req/sec' │ '± 2.92 %' │ '-' │
34
+ │ 'undici - fetch' 75 │ '5438.50 req/sec' │ '± 2.97 %' │ '+ 15.42 %'
35
+ │ 'axios' 45 │ '5448.08 req/sec' │ '± 2.98 %' │ '+ 15.62 %'
36
+ │ 'request' 65 │ '5809.63 req/sec' │ '± 2.90 %' │ '+ 23.30 %'
37
+ │ 'http - no keepalive' 35 │ '5910.77 req/sec' │ '± 2.87 %' │ '+ 25.44 %'
38
+ │ 'got' │ 50 │ '6047.80 req/sec' │ '± 2.91 %' │ '+ 28.35 %' │
39
+ │ 'superagent' 60 │ '7534.53 req/sec' │ '± 2.97 %' │ '+ 59.91 %' │
40
+ │ 'http - keepalive' 75 │ '9343.41 req/sec' │ '± 2.90 %' │ '+ 98.30 %' │
41
+ │ 'undici - pipeline' │ 65 │ '13470.70 req/sec' │ '± 2.93 %' │ '+ 185.89 %' │
42
+ │ 'undici - request' 80 │ '16850.87 req/sec' │ '± 2.93 %' │ '+ 257.63 %' │
43
+ │ 'undici - stream' 101 │ '18488.56 req/sec' │ '± 3.81 %' │ '+ 292.38 %' │
44
+ │ 'undici - dispatch' │ 101 │ '20786.44 req/sec' │ '± 3.08 %' │ '+ 341.15 %' │
43
45
  └────────────────────────┴─────────┴────────────────────┴────────────┴─────────────────────────┘
44
46
  ```
45
47
 
48
+ ### HTTP/1.1 over HTTPS
49
+
50
+ Using [benchmark-https.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-https.js) against an h1-over-TLS server (50 connections, pipelining depth 10, Node 24.14.1).
51
+
52
+ ```
53
+ ┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
54
+ │ Tests │ Samples │ Result │ Tolerance │ Difference with slowest │
55
+ ├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
56
+ │ 'https - no keepalive'│ 10 │ '1358.40 req/sec' │ '± 1.99 %' │ '-' │
57
+ │ 'undici - fetch' │ 30 │ '3721.76 req/sec' │ '± 2.97 %' │ '+ 173.98 %' │
58
+ │ 'https - keepalive' │ 35 │ '5633.91 req/sec' │ '± 2.84 %' │ '+ 314.75 %' │
59
+ │ 'undici - pipeline' │ 15 │ '6254.05 req/sec' │ '± 2.80 %' │ '+ 360.40 %' │
60
+ │ 'undici - request' │ 25 │ '6669.80 req/sec' │ '± 2.73 %' │ '+ 391.01 %' │
61
+ │ 'undici - stream' │ 25 │ '7019.04 req/sec' │ '± 2.77 %' │ '+ 416.71 %' │
62
+ │ 'undici - dispatch' │ 20 │ '7361.85 req/sec' │ '± 2.90 %' │ '+ 441.95 %' │
63
+ └────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
64
+ ```
65
+
66
+ ### HTTP/2
67
+
68
+ Using [benchmark-http2.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-http2.js) against an h2 server (50 connections, pipelining depth 10, Node 24.14.1).
69
+
70
+ ```
71
+ ┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
72
+ │ Tests │ Samples │ Result │ Tolerance │ Difference with slowest │
73
+ ├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
74
+ │ 'undici - fetch' │ 45 │ '3499.03 req/sec' │ '± 2.93 %' │ '-' │
75
+ │ 'native - http2' │ 25 │ '4904.58 req/sec' │ '± 2.81 %' │ '+ 40.17 %' │
76
+ │ 'undici - pipeline' │ 60 │ '5836.82 req/sec' │ '± 2.99 %' │ '+ 66.81 %' │
77
+ │ 'undici - request' │ 65 │ '6831.25 req/sec' │ '± 2.83 %' │ '+ 95.23 %' │
78
+ │ 'undici - stream' │ 55 │ '6874.30 req/sec' │ '± 2.91 %' │ '+ 96.46 %' │
79
+ │ 'undici - dispatch' │ 55 │ '7791.23 req/sec' │ '± 2.96 %' │ '+ 122.67 %' │
80
+ └────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
81
+ ```
82
+
46
83
  ## Undici vs. Fetch
47
84
 
48
85
  ### Overview
@@ -340,6 +377,9 @@ The `body` mixins are the most common way to format the request/response body. M
340
377
  > [!NOTE]
341
378
  > The body returned from `undici.request` does not implement `.formData()`.
342
379
 
380
+ > [!WARNING]
381
+ > Calling `body.formData()` on a fetch response causes undici to buffer and parse the entire body. Since this is dictated by the spec, `body.formData()` must only be called on responses from trusted servers.
382
+
343
383
  Example usage:
344
384
 
345
385
  ```js
@@ -740,10 +780,11 @@ and `undici.Agent`) which will enable the family autoselection algorithm when es
740
780
  Undici aligns with the Node.js LTS schedule. The following table shows the supported versions:
741
781
 
742
782
  | Undici Version | Bundled in Node.js | Node.js Versions Supported | End of Life |
743
- |----------------|-------------------|----------------------------|-------------|
744
- | 5.x | 18.x | ≥14.0 (tested: 14, 16, 18) | 2024-04-30 |
745
- | 6.x | 20.x, 22.x | ≥18.17 (tested: 18, 20, 21, 22) | 2026-04-30 |
746
- | 7.x | 24.x | ≥20.18.1 (tested: 20, 22, 24) | 2027-04-30 |
783
+ |----------------|--------------------|----------------------------|-------------|
784
+ | 5.x | 18.x | ≥14.0 (tested: 14, 16, 18) | 2024-04-30 |
785
+ | 6.x | 20.x, 22.x | ≥18.17 (tested: 18, 20, 21, 22) | 2027-04-30 |
786
+ | 7.x | 24.x | ≥20.18.1 (tested: 20, 22, 24) | 2028-04-30 |
787
+ | 8.x | 26.x | ≥22.19.0 (tested: 22, 24, 26) | 2029-04-30 |
747
788
 
748
789
  ## License
749
790
 
@@ -0,0 +1,278 @@
1
+ # Getting Started
2
+
3
+ ## Installation
4
+
5
+ ```bash
6
+ npm install undici
7
+ ```
8
+
9
+ ## Fetch
10
+
11
+ The quickest way to get started is with `fetch`, which follows the
12
+ [Fetch Standard](https://fetch.spec.whatwg.org/) and works the same way as
13
+ the browser API:
14
+
15
+ ```js
16
+ import { fetch } from 'undici'
17
+
18
+ const res = await fetch('https://example.com')
19
+ const data = await res.json()
20
+ console.log(data)
21
+ ```
22
+
23
+ ### Using the Request object
24
+
25
+ undici also exports a `Request` class that follows the Fetch Standard:
26
+
27
+ ```js
28
+ import { fetch, Request } from 'undici'
29
+
30
+ const req = new Request('https://example.com', {
31
+ method: 'POST',
32
+ headers: { 'content-type': 'application/json' },
33
+ body: JSON.stringify({ hello: 'world' })
34
+ })
35
+ const res = await fetch(req)
36
+ console.log(res.status)
37
+ ```
38
+
39
+ ### Streaming the response
40
+
41
+ `res.body` is a web `ReadableStream`. Use `pipeline` from
42
+ `node:stream/promises` to stream it to a file:
43
+
44
+ ```js
45
+ import { fetch } from 'undici'
46
+ import { pipeline } from 'node:stream/promises'
47
+ import { createWriteStream } from 'node:fs'
48
+
49
+ const res = await fetch('https://example.com/large-file.zip')
50
+ await pipeline(res.body, createWriteStream('./file.zip'))
51
+ ```
52
+
53
+ > Always consume or cancel the response body. In Node.js, garbage collection
54
+ > is not aggressive enough to release connections promptly, so leaving a body
55
+ > unread can cause connection leaks and stalled requests. See
56
+ > [Specification Compliance - Garbage Collection](/docs/#garbage-collection)
57
+ > for details.
58
+
59
+ For more on `fetch`, see [API Reference: Fetch](/docs/docs/api/Fetch.md).
60
+
61
+ ## Dispatchers: Connection reuse and pooling
62
+
63
+ By default, `fetch`, `request`, `stream`, and `pipeline` create a new connection
64
+ for each call. For applications that make many requests to the same origin,
65
+ this is wasteful. undici provides **dispatchers** that manage connections
66
+ internally.
67
+
68
+ ### `Agent` — for requests to multiple origins
69
+
70
+ `Agent` is the most general-purpose dispatcher. It pools connections per-origin
71
+ and is the recommended default for most applications. Use it with
72
+ `setGlobalDispatcher` to affect all undici calls globally:
73
+
74
+ ```js
75
+ import { Agent, setGlobalDispatcher, fetch } from 'undici'
76
+
77
+ const agent = new Agent({
78
+ keepAliveTimeout: 30_000,
79
+ keepAliveMaxTimeout: 600_000
80
+ })
81
+ setGlobalDispatcher(agent)
82
+
83
+ // All subsequent fetch/request/stream/pipeline calls reuse connections
84
+ const res = await fetch('https://api.example.com/data')
85
+ ```
86
+
87
+ You can also pass a dispatcher per-request:
88
+
89
+ ```js
90
+ await fetch('https://api.example.com/data', { dispatcher: agent })
91
+ ```
92
+
93
+ ### `Pool` — for requests to a single origin
94
+
95
+ `Pool` manages a fixed set of connections to one origin. It gives you explicit
96
+ control over concurrency:
97
+
98
+ ```js
99
+ import { Pool, request } from 'undici'
100
+
101
+ const pool = new Pool('https://api.example.com', { connections: 10 })
102
+
103
+ const { body } = await request('https://api.example.com/data', {
104
+ dispatcher: pool
105
+ })
106
+ const data = await body.json()
107
+
108
+ pool.close()
109
+ ```
110
+
111
+ ### `Client` — for a single connection
112
+
113
+ `Client` maps to a single TCP connection. It supports pipelining (sending
114
+ multiple requests before responses arrive):
115
+
116
+ ```js
117
+ import { Client } from 'undici'
118
+
119
+ const client = new Client('https://api.example.com', {
120
+ pipelining: 5
121
+ })
122
+
123
+ const { body } = await client.request({ path: '/', method: 'GET' })
124
+ await body.dump()
125
+
126
+ client.close()
127
+ ```
128
+
129
+ For more on dispatcher options and lifecycle, see:
130
+ - [API Reference: Agent](/docs/docs/api/Agent.md)
131
+ - [API Reference: Pool](/docs/docs/api/Pool.md)
132
+ - [API Reference: Client](/docs/docs/api/Client.md)
133
+
134
+ ## Timeouts
135
+
136
+ undici applies timeouts at two levels:
137
+
138
+ - **`headersTimeout`** — time to wait for response headers (default: 300s).
139
+ - **`bodyTimeout`** — time between consecutive body chunks (default: 300s).
140
+
141
+ Set these on the dispatcher or per-request:
142
+
143
+ ```js
144
+ import { Agent, setGlobalDispatcher } from 'undici'
145
+
146
+ const agent = new Agent({
147
+ headersTimeout: 5_000,
148
+ bodyTimeout: 30_000
149
+ })
150
+
151
+ setGlobalDispatcher(agent)
152
+ ```
153
+
154
+ Timeout errors are thrown as `HeadersTimeoutError` and `BodyTimeoutError`.
155
+ See [API Reference: Errors](/docs/docs/api/Errors.md) for the full list.
156
+
157
+ ## Error handling
158
+
159
+ undici exposes structured errors via `error.code`:
160
+
161
+ ```js
162
+ import { request, errors } from 'undici'
163
+
164
+ try {
165
+ const { body } = await request('https://example.com')
166
+ await body.json()
167
+ } catch (err) {
168
+ switch (err.code) {
169
+ case 'UND_ERR_CONNECT_TIMEOUT':
170
+ console.error('Connection timed out')
171
+ break
172
+ case 'UND_ERR_HEADERS_TIMEOUT':
173
+ console.error('Headers timed out')
174
+ break
175
+ case 'UND_ERR_BODY_TIMEOUT':
176
+ console.error('Body timed out')
177
+ break
178
+ case 'UND_ERR_ABORTED':
179
+ console.error('Request was aborted')
180
+ break
181
+ default:
182
+ console.error(err)
183
+ }
184
+ }
185
+ ```
186
+
187
+ ### Aborting requests
188
+
189
+ ```js
190
+ import { request } from 'undici'
191
+
192
+ const ac = new AbortController()
193
+
194
+ setTimeout(() => ac.abort(), 1000)
195
+
196
+ try {
197
+ const { body } = await request('https://example.com', {
198
+ signal: ac.signal
199
+ })
200
+ await body.dump()
201
+ } catch (err) {
202
+ console.error(err.code) // UND_ERR_ABORTED
203
+ }
204
+ ```
205
+
206
+ ## Common patterns
207
+
208
+ ### Proxies
209
+
210
+ Use `ProxyAgent` for HTTP(S) proxies, or `EnvHttpProxyAgent` to pick up
211
+ proxy settings from environment variables:
212
+
213
+ ```js
214
+ import { ProxyAgent, setGlobalDispatcher } from 'undici'
215
+
216
+ const proxy = new ProxyAgent('http://proxy.internal:8080')
217
+ setGlobalDispatcher(proxy)
218
+ ```
219
+
220
+ See [Best Practices: Proxy](/docs/docs/best-practices/proxy.md) and
221
+ [API Reference: ProxyAgent](/docs/docs/api/ProxyAgent.md).
222
+
223
+ ### Mocking in tests
224
+
225
+ ```js
226
+ import { MockAgent, setGlobalDispatcher, request } from 'undici'
227
+
228
+ const mockAgent = new MockAgent()
229
+ setGlobalDispatcher(mockAgent)
230
+
231
+ const mockPool = mockAgent.get('https://api.example.com')
232
+ mockPool.intercept({ path: '/users' }).reply(200, [{ id: 1 }])
233
+
234
+ const { body } = await request('https://api.example.com/users')
235
+ console.log(await body.json())
236
+ ```
237
+
238
+ See [Best Practices: Mocking Request](/docs/docs/best-practices/mocking-request.md)
239
+ and [API Reference: MockAgent](/docs/docs/api/MockAgent.md).
240
+
241
+ ### Testing with undici
242
+
243
+ For test suites, set short keep-alive timeouts to avoid slow teardowns:
244
+
245
+ ```js
246
+ import { Agent, setGlobalDispatcher } from 'undici'
247
+
248
+ const agent = new Agent({
249
+ keepAliveTimeout: 10,
250
+ keepAliveMaxTimeout: 10
251
+ })
252
+ setGlobalDispatcher(agent)
253
+ ```
254
+
255
+ See [Best Practices: Writing Tests](/docs/docs/best-practices/writing-tests.md).
256
+
257
+ ### Customizing the global fetch
258
+
259
+ You can override Node.js's built-in globals with `install()`:
260
+
261
+ ```js
262
+ import { install } from 'undici'
263
+
264
+ install()
265
+
266
+ // Global fetch, Headers, Response, Request, and FormData
267
+ // now come from undici, not the Node.js bundle
268
+ const res = await fetch('https://example.com')
269
+ ```
270
+
271
+ See [API Reference: Global Installation](/docs/docs/api/GlobalInstallation.md).
272
+
273
+ ## Further reading
274
+
275
+ - [Undici vs. Built-in Fetch](/docs/docs/best-practices/undici-vs-builtin-fetch.md) —
276
+ when to install undici vs using Node.js built-in fetch
277
+ - [API Reference](/docs/docs/api/Dispatcher.md) — full dispatcher API documentation
278
+ - [Examples](/docs/examples/) — runnable code examples
@@ -21,6 +21,9 @@ Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
21
21
  * **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
22
22
  * **maxOrigins** `number` (optional) - Default: `Infinity` - Limits the total number of origins that can receive requests at a time, throwing an `MaxOriginsReachedError` error when attempting to dispatch when the max is reached. If `Infinity`, no limit is enforced.
23
23
 
24
+ > [!NOTE]
25
+ > Like `Pool`, `Agent` inherits all [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions). `allowH2` defaults to `true` and `maxConcurrentStreams` to `100`. The per-origin `Pool` it creates uses the default unlimited `connections`, so concurrent requests to the same origin land on separate `Client` instances and separate TCP/TLS sockets — HTTP/2 multiplexing on a shared session does not apply unless `connections` is set to a small value. See [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions).
26
+
24
27
  ## Instance Properties
25
28
 
26
29
  ### `Agent.closed`
@@ -34,7 +34,7 @@ Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
34
34
 
35
35
  Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
36
36
 
37
- ### `Pool.stats`
37
+ ### `BalancedPool.stats`
38
38
 
39
39
  Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
40
40
 
@@ -25,15 +25,18 @@ Returns: `Client`
25
25
  * **maxHeaderSize** `number | null` (optional) - Default: `--max-http-header-size` or `16384` - The maximum length of request headers in bytes. Defaults to Node.js' --max-http-header-size or 16KiB.
26
26
  * **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
27
27
  * **webSocket** `WebSocketOptions` (optional) - WebSocket-specific configuration options.
28
+ * **maxFragments** `number` (optional) - Default: `131072` - Maximum number of fragments in a message. Set to 0 to disable the limit.
28
29
  * **maxPayloadSize** `number` (optional) - Default: `134217728` (128 MB) - Maximum allowed payload size in bytes for WebSocket messages. Applied to uncompressed messages, compressed frame payloads, and decompressed (permessage-deflate) messages. Set to 0 to disable the limit.
29
- * **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections.
30
- * **connect** `ConnectOptions | Function | null` (optional) - Default: `null`.
30
+ * **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections. This option has no effect once HTTP/2 is negotiated — see `maxConcurrentStreams` for the h2 dispatch ceiling.
31
+ * **connect** `ConnectOptions | Function | null` (optional) - Default: `null` - Configures how undici establishes TCP/TLS connections. Accepts two forms:
32
+ * **Object (`ConnectOptions`)**: Options passed directly to the internal [`buildConnector()`](/docs/docs/api/Connector.md). This is the simplest way to customize TLS or socket behavior (e.g., setting `rejectUnauthorized`, `ca`, `socketPath`). See [`ConnectOptions`](#parameter-connectoptions) for available fields.
33
+ * **Function**: A custom connector with the signature `(options, callback)`, where `options` contains `{ hostname, host, protocol, port, servername, localAddress, httpSocket }` and `callback` follows `(error, socket)`. Useful when you need full control over socket creation, such as adding custom validation or proxy logic. When a function is provided, undici wraps it to automatically inject `socketPath` and `allowH2` into the `options` argument if those values are set on the client.
31
34
  * **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body. **Security Warning:** Disabling this option can expose your application to HTTP Request Smuggling attacks, where mismatched content-length headers cause servers and proxies to interpret request boundaries differently. This can lead to cache poisoning, credential hijacking, and bypassing security controls. Only disable this in controlled environments where you fully trust the request source.
32
35
  * **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.
33
36
  * **autoSelectFamilyAttemptTimeout**: `number` - Default: depends on local Node version, on Node 18.13.0 and above is `250`. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.
34
37
  * **allowH2**: `boolean` - Default: `true`. Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation.
35
38
  * **useH2c**: `boolean` - Default: `false`. Enforces h2c for non-https connections.
36
- * **maxConcurrentStreams**: `number` - Default: `100`. Dictates the maximum number of concurrent streams for a single H2 session. It can be overridden by a SETTINGS remote frame.
39
+ * **maxConcurrentStreams**: `number` - Default: `100`. The maximum number of concurrent HTTP/2 streams per session. When `allowH2` negotiates h2, this — not `pipelining` (which is HTTP/1.1 only, per [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2)) — is the ceiling the Client uses to dispatch in-flight requests on a shared session. The same value is advertised to the server as `peerMaxConcurrentStreams`, capping how many streams the server may push back. The initial value is replaced by the server's `SETTINGS_MAX_CONCURRENT_STREAMS` whenever the server sends one, so a user-supplied value acts as a pre-`SETTINGS` default rather than a hard cap.
37
40
  * **initialWindowSize**: `number` (optional) - Default: `262144` (256KB). Sets the HTTP/2 stream-level flow-control window size (SETTINGS_INITIAL_WINDOW_SIZE). Must be a positive integer greater than 0. This default is higher than Node.js core's default (65535 bytes) to improve throughput, Node's choice is very conservative for current high-bandwith networks. See [RFC 7540 Section 6.9.2](https://datatracker.ietf.org/doc/html/rfc7540#section-6.9.2) for more details.
38
41
  * **connectionWindowSize**: `number` (optional) - Default `524288` (512KB). Sets the HTTP/2 connection-level flow-control window size using `ClientHttp2Session.setLocalWindowSize()`. Must be a positive integer greater than 0. This provides better flow control for the entire connection across multiple streams. See [Node.js HTTP/2 documentation](https://nodejs.org/api/http2.html#clienthttp2sessionsetlocalwindowsize) for more details.
39
42
  * **pingInterval**: `number` - Default: `60e3`. The time interval in milliseconds between PING frames sent to the server. Set to `0` to disable PING frames. This is only applicable for HTTP/2 connections. This will emit a `ping` event on the client with the duration of the ping in milliseconds.
@@ -72,9 +75,43 @@ import { Client } from 'undici'
72
75
  const client = new Client('http://localhost:3000')
73
76
  ```
74
77
 
75
- ### Example - Custom connector
78
+ ### Example - Connect with TLS options (object form)
76
79
 
77
- This will allow you to perform some additional check on the socket that will be used for the next request.
80
+ Pass a `ConnectOptions` object to customize the TLS connection. The options are forwarded to the internal `buildConnector()`.
81
+
82
+ ```js
83
+ 'use strict'
84
+ import { Client } from 'undici'
85
+ import fs from 'node:fs'
86
+
87
+ const client = new Client('https://localhost:3000', {
88
+ connect: {
89
+ rejectUnauthorized: false,
90
+ ca: fs.readFileSync('./ca-cert.pem')
91
+ }
92
+ })
93
+ ```
94
+
95
+ ### Example - Connect via Unix domain socket
96
+
97
+ Use the `socketPath` option to connect through an IPC endpoint instead of a TCP connection.
98
+
99
+ ```js
100
+ 'use strict'
101
+ import { Client } from 'undici'
102
+
103
+ const client = new Client('http://localhost:3000', {
104
+ connect: {
105
+ socketPath: '/var/run/docker.sock'
106
+ }
107
+ })
108
+ ```
109
+
110
+ ### Example - Custom connector (function form)
111
+
112
+ Pass a function for full control over socket creation. This allows you to perform additional checks on the socket, use a proxy, or implement custom connection logic.
113
+
114
+ > **Note:** When a function is provided, undici wraps it to automatically inject `socketPath` and `allowH2` into the first argument (`options`) when those values are set on the client.
78
115
 
79
116
  ```js
80
117
  'use strict'
@@ -97,6 +134,8 @@ const client = new Client('https://localhost:3000', {
97
134
  })
98
135
  ```
99
136
 
137
+ For more details on building custom connectors, see [Connector](/docs/docs/api/Connector.md).
138
+
100
139
  ## Instance Methods
101
140
 
102
141
  ### `Client.close([callback])`
@@ -13,6 +13,7 @@ Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_opt
13
13
  Furthermore, the following options can be passed:
14
14
 
15
15
  * **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
16
+ * **preferH2** `boolean` (optional) - Default: `false` - Only effective together with `allowH2`. When `true`, ALPN is offered as `['h2', 'http/1.1']` (HTTP/2 first) instead of the default `['http/1.1', 'h2']`. Use this when the server selects the ALPN protocol by *client* preference (e.g. some load balancers) so that HTTP/2 is negotiated whenever the server supports it. If the server does not support HTTP/2, ALPN transparently falls back to `http/1.1`.
16
17
  * **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: `100`.
17
18
  * **timeout** `number | null` (optional) - In milliseconds. Default `10e3`.
18
19
  * **servername** `string | null` (optional)
@@ -10,7 +10,7 @@
10
10
  * **path** `string` (optional)
11
11
  * **secure** `boolean` (optional)
12
12
  * **httpOnly** `boolean` (optional)
13
- * **sameSite** `'String'|'Lax'|'None'` (optional)
13
+ * **sameSite** `'Strict'|'Lax'|'None'` (optional)
14
14
  * **unparsed** `string[]` (optional) Left over attributes that weren't parsed.
15
15
 
16
16
  ## `deleteCookie(headers, name[, attributes])`
@@ -80,6 +80,33 @@ Arguments:
80
80
 
81
81
  Returns: `Cookie[]`
82
82
 
83
+ ## `parseCookie(cookie)`
84
+
85
+ Parses a single `Set-Cookie` header value into a `Cookie` object.
86
+
87
+ ```js
88
+ import { parseCookie } from 'undici'
89
+
90
+ console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
91
+ // {
92
+ // name: 'undici',
93
+ // value: 'getSetCookies',
94
+ // secure: true,
95
+ // sameSite: 'Lax'
96
+ // }
97
+ ```
98
+
99
+ Notes:
100
+
101
+ * The cookie value is returned as it appears in the header. Percent-encoded sequences such as `%20` or `%0D%0A` are **not** decoded.
102
+ * `sameSite` is only set for exact case-insensitive matches of `Strict`, `Lax`, or `None`.
103
+
104
+ Arguments:
105
+
106
+ * **cookie** `string`
107
+
108
+ Returns: `Cookie | null`
109
+
83
110
  ## `setCookie(headers, cookie)`
84
111
 
85
112
  Appends a cookie to the `Set-Cookie` header.