@workerstack/clients 1.0.0-rc.28 → 1.0.0-rc.30

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 (368) hide show
  1. package/README.md +403 -21
  2. package/assets/installers/examples/github.config.ts +17 -19
  3. package/assets/installers/examples/goreleaser.config.ts +16 -18
  4. package/assets/installers/examples/raw.config.ts +13 -15
  5. package/bin/clients.js +87 -66
  6. package/bin/installgen.js +19 -10
  7. package/dist/cli.d.ts +4 -4
  8. package/dist/cli.js +18 -12
  9. package/dist/emit/cli/channels.d.ts +2 -2
  10. package/dist/emit/cli/channels.js +18 -13
  11. package/dist/emit/cli/commands.d.ts +1 -1
  12. package/dist/emit/cli/commands.js +39 -13
  13. package/dist/emit/cli/discovery.d.ts +0 -6
  14. package/dist/emit/cli/discovery.js +9 -7
  15. package/dist/emit/cli/flags.d.ts +1 -3
  16. package/dist/emit/cli/flags.js +18 -8
  17. package/dist/emit/cli/install.d.ts +0 -8
  18. package/dist/emit/cli/install.js +3 -3
  19. package/dist/emit/cli/layout.d.ts +1 -1
  20. package/dist/emit/cli/layout.js +13 -10
  21. package/dist/emit/cli/module.d.ts +6 -6
  22. package/dist/emit/cli/module.js +10 -10
  23. package/dist/emit/cli/release.d.ts +0 -11
  24. package/dist/emit/cli/release.js +4 -4
  25. package/dist/emit/cli/skills.js +8 -4
  26. package/dist/emit/csharp/errors.js +4 -4
  27. package/dist/emit/csharp/json.js +8 -8
  28. package/dist/emit/csharp/realtime.d.ts +1 -8
  29. package/dist/emit/csharp/realtime.js +26 -26
  30. package/dist/emit/csharp/sdk-answer.d.ts +10 -2
  31. package/dist/emit/csharp/sdk-answer.js +4 -4
  32. package/dist/emit/csharp/sdk-body.js +8 -6
  33. package/dist/emit/csharp/sdk-client.d.ts +3 -3
  34. package/dist/emit/csharp/sdk-client.js +2 -2
  35. package/dist/emit/csharp/sdk-csproj.d.ts +7 -9
  36. package/dist/emit/csharp/sdk-csproj.js +10 -10
  37. package/dist/emit/csharp/sdk-doc.js +1 -1
  38. package/dist/emit/csharp/sdk-method.d.ts +0 -1
  39. package/dist/emit/csharp/sdk-method.js +19 -8
  40. package/dist/emit/csharp/sdk-plan.js +0 -1
  41. package/dist/emit/csharp/sdk.js +3 -3
  42. package/dist/emit/csharp/sse.d.ts +0 -13
  43. package/dist/emit/csharp/sse.js +92 -11
  44. package/dist/emit/csharp/transport.js +9 -9
  45. package/dist/emit/csharp/types-enum.js +3 -1
  46. package/dist/emit/csharp/types-messages.d.ts +47 -0
  47. package/dist/emit/csharp/types-messages.js +172 -0
  48. package/dist/emit/csharp/types-names.js +13 -14
  49. package/dist/emit/csharp/types-record.js +3 -3
  50. package/dist/emit/csharp/types-union.d.ts +1 -1
  51. package/dist/emit/csharp/types.d.ts +0 -1
  52. package/dist/emit/csharp/types.js +3 -3
  53. package/dist/emit/csharp/ws.d.ts +0 -15
  54. package/dist/emit/csharp/ws.js +26 -5
  55. package/dist/emit/go/errors.js +1 -1
  56. package/dist/emit/go/http.js +2 -2
  57. package/dist/emit/go/module-path.js +2 -2
  58. package/dist/emit/go/sdk-answer.d.ts +24 -1
  59. package/dist/emit/go/sdk-answer.js +1 -1
  60. package/dist/emit/go/sdk-body.js +11 -7
  61. package/dist/emit/go/sdk-client.js +1 -1
  62. package/dist/emit/go/sdk-method.d.ts +3 -0
  63. package/dist/emit/go/sdk-method.js +18 -12
  64. package/dist/emit/go/sdk-mirror.js +2 -2
  65. package/dist/emit/go/sdk-opts.d.ts +0 -2
  66. package/dist/emit/go/sdk-opts.js +3 -3
  67. package/dist/emit/go/sdk.d.ts +1 -1
  68. package/dist/emit/go/sdk.js +9 -9
  69. package/dist/emit/go/sse.d.ts +2 -10
  70. package/dist/emit/go/sse.js +88 -13
  71. package/dist/emit/go/types-names.js +5 -0
  72. package/dist/emit/go/types-struct.d.ts +2 -1
  73. package/dist/emit/go/types-struct.js +1 -1
  74. package/dist/emit/go/types-union.d.ts +3 -2
  75. package/dist/emit/go/types-union.js +2 -0
  76. package/dist/emit/go/types.d.ts +6 -0
  77. package/dist/emit/go/types.js +20 -9
  78. package/dist/emit/go/ws.d.ts +4 -11
  79. package/dist/emit/go/ws.js +215 -59
  80. package/dist/emit/java/gradle.d.ts +7 -9
  81. package/dist/emit/java/gradle.js +8 -8
  82. package/dist/emit/java/json.d.ts +3 -0
  83. package/dist/emit/java/json.js +1 -1
  84. package/dist/emit/java/layout-ast.d.ts +4 -1
  85. package/dist/emit/java/layout-ast.js +1 -1
  86. package/dist/emit/java/layout-decl.js +5 -4
  87. package/dist/emit/java/layout-doc.js +13 -7
  88. package/dist/emit/java/layout-dot.js +1 -1
  89. package/dist/emit/java/layout-strings.js +4 -5
  90. package/dist/emit/java/layout-types.js +7 -5
  91. package/dist/emit/java/layout-visitor.js +4 -3
  92. package/dist/emit/java/layout.js +5 -4
  93. package/dist/emit/java/models-names.d.ts +2 -0
  94. package/dist/emit/java/models-names.js +6 -4
  95. package/dist/emit/java/models-record.d.ts +0 -1
  96. package/dist/emit/java/models-record.js +3 -3
  97. package/dist/emit/java/models-union.d.ts +13 -2
  98. package/dist/emit/java/models-union.js +12 -6
  99. package/dist/emit/java/models.d.ts +5 -1
  100. package/dist/emit/java/models.js +44 -20
  101. package/dist/emit/java/realtime.d.ts +34 -26
  102. package/dist/emit/java/realtime.js +45 -10
  103. package/dist/emit/java/sdk-client.d.ts +6 -6
  104. package/dist/emit/java/sdk-client.js +1 -1
  105. package/dist/emit/java/sdk-decl.js +2 -2
  106. package/dist/emit/java/sdk-errors.js +1 -1
  107. package/dist/emit/java/sdk-headers.js +2 -2
  108. package/dist/emit/java/sdk-mirror.js +7 -6
  109. package/dist/emit/java/sdk-models.d.ts +1 -1
  110. package/dist/emit/java/sdk-models.js +7 -7
  111. package/dist/emit/java/sdk-op.d.ts +1 -10
  112. package/dist/emit/java/sdk-op.js +9 -9
  113. package/dist/emit/java/sdk-params.d.ts +5 -5
  114. package/dist/emit/java/sdk-params.js +3 -2
  115. package/dist/emit/java/sdk-plan.js +0 -1
  116. package/dist/emit/java/sdk.d.ts +1 -1
  117. package/dist/emit/java/sdk.js +14 -13
  118. package/dist/emit/java/sse.d.ts +12 -13
  119. package/dist/emit/java/sse.js +105 -6
  120. package/dist/emit/java/ws.d.ts +48 -9
  121. package/dist/emit/java/ws.js +88 -4
  122. package/dist/emit/mcp/annotations.js +8 -4
  123. package/dist/emit/mcp/files.js +9 -9
  124. package/dist/emit/mcp/mounted.js +2 -2
  125. package/dist/emit/mcp/output-schema.d.ts +4 -2
  126. package/dist/emit/mcp/output-schema.js +58 -14
  127. package/dist/emit/mcp/registry.d.ts +0 -2
  128. package/dist/emit/mcp/registry.js +5 -4
  129. package/dist/emit/mcp/runtime.js +2 -2
  130. package/dist/emit/mcp/schema.js +22 -11
  131. package/dist/emit/mcp/server.d.ts +7 -7
  132. package/dist/emit/mcp/server.js +7 -6
  133. package/dist/emit/mcp/tools.js +7 -6
  134. package/dist/emit/python/errors.js +3 -3
  135. package/dist/emit/python/realtime.d.ts +9 -6
  136. package/dist/emit/python/realtime.js +22 -20
  137. package/dist/emit/python/sdk-answer.d.ts +8 -8
  138. package/dist/emit/python/sdk-answer.js +2 -2
  139. package/dist/emit/python/sdk-body.js +4 -5
  140. package/dist/emit/python/sdk-client.js +5 -5
  141. package/dist/emit/python/sdk-doc.js +2 -2
  142. package/dist/emit/python/sdk-method.d.ts +1 -1
  143. package/dist/emit/python/sdk-method.js +38 -11
  144. package/dist/emit/python/sdk-plan.js +0 -1
  145. package/dist/emit/python/sdk-pyproject.d.ts +0 -2
  146. package/dist/emit/python/sdk-pyproject.js +8 -8
  147. package/dist/emit/python/sdk.d.ts +1 -1
  148. package/dist/emit/python/sdk.js +28 -8
  149. package/dist/emit/python/sse.d.ts +0 -7
  150. package/dist/emit/python/sse.js +36 -6
  151. package/dist/emit/python/transport.js +4 -4
  152. package/dist/emit/python/types-dict.d.ts +2 -2
  153. package/dist/emit/python/types-dict.js +1 -1
  154. package/dist/emit/python/types-names.js +2 -2
  155. package/dist/emit/python/types-union.js +1 -1
  156. package/dist/emit/python/types.d.ts +7 -0
  157. package/dist/emit/python/types.js +23 -6
  158. package/dist/emit/python/ws.d.ts +21 -10
  159. package/dist/emit/python/ws.js +69 -3
  160. package/dist/emit/rust/errors.js +3 -3
  161. package/dist/emit/rust/http.js +4 -4
  162. package/dist/emit/rust/realtime.d.ts +7 -5
  163. package/dist/emit/rust/realtime.js +15 -18
  164. package/dist/emit/rust/sdk-body.js +8 -5
  165. package/dist/emit/rust/sdk-cargo.d.ts +16 -18
  166. package/dist/emit/rust/sdk-cargo.js +12 -12
  167. package/dist/emit/rust/sdk-client.d.ts +1 -1
  168. package/dist/emit/rust/sdk-client.js +3 -3
  169. package/dist/emit/rust/sdk-method.js +3 -3
  170. package/dist/emit/rust/sdk-opts.d.ts +2 -1
  171. package/dist/emit/rust/sdk-opts.js +2 -2
  172. package/dist/emit/rust/sdk-plan.js +0 -1
  173. package/dist/emit/rust/sdk.d.ts +1 -1
  174. package/dist/emit/rust/sdk.js +5 -5
  175. package/dist/emit/rust/sse.d.ts +11 -12
  176. package/dist/emit/rust/sse.js +54 -8
  177. package/dist/emit/rust/types-names.js +3 -3
  178. package/dist/emit/rust/types-struct.js +1 -1
  179. package/dist/emit/rust/types-union.d.ts +10 -2
  180. package/dist/emit/rust/types-union.js +4 -0
  181. package/dist/emit/rust/types.d.ts +9 -0
  182. package/dist/emit/rust/types.js +20 -12
  183. package/dist/emit/rust/ws.d.ts +22 -15
  184. package/dist/emit/rust/ws.js +60 -10
  185. package/dist/emit/shared/escape.js +17 -17
  186. package/dist/emit/shared/format.js +1 -1
  187. package/dist/emit/shared/gofmt.js +1 -1
  188. package/dist/emit/shared/lang.js +10 -10
  189. package/dist/emit/shared/literals.d.ts +5 -0
  190. package/dist/emit/shared/literals.js +8 -0
  191. package/dist/emit/shared/metadata.d.ts +0 -6
  192. package/dist/emit/shared/metadata.js +8 -7
  193. package/dist/emit/shared/ruff.js +1 -1
  194. package/dist/emit/shared/rustfmt.js +1 -1
  195. package/dist/emit/shared/type-emitter.js +37 -20
  196. package/dist/emit/shared/unknown-type.constants.d.ts +2 -0
  197. package/dist/emit/shared/unknown-type.constants.js +2 -0
  198. package/dist/emit/ts/http.d.ts +0 -2
  199. package/dist/emit/ts/http.js +4 -4
  200. package/dist/emit/ts/package.d.ts +14 -12
  201. package/dist/emit/ts/package.js +9 -8
  202. package/dist/emit/ts/route-tree.js +2 -2
  203. package/dist/emit/ts/sdk-types-preamble.d.ts +1 -1
  204. package/dist/emit/ts/sdk-types-preamble.js +6 -2
  205. package/dist/emit/ts/sdk-types.js +59 -20
  206. package/dist/emit/ts/sdk.js +6 -6
  207. package/dist/emit/ts/service-map.d.ts +10 -3
  208. package/dist/emit/ts/service-map.js +30 -2
  209. package/dist/emit/ts/tanstack-query.js +6 -6
  210. package/dist/emit/ts/type-gen.js +36 -21
  211. package/dist/emit/ts/webhooks.d.ts +0 -2
  212. package/dist/emit/ts/webhooks.js +3 -3
  213. package/dist/extract/chain.js +5 -4
  214. package/dist/extract/extract.js +5 -5
  215. package/dist/extract/serialize.d.ts +0 -2
  216. package/dist/extract/serialize.js +14 -15
  217. package/dist/extract/walk.js +15 -12
  218. package/dist/gen/args.js +9 -5
  219. package/dist/gen/formatters.js +5 -3
  220. package/dist/gen/shipped.js +2 -2
  221. package/dist/gen/targets.d.ts +2 -4
  222. package/dist/gen/targets.js +8 -4
  223. package/dist/gen/write.js +4 -2
  224. package/dist/index.js +2 -2
  225. package/dist/installers/cli.d.ts +4 -4
  226. package/dist/installers/cli.js +24 -24
  227. package/dist/installers/commands/build.d.ts +4 -4
  228. package/dist/installers/commands/build.js +2 -3
  229. package/dist/installers/commands/check.d.ts +2 -2
  230. package/dist/installers/commands/check.js +11 -10
  231. package/dist/installers/commands/init.d.ts +2 -2
  232. package/dist/installers/commands/init.js +1 -2
  233. package/dist/installers/config/define-config.d.ts +16 -16
  234. package/dist/installers/config/define-config.js +1 -1
  235. package/dist/installers/config/hooks/bun.d.ts +6 -6
  236. package/dist/installers/config/hooks/node.js +1 -1
  237. package/dist/installers/config/load.d.ts +6 -8
  238. package/dist/installers/config/load.js +7 -8
  239. package/dist/installers/config/resolve.d.ts +1 -2
  240. package/dist/installers/config/resolve.js +28 -33
  241. package/dist/installers/config/types.d.ts +6 -6
  242. package/dist/installers/config/types.js +0 -1
  243. package/dist/installers/render/quote.js +3 -5
  244. package/dist/installers/render/render.d.ts +6 -6
  245. package/dist/installers/render/render.js +26 -26
  246. package/dist/installers/ui.d.ts +4 -4
  247. package/dist/installers/ui.js +3 -3
  248. package/dist/ir/build.d.ts +3 -3
  249. package/dist/ir/build.js +12 -5
  250. package/dist/ir/load.js +9 -10
  251. package/dist/ir/model.d.ts +16 -1
  252. package/dist/ir/model.js +0 -1
  253. package/dist/ir/resolve-refs.js +2 -2
  254. package/dist/ir/resource-tree.js +2 -1
  255. package/dist/ir/route-tree-intern.js +1 -1
  256. package/dist/ir/schema.js +3 -3
  257. package/dist/ir/sdk-model.d.ts +25 -1
  258. package/dist/ir/sdk-model.js +38 -8
  259. package/dist/ir/slots.d.ts +1 -1
  260. package/dist/ir/slots.js +22 -11
  261. package/dist/ir/streams.d.ts +16 -0
  262. package/dist/ir/streams.js +40 -0
  263. package/dist/release/bootstrap.d.ts +3 -3
  264. package/dist/release/bootstrap.js +7 -7
  265. package/dist/release/bump-args.js +4 -4
  266. package/dist/release/bump-command.d.ts +1 -1
  267. package/dist/release/bump-command.js +9 -10
  268. package/dist/release/bump.d.ts +5 -4
  269. package/dist/release/bump.js +2 -2
  270. package/dist/release/cli.d.ts +4 -4
  271. package/dist/release/cli.js +4 -4
  272. package/dist/release/codegen.js +1 -1
  273. package/dist/release/digest.js +5 -7
  274. package/dist/release/git.js +5 -8
  275. package/dist/release/load.js +3 -3
  276. package/dist/release/manifest.js +9 -10
  277. package/dist/release/oasdiff.d.ts +10 -15
  278. package/dist/release/oasdiff.js +5 -6
  279. package/dist/release/registries.d.ts +0 -11
  280. package/dist/release/registries.js +17 -17
  281. package/dist/release/release-state.d.ts +16 -13
  282. package/dist/release/release-workflow.js +5 -7
  283. package/dist/release/repo-settings.d.ts +2 -1
  284. package/dist/release/spec-gate.d.ts +0 -2
  285. package/dist/release/spec-gate.js +6 -10
  286. package/dist/release/sync-command.d.ts +2 -2
  287. package/dist/release/sync-command.js +1 -1
  288. package/dist/release/sync-tree.js +9 -13
  289. package/dist/release/sync.d.ts +6 -6
  290. package/dist/release/sync.js +12 -13
  291. package/dist/release/types.d.ts +22 -22
  292. package/dist/release/types.js +0 -1
  293. package/dist/release/version-files.d.ts +3 -4
  294. package/dist/release/version-files.js +4 -5
  295. package/dist/runtime/.oxfmtrc.jsonc +8 -0
  296. package/dist/runtime/cli/socket.go +107 -13
  297. package/dist/runtime/cli/stream.go +18 -11
  298. package/dist/runtime/csharp/Adapters.cs +12 -11
  299. package/dist/runtime/csharp/Events.cs +22 -17
  300. package/dist/runtime/csharp/Realtime.cs +50 -23
  301. package/dist/runtime/csharp/RealtimeLoop.cs +1 -1
  302. package/dist/runtime/csharp/TransportSse.cs +3 -3
  303. package/dist/runtime/csharp/Ws.cs +1 -1
  304. package/dist/runtime/csharp/WsDial.cs +19 -1
  305. package/dist/runtime/csharp/WsTyped.cs +109 -0
  306. package/dist/runtime/go/realtime.go +125 -41
  307. package/dist/runtime/go/realtime_loop.go +21 -18
  308. package/dist/runtime/go/result.go +2 -1
  309. package/dist/runtime/go/sse.go +11 -0
  310. package/dist/runtime/go/stream.go +29 -13
  311. package/dist/runtime/go/transport.go +15 -21
  312. package/dist/runtime/go/transport_longpoll.go +3 -4
  313. package/dist/runtime/go/transport_sse.go +6 -6
  314. package/dist/runtime/go/ws.go +157 -61
  315. package/dist/runtime/java/EventStream.java +47 -29
  316. package/dist/runtime/java/Exchange.java +5 -5
  317. package/dist/runtime/java/Flight.java +3 -3
  318. package/dist/runtime/java/Realtime.java +45 -11
  319. package/dist/runtime/java/ResumableConnection.java +77 -32
  320. package/dist/runtime/java/Socket.java +8 -4
  321. package/dist/runtime/java/SseAdapter.java +1 -1
  322. package/dist/runtime/java/TypedWebSocket.java +81 -24
  323. package/dist/runtime/java/WsAdapter.java +4 -2
  324. package/dist/runtime/java/WsDial.java +12 -5
  325. package/dist/runtime/mcp/files.ts +1 -1
  326. package/dist/runtime/mcp/http.ts +6 -2
  327. package/dist/runtime/mcp/listen.ts +1 -1
  328. package/dist/runtime/mcp/mount.ts +2 -2
  329. package/dist/runtime/mcp/protocol.ts +1 -1
  330. package/dist/runtime/python/events.py +25 -11
  331. package/dist/runtime/python/operation.py +6 -1
  332. package/dist/runtime/python/realtime.py +47 -33
  333. package/dist/runtime/python/send_async.py +1 -0
  334. package/dist/runtime/python/transport_sse.py +2 -2
  335. package/dist/runtime/python/transport_ws.py +1 -1
  336. package/dist/runtime/python/ws.py +100 -39
  337. package/dist/runtime/rust/events.rs +64 -41
  338. package/dist/runtime/rust/realtime.rs +80 -34
  339. package/dist/runtime/rust/realtime_loop.rs +37 -12
  340. package/dist/runtime/rust/sse.rs +3 -2
  341. package/dist/runtime/rust/transport_sse.rs +1 -1
  342. package/dist/runtime/rust/transport_ws.rs +3 -2
  343. package/dist/runtime/rust/ws.rs +122 -50
  344. package/dist/runtime/ts/realtime-connection.ts +22 -0
  345. package/dist/runtime/ts/realtime-transports.ts +13 -4
  346. package/dist/runtime/ts/realtime.ts +27 -3
  347. package/dist/runtime/ts/sdk-realtime.ts +1 -1
  348. package/dist/runtime/ts/sdk-sse.ts +31 -14
  349. package/dist/runtime/ts/sdk-ws.ts +2 -1
  350. package/dist/runtime/ts/sdk.ts +9 -2
  351. package/dist/runtime/ts/sse.ts +8 -0
  352. package/dist/runtime/ts/ws.ts +88 -50
  353. package/dist/runtime/ts-tanstack-query/query.ts +0 -2
  354. package/package.json +12 -40
  355. package/dist/emit/cli/index.d.ts +0 -1
  356. package/dist/emit/cli/index.js +0 -1
  357. package/dist/emit/csharp/index.d.ts +0 -1
  358. package/dist/emit/csharp/index.js +0 -1
  359. package/dist/emit/go/index.d.ts +0 -1
  360. package/dist/emit/go/index.js +0 -1
  361. package/dist/emit/java/index.d.ts +0 -2
  362. package/dist/emit/java/index.js +0 -2
  363. package/dist/emit/mcp/index.d.ts +0 -3
  364. package/dist/emit/mcp/index.js +0 -3
  365. package/dist/emit/python/index.d.ts +0 -1
  366. package/dist/emit/python/index.js +0 -1
  367. package/dist/emit/rust/index.d.ts +0 -1
  368. package/dist/emit/rust/index.js +0 -1
@@ -1,16 +1,16 @@
1
1
  import { type Metadata, type PackageIdentity } from "../shared/metadata.ts";
2
2
  export type McpServerOptions = {
3
3
  /** the server's name: lowercase words joined by `-`, at most 60 characters; by default the document title's */
4
- readonly name?: string;
4
+ readonly name?: string | undefined;
5
5
  /** the prefix of its environment variables; by default the name's words, uppercased, joined by `_` */
6
- readonly envPrefix?: string;
6
+ readonly envPrefix?: string | undefined;
7
7
  /** the version its server info and package.json carry, one npm accepts; by default the document's */
8
- readonly version?: string;
8
+ readonly version?: string | undefined;
9
9
  /** the npm name it publishes under; `<name>-mcp` by default, the bin's name either way */
10
- readonly packageName?: string;
10
+ readonly packageName?: string | undefined;
11
11
  /** the MCP registry's name for it, `namespace/name` (`io.github.acme/shop`): package.json's `mcpName`, which the
12
12
  * registry checks the npm package by; none by default */
13
- readonly mcpName?: string;
13
+ readonly mcpName?: string | undefined;
14
14
  };
15
15
  export type GeneratedMcpServer = {
16
16
  readonly files: Readonly<Record<string, string>>;
@@ -21,8 +21,8 @@ export type GeneratedMcpServer = {
21
21
  };
22
22
  /** The options with their defaults filled, each refused unless it matches its grammar (F2). */
23
23
  export declare function resolved(options: McpServerOptions, title: string | undefined): {
24
- envPrefix: string;
25
- name: string;
24
+ readonly envPrefix: string;
25
+ readonly name: string;
26
26
  };
27
27
  /** `source` with its types erased, as ES module JavaScript; the entry gets the shebang a bin needs. */
28
28
  export declare function erased(path: string, source: string): string;
@@ -8,18 +8,18 @@
8
8
  */
9
9
  import { toIR } from "../../ir/build.js";
10
10
  import { binaryNameOf } from "../cli/module.js";
11
- import { checked, NPM_NAME, packageOn, SEMVER } from "../shared/metadata.js";
12
11
  import { tsString } from "../shared/escape.js";
12
+ import { checked, NPM_NAME, packageOn, SEMVER } from "../shared/metadata.js";
13
13
  import { compiled, npmFields } from "../ts/package.js";
14
14
  import { generateSdk } from "../ts/sdk.js";
15
15
  import { literal } from "./literal.js";
16
16
  import { serverJson } from "./registry.js";
17
17
  import { mcpRuntimeSource } from "./runtime.js";
18
18
  import { toolsOf, untoolable } from "./tools.js";
19
- /* a name leaves room for the bin's `-mcp`; a prefix is uppercase words joined by `_` */
19
+ // a name leaves room for the bin's `-mcp`; a prefix is uppercase words joined by `_`
20
20
  const NAME = /^(?=.{1,60}$)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
21
21
  const ENV_PREFIX = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/;
22
- /* a server name as the MCP registry's server.json schema (2025-12-11) takes it: a reverse-DNS namespace, `/`, a name */
22
+ // a server name as the MCP registry's server.json schema (2025-12-11) takes it: a reverse-DNS namespace, `/`, a name
23
23
  const MCP_NAME = /^(?=.{3,200}$)[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
24
24
  const MARKER = "// Code generated by clients. DO NOT EDIT.";
25
25
  /** The options with their defaults filled, each refused unless it matches its grammar (F2). */
@@ -34,7 +34,7 @@ export function resolved(options, title) {
34
34
  throw new Error(`Invalid version: ${JSON.stringify(options.version)}`);
35
35
  return { envPrefix, name };
36
36
  }
37
- /* a cap in bytes from the environment: a whole number, its default when unset */
37
+ // a cap in bytes from the environment: a whole number, its default when unset
38
38
  const BYTES = `const bytes = (name: string, fallback: string): number => {
39
39
  const text = process.env[name] || fallback
40
40
  if (/^(?:0|[1-9][0-9]{0,14})$/.test(text)) return Number(text)
@@ -215,13 +215,14 @@ export function generateMcpServer(document, options = {}, metadata = {}) {
215
215
  packageName: checked("packageName", options.packageName ?? `${name}-mcp`, NPM_NAME),
216
216
  };
217
217
  const version = options.version ?? ir.info.version ?? "0.0.0";
218
- /* what npm and the registries take: the version when it is semver, else 0.0.0 */
218
+ // what npm and the registries take: the version when it is semver, else 0.0.0
219
219
  const publishable = SEMVER.test(version) ? version : "0.0.0";
220
220
  const specs = toolsOf(ir);
221
- if (specs.length === 0)
221
+ if (specs.length === 0) {
222
222
  throw new Error(ir.operations.some((op) => op.extensions.mcp === true)
223
223
  ? "No operation marked x-mcp is one a tool can call yet: nothing to serve"
224
224
  : "No operation is marked x-mcp: nothing to serve");
225
+ }
225
226
  const files = specs.some((spec) => spec.parts?.some(([, , kind]) => kind !== "text"));
226
227
  const sdk = generateSdk(document, { name: "Api", stem: "api" });
227
228
  const source = {
@@ -44,7 +44,7 @@ export function untoolable(op) {
44
44
  export const isTool = (op) => op.extensions.mcp === true && untoolable(op) === undefined;
45
45
  /** The tool name for `id`, not one `taken` holds: snake case, sanitized, truncated, then suffixed. */
46
46
  export function toolName(id, taken) {
47
- /* snakeWords keeps only letters, digits and inner underscores: nothing is left to sanitize */
47
+ // snakeWords keeps only letters, digits and inner underscores: nothing is left to sanitize
48
48
  const base = (snakeWords(id) || "tool").slice(0, NAME_MAX);
49
49
  let name = base;
50
50
  for (let n = 2; taken.has(name); n++)
@@ -77,7 +77,7 @@ function bodyOf(op, ir, into) {
77
77
  const field = bodyField(op);
78
78
  if (field === undefined || op.body === undefined)
79
79
  return {};
80
- /* a multipart form is never a stream: it has its schema */
80
+ // a multipart form is never a stream: it has its schema
81
81
  if (field === "parts")
82
82
  return { parts: partsOf(op.body.schema, ir, into) };
83
83
  const property = into.scope.claim("body");
@@ -90,7 +90,7 @@ function bodyOf(op, ir, into) {
90
90
  function inputOf(op, ir, file) {
91
91
  const scope = new NameScope();
92
92
  const credentials = new Set([...CREDENTIAL_HEADERS, ir.auth.headerName.toLowerCase()]);
93
- /* null-prototype: a parameter named __proto__ is a property, never the object's prototype */
93
+ // null-prototype: a parameter named __proto__ is a property, never the object's prototype
94
94
  const properties = Object.create(null);
95
95
  const required = [];
96
96
  const args = [];
@@ -99,7 +99,7 @@ function inputOf(op, ir, file) {
99
99
  ["search", op.params.query],
100
100
  ["headers", op.params.header.filter((param) => !credentials.has(param.name.toLowerCase()))],
101
101
  ];
102
- for (const [group, params] of groups)
102
+ for (const [group, params] of groups) {
103
103
  for (const param of params) {
104
104
  const property = scope.claim(param.name);
105
105
  properties[property] = { ...jsonSchemaOf(param.schema, ir.schemas), ...describe(param.description) };
@@ -107,6 +107,7 @@ function inputOf(op, ir, file) {
107
107
  required.push(property);
108
108
  args.push([property, group, param.name]);
109
109
  }
110
+ }
110
111
  const body = bodyOf(op, ir, { file, properties, required, scope });
111
112
  let collect;
112
113
  if (op.extensions.sse === true) {
@@ -134,14 +135,14 @@ export function toolsOf(ir, file = FILE_SCHEMA) {
134
135
  const taken = new Set();
135
136
  return ir.operations.filter(isTool).map((op) => {
136
137
  const { args, body, collect, inputSchema } = inputOf(op, ir, file);
137
- /* the SDK model holds every operation of the IR */
138
+ // the SDK model holds every operation of the IR
138
139
  const sdkOp = model.opsById.get(op.id);
139
140
  const annotations = annotationsOf(sdkOp);
140
141
  return {
141
142
  name: toolName(op.id, taken),
142
143
  ...describe(op.description ?? op.summary),
143
144
  inputSchema,
144
- /* sdkMemberPaths holds every operation of the IR */
145
+ // sdkMemberPaths holds every operation of the IR
145
146
  member: members.get(op.id),
146
147
  args,
147
148
  ...body,
@@ -5,7 +5,7 @@ import { pyTopLevel } from "./types.js";
5
5
  /** The keys an error response's envelope names, over every operation's JSON error statuses (the runtime reads JSON only). */
6
6
  function envelopeKeys(model) {
7
7
  return model.ops.flatMap((op) => op.errorStatuses.flatMap((status) => {
8
- /* an error status is a declared response, and a schema comes with the content type it is under */
8
+ // an error status is a declared response, and a schema comes with the content type it is under
9
9
  const { contentType, schema } = op.ir.responses[String(status)];
10
10
  if (schema === undefined || !isJsonMedia(contentType))
11
11
  return [];
@@ -19,7 +19,7 @@ function envelopeKeys(model) {
19
19
  function declaredKeys(model) {
20
20
  const byId = [...model.ops].sort((a, b) => compareCodeUnits(a.id, b.id));
21
21
  const declared = byId.flatMap((op) => Object.entries(op.ir.extensions.errors ?? {}));
22
- /* a later entry wins: an envelope's key gives way to a declaration, each declaration reversed to its first */
22
+ // a later entry wins: an envelope's key gives way to a declaration, each declaration reversed to its first
23
23
  const keys = new Map([
24
24
  ...envelopeKeys(model).map((key) => [key, undefined]),
25
25
  ...declared.toReversed().map(([key, { schema }]) => [key, schema]),
@@ -50,7 +50,7 @@ export function pythonErrorKeys(model, at) {
50
50
  const members = new NameScope();
51
51
  const keys = declared.map(([wire, schema]) => ({
52
52
  data: bodyType(wire, schema, model, at),
53
- /* an UPPER_SNAKE member never meets a keyword, so the keyword guard's `_` goes */
53
+ // an UPPER_SNAKE member never meets a keyword, so the keyword guard's `_` goes
54
54
  member: members.claim(pyIdentifier(wire).replace(/_$/, "").toUpperCase()),
55
55
  wire,
56
56
  }));
@@ -1,10 +1,13 @@
1
1
  /**
2
- * A realtime operation's answer (contract 34 §2.0, §2.3; Fd3): `ResumableConnection[E]`, `E` the declared event
3
- * schema's type (`Any` for a string or absent one), opened by awaiting the method over WebSocket, else SSE, else
4
- * long-poll. Its five fields are the `TransportOpts` of their names: the resume cursor, the offered subprotocols
5
- * and the reconnect policy; a declared param on a resume channel is folded in, and one named like a policy field
6
- * is claimed as `…2` (`sdk-method.ts`).
2
+ * A realtime operation's answer (contract 34 §2.0, §2.3; Fd3): `ResumableConnection[Out, In]`, opened by awaiting the
3
+ * method over WebSocket, else SSE, else long-poll. `Out` is what the server sends (its declared `send`, else the
4
+ * declared event schema's type, `Any` for a string or absent one) and `In` what it receives (its `receive`, else
5
+ * `object`). A `send` union keyed on one field (D9) makes the answer `<Op>Connection`, a subclass hoisted beside the
6
+ * types whose `on` overloads give each member's value its member's type; a `message` member gets none. Its one field
7
+ * is `transport: TransportOpts | None`: the resume cursor, the offered subprotocols and the reconnect policy, which
8
+ * the connection advances in its own copy, so `rc.opts` resumes past the last message. A declared param on a resume
9
+ * channel is carried by it, and one named `transport` is claimed as `transport2` (`sdk-method.ts`).
7
10
  */
8
11
  import { type PyStream } from "./sdk-answer.ts";
9
- /** The realtime operation's answer, its five fields and its docstring's lines. */
12
+ /** The realtime operation's answer, its one field and its docstring's lines. */
10
13
  export declare const realtimeStream: PyStream;
@@ -1,21 +1,29 @@
1
1
  /**
2
- * A realtime operation's answer (contract 34 §2.0, §2.3; Fd3): `ResumableConnection[E]`, `E` the declared event
3
- * schema's type (`Any` for a string or absent one), opened by awaiting the method over WebSocket, else SSE, else
4
- * long-poll. Its five fields are the `TransportOpts` of their names: the resume cursor, the offered subprotocols
5
- * and the reconnect policy; a declared param on a resume channel is folded in, and one named like a policy field
6
- * is claimed as `…2` (`sdk-method.ts`).
2
+ * A realtime operation's answer (contract 34 §2.0, §2.3; Fd3): `ResumableConnection[Out, In]`, opened by awaiting the
3
+ * method over WebSocket, else SSE, else long-poll. `Out` is what the server sends (its declared `send`, else the
4
+ * declared event schema's type, `Any` for a string or absent one) and `In` what it receives (its `receive`, else
5
+ * `object`). A `send` union keyed on one field (D9) makes the answer `<Op>Connection`, a subclass hoisted beside the
6
+ * types whose `on` overloads give each member's value its member's type; a `message` member gets none. Its one field
7
+ * is `transport: TransportOpts | None`: the resume cursor, the offered subprotocols and the reconnect policy, which
8
+ * the connection advances in its own copy, so `rc.opts` resumes past the last message. A declared param on a resume
9
+ * channel is carried by it, and one named `transport` is claimed as `transport2` (`sdk-method.ts`).
7
10
  */
8
11
  import { eventType } from "./sdk-answer.js";
9
- import { isLastEventIdHeader, sseStream } from "./sse.js";
12
+ import { isLastEventIdHeader } from "./sse.js";
10
13
  import { pyTypeOf } from "./types.js";
11
- import { isReconnectToken, PROTOCOLS, RECONNECT_TOKEN } from "./ws.js";
12
- /** The realtime operation's answer, its five fields and its docstring's lines. */
14
+ import { isReconnectToken, socketAnswer } from "./ws.js";
15
+ /** The realtime operation's answer, its one field and its docstring's lines. */
13
16
  export const realtimeStream = {
14
- answer: (op, env) => {
15
- const events = eventType(op, env, () => pyTypeOf({ kind: "unknown" }, env.at));
16
- return { returns: `ResumableConnection[${events}]`, run: "realtime", type: events };
17
- },
18
- /* the WebSocket and long-poll dials send the cursor as query params, the SSE dial its id as Last-Event-ID */
17
+ answer: (op, env) => socketAnswer(op, env, {
18
+ base: "ResumableConnection",
19
+ in: "object",
20
+ // the one event a connection's `on` takes for itself
21
+ lifecycle: (out) => [["message", out]],
22
+ out: () => eventType(op, env, () => pyTypeOf({ kind: "unknown" }, env.at)),
23
+ run: "realtime",
24
+ suffix: "Connection",
25
+ }),
26
+ // the WebSocket and long-poll dials send the cursor as query params, the SSE dial its id as Last-Event-ID
19
27
  carries: (name, where) => isReconnectToken(name, where) ||
20
28
  (where === "query" && name === "last_event_id") ||
21
29
  isLastEventIdHeader(name, where),
@@ -23,11 +31,5 @@ export const realtimeStream = {
23
31
  "Opens the connection over WebSocket, else SSE, else long-poll; recv() reconnects after a drop and",
24
32
  "resumes after the last message it delivered.",
25
33
  ],
26
- fields: [
27
- ...sseStream.fields,
28
- RECONNECT_TOKEN,
29
- PROTOCOLS,
30
- "max_reconnect_attempts: int | None = None",
31
- "reconnect_delay_ms: int | None = None",
32
- ],
34
+ fields: ["transport: TransportOpts | None = None"],
33
35
  };
@@ -8,15 +8,20 @@
8
8
  import type { IRParam } from "../../ir/model.ts";
9
9
  import type { SdkOp } from "../../ir/sdk-model.ts";
10
10
  import type { MethodEnv } from "./sdk-method.ts";
11
+ import type { PythonCallPlan } from "./sdk-plan.ts";
11
12
  /** `schema`'s type at `<Op><field>`, written in the client module. */
12
13
  export declare const typeAt: (op: SdkOp, field: string, schema: IRParam["schema"], env: MethodEnv) => string;
13
14
  /** The body parameter's type: its schema's for JSON and a form, `<Op>Body` for multipart, `str` for text, bytes or chunks for binary. */
14
15
  export declare function bodyType(op: SdkOp, async: boolean, env: MethodEnv): string | null;
15
- /** What a method answers (its `Operation`'s type and its return type), and the transport call it makes. */
16
+ /**
17
+ * What a method answers (its `Operation`'s type and its return type), the transport call it makes, and the
18
+ * socket class the runtime builds for it, when it has its own.
19
+ */
16
20
  export type Answer = {
17
21
  readonly type: string;
18
22
  readonly returns: string;
19
23
  readonly run: string;
24
+ readonly kind?: string;
20
25
  };
21
26
  /**
22
27
  * What a streaming operation's method is: whether a declared param is one its own fields carry (Fd3), those
@@ -39,11 +44,6 @@ export declare function answerOf(op: SdkOp, env: MethodEnv): Answer;
39
44
  export declare function shapeOf(op: SdkOp, env: MethodEnv): string | null;
40
45
  /** `<Op>Headers` (total=False) hoisted beside the types, and how `Operation.headers` reads each; null without any. */
41
46
  export declare function responseHeaders(op: SdkOp, env: MethodEnv): {
42
- plan: {
43
- fields: {
44
- [k: string]: string;
45
- };
46
- type: string;
47
- };
48
- read: string[];
47
+ readonly plan: NonNullable<PythonCallPlan["responseHeaders"]>;
48
+ readonly read: string[];
49
49
  } | null;
@@ -75,14 +75,14 @@ export function responseHeaders(op, env) {
75
75
  const fields = headers.map((header) => {
76
76
  const resolved = env.at.names.resolve(header.schema);
77
77
  const at = { ...env.at, fieldName: header.name, parentName: type, typing };
78
- /* a scalar is read as its kind; any other schema as the header's text, which is what arrives */
78
+ // a scalar is read as its kind; any other schema as the header's text, which is what arrives
79
79
  const read = resolved.kind === "scalar" && resolved.type !== "null"
80
80
  ? { kind: resolved.type, type: pyTypeOf(header.schema, at) }
81
81
  : { kind: "string", type: "str" };
82
82
  return { header: header.name, key: scope.claim(pyIdentifier(header.name)), required: header.required, ...read };
83
83
  });
84
84
  typing.add("TypedDict");
85
- /* every key is an identifier (pyIdentifier), so the class form always spells it */
85
+ // every key is an identifier (pyIdentifier), so the class form always spells it
86
86
  env.at.decls.set(type, [`class ${type}(TypedDict, total=False):`, ...fields.map((f) => ` ${f.key}: ${f.type}`)].join("\n"));
87
87
  const read = fields.map(({ header, key, kind, required }) => `(${pyString(header)}, ${pyString(key)}, ${pyString(kind)}, ${required ? "True" : "False"})`);
88
88
  return { plan: { fields: Object.fromEntries(fields.map((f) => [f.header, f.key])), type }, read };
@@ -3,17 +3,16 @@ import { dictDecl } from "./types-dict.js";
3
3
  import { pyTypeOf } from "./types.js";
4
4
  /** The parts the body schema of `op` requires: none unless it is an object. */
5
5
  function requiredParts(op, env) {
6
- /* a multipart body, with file parts or text parts alone, is declared with its form's schema */
6
+ // a multipart body, with file parts or text parts alone, is declared with its form's schema
7
7
  const form = env.at.names.resolve(op.ir.body.schema);
8
8
  return new Set(form.kind === "object" ? form.fields.flatMap((f) => (f.required ? [f.name] : [])) : []);
9
9
  }
10
10
  /** The type of `part` as a key of `parent`: `FilePart` or its list for a file, its schema's type for text. */
11
11
  function partType(part, parent, env) {
12
- /* the IR gives every part its schema (ir/slots.ts partsOf, ir/sdk-model.ts bodyOf) */
12
+ // the IR gives every part its schema (ir/slots.ts partsOf, ir/sdk-model.ts bodyOf)
13
13
  const schema = part.schema;
14
- if (part.type === "text") {
14
+ if (part.type === "text")
15
15
  return pyTypeOf(schema, { ...env.at, fieldName: part.name, parentName: parent, typing: env.at.declTyping });
16
- }
17
16
  env.typesImports.add("FilePart");
18
17
  return env.at.names.resolve(schema).kind === "array" ? "list[FilePart]" : "FilePart";
19
18
  }
@@ -22,7 +21,7 @@ export function multipartBody(op, parts, env) {
22
21
  const name = env.at.names.hoist(`${op.id}.Body`, `${pyClassName(op.id)}Body`);
23
22
  if (env.at.decls.has(name))
24
23
  return name;
25
- /* claimed before its keys: what a text part hoists in turn comes after it */
24
+ // claimed before its keys: what a text part hoists in turn comes after it
26
25
  env.at.decls.set(name, "");
27
26
  const required = requiredParts(op, env);
28
27
  const keys = [...parts]
@@ -3,7 +3,7 @@ import { pyDocLines, pyString } from "../shared/escape.js";
3
3
  import { compareCodeUnits, NameScope, pyClassName, pyIdentifier } from "../shared/lang.js";
4
4
  import { MIRROR, mirrorNotice } from "../shared/mirror.js";
5
5
  import { BUILTINS, pyMethod } from "./sdk-method.js";
6
- /* the root clients' own members: no namespace or operation takes their names */
6
+ // the root clients' own members: no namespace or operation takes their names
7
7
  const ROOT_NAMES = ["close", "aclose", "is_stale", MIRROR];
8
8
  /**
9
9
  * `ns` at `path`: its children first, so a method never takes an attribute's name. A root member spelled `safe` is
@@ -37,7 +37,7 @@ const below = (node) => node.children.flatMap(({ node: child }) => [...below(chi
37
37
  */
38
38
  function classNames(root, env) {
39
39
  const base = (node) => (node === root ? "SDK" : `${node.path.map(pyClassName).join("")}Resource`);
40
- /* the normal classes first, so a twin never moves the name one of them had */
40
+ // the normal classes first, so a twin never moves the name one of them had
41
41
  const claimed = (nodes, prefix) => new Map(nodes.map((node) => {
42
42
  const sync = node === root || hasSync(node) ? env.at.names.claim(`${prefix}${base(node)}`) : undefined;
43
43
  const async = env.at.names.claim(`Async${prefix}${base(node)}`);
@@ -76,7 +76,7 @@ function methodBlocks(node, side) {
76
76
  }
77
77
  /** The class of `node` on `side`; a safe mirror's methods one line each, with no blank line between them. */
78
78
  function resourceClass(node, side) {
79
- const init = [" def __init__(self, transport: " + side.transport + ") -> None:", " self._t = transport"];
79
+ const init = [` def __init__(self, transport: ${side.transport}) -> None:`, " self._t = transport"];
80
80
  const methods = methodBlocks(node, side);
81
81
  return [
82
82
  `class ${side.name(node)}:`,
@@ -105,7 +105,7 @@ function rootClass(root, side, safe, doc) {
105
105
  [` ${a ? "async " : ""}def ${a}close(self) -> None:`, ` ${aw}self._t.${a}close()`],
106
106
  [` ${a ? "async " : ""}def __${a}enter__(self) -> Self:`, " return self"],
107
107
  [` ${a ? "async " : ""}def __${a}exit__(self, *exc: object) -> None:`, ` ${aw}self.${a}close()`],
108
- /* after the client's own methods: an operation named like a builtin shadows only what follows it */
108
+ // after the client's own methods: an operation named like a builtin shadows only what follows it
109
109
  ...methodBlocks(root, side),
110
110
  ];
111
111
  return [`class ${side.async ? "AsyncSDK" : "SDK"}:`, ` """${doc}"""`, "", ...members(own)];
@@ -153,7 +153,7 @@ export function clientDecls(ir, env) {
153
153
  ...nodes.map((node) => resourceClass(node, async)),
154
154
  rootClass(root, sync, safeSync, clientTitle(ir)),
155
155
  rootClass(root, async, safeAsync, clientTitle(ir)),
156
- /* after the classes they twin: each method line reads its normal class */
156
+ // after the classes they twin: each method line reads its normal class
157
157
  ...nodes.filter((node) => sync.name(node) !== undefined).map((node) => resourceClass(node, safeSync)),
158
158
  ...nodes.map((node) => resourceClass(node, safeAsync)),
159
159
  resourceClass(root, safeSync),
@@ -1,5 +1,5 @@
1
1
  import { pyDocLines } from "../shared/escape.js";
2
- /* the runtime's STATUS_ERRORS (runtime/python/errors.py); any other status raises APIStatusError */
2
+ // the runtime's STATUS_ERRORS (runtime/python/errors.py); any other status raises APIStatusError
3
3
  const STATUS_ERRORS = {
4
4
  400: "BadRequestError",
5
5
  401: "UnauthorizedError",
@@ -25,7 +25,7 @@ export function methodDoc(op, stream) {
25
25
  const lines = parts.flatMap((part, i) => (i === 0 ? part : ["", ...part]));
26
26
  if (lines.length === 0)
27
27
  return [];
28
- /* a docstring that opens on its Raises: block opens on a line of its own, so the block keeps its shape */
28
+ // a docstring that opens on its Raises: block opens on a line of its own, so the block keeps its shape
29
29
  const open = lines[0] === "Raises:" ? ['"""', ...lines] : [`"""${lines[0]}`, ...lines.slice(1)];
30
30
  const body = lines.length === 1 ? [`"""${lines[0]}"""`] : [...open, '"""'];
31
31
  return body.map((line) => (line === "" ? "" : ` ${line}`));
@@ -10,7 +10,7 @@ export type MethodEnv = {
10
10
  readonly constants: NameScope;
11
11
  /** the `collections.abc` and runtime names client.py imports */
12
12
  readonly imports: Set<string>;
13
- /** the runtime names types.py imports (a multipart body's `FilePart`) */
13
+ /** the runtime names types.py imports (a multipart body's `FilePart`, a named event's `SseEventOf`) */
14
14
  readonly typesImports: Set<string>;
15
15
  };
16
16
  /**
@@ -1,4 +1,4 @@
1
- import { mediaEssence } from "../../ir/sdk-model.js";
1
+ import { dispatchKey, isJsonEventData, mediaEssence, sseEvents, } from "../../ir/sdk-model.js";
2
2
  import { pyString } from "../shared/escape.js";
3
3
  import { compareCodeUnits, NameScope, pyIdentifier } from "../shared/lang.js";
4
4
  import { realtimeStream } from "./realtime.js";
@@ -6,23 +6,23 @@ import { answerOf, bodyType, responseHeaders, shapeOf, typeAt } from "./sdk-answ
6
6
  import { methodDoc } from "./sdk-doc.js";
7
7
  import { sseStream } from "./sse.js";
8
8
  import { wsStream } from "./ws.js";
9
- /* the builtins an annotation may spell that a method may be named: a method so named shadows it below */
9
+ // the builtins an annotation may spell that a method may be named: a method so named shadows it below
10
10
  export const BUILTINS = ["bool", "bytes", "dict", "float", "int", "list", "str", "tuple"];
11
11
  /**
12
12
  * `type` with each builtin `shadowed` names spelled `_builtins.<name>`; strings inside it kept. The module is
13
13
  * aliased because a method may be named `builtins`, and `pyIdentifier` never yields a leading `_`.
14
14
  */
15
15
  function qualified(type, shadowed, env) {
16
- return type.replace(/("(?:[^"\\]|\\.)*")|\b([a-z]+)\b/g, (whole, text, name) => {
16
+ return type.replaceAll(/("(?:[^"\\]|\\.)*")|\b([a-z]+)\b/g, (whole, text, name) => {
17
17
  if (text !== undefined || !shadowed.has(name))
18
18
  return whole;
19
19
  env.imports.add("builtins");
20
20
  return `_builtins.${name}`;
21
21
  });
22
22
  }
23
- /* the method's own names, a stream's fields among them: a parameter that takes one is claimed as `…2` */
23
+ // the method's own names, a stream's fields among them: a parameter that takes one is claimed as `…2`
24
24
  const METHOD_LOCALS = ["self", "body", "options", "idempotency_key", "headers_into"];
25
- /* each stream's answer, its own fields, and the declared params its resume channels carry (Fd3) */
25
+ // each stream's answer, its own fields, and the declared params its resume channels carry (Fd3)
26
26
  const STREAMS = {
27
27
  realtime: realtimeStream,
28
28
  sse: sseStream,
@@ -67,6 +67,28 @@ function acceptOf(op, kind) {
67
67
  return "text/event-stream";
68
68
  return kind === "text" || kind === "binary" ? mediaEssence(op.success.contentType) : null;
69
69
  }
70
+ /** The names of the events whose data is JSON, for an SSE op that names its events (D7); null for any other. */
71
+ function jsonEvents(op, env) {
72
+ const events = op.stream === "sse" ? sseEvents(op.ir) : undefined;
73
+ if (events === undefined)
74
+ return null;
75
+ return tuple(events.filter(({ data }) => isJsonEventData(data, env.at.names.resolve)).map(({ name }) => pyString(name)));
76
+ }
77
+ /**
78
+ * How a WebSocket or realtime op's runtime frames its messages: JSON-encode every send when it declares what the
79
+ * server receives, parse every frame when it declares what the server sends, and the key that parsed union
80
+ * dispatches on (D9).
81
+ */
82
+ function framing(op, env) {
83
+ const socket = op.stream === "ws" || op.stream === "realtime";
84
+ const { receive, send } = (socket ? op.ir.messages : undefined) ?? {};
85
+ const key = send === undefined ? undefined : dispatchKey(send, env.at.names.resolve);
86
+ return [
87
+ ["encode", receive === undefined ? null : "True"],
88
+ ["decode", send === undefined ? null : "True"],
89
+ ["dispatch", key === undefined ? null : pyString(key)],
90
+ ];
91
+ }
70
92
  /** The `Operation(…)` keywords that differ from its defaults, in its field order. */
71
93
  function namedArgs(parts, env) {
72
94
  const { answer, headers, op } = parts;
@@ -83,6 +105,9 @@ function namedArgs(parts, env) {
83
105
  ["invalidates", op.invalidates.length > 0 ? tuple(op.invalidates.map(pyString)) : null],
84
106
  ["stream", op.stream === null ? null : pyString(op.stream)],
85
107
  ["headers", headers === null ? null : tuple(headers.read)],
108
+ ["events", jsonEvents(op, env)],
109
+ ...framing(op, env),
110
+ ["kind", answer.kind ?? null],
86
111
  ];
87
112
  return named.flatMap(([key, value]) => (value === null ? [] : [`${key}=${value}`]));
88
113
  }
@@ -106,7 +131,7 @@ function methodLines(parts, async, env, shadowed) {
106
131
  const required = op.body?.required === true;
107
132
  const keyed = op.idempotent && op.stream === null;
108
133
  const own = op.stream === null ? [] : STREAMS[op.stream].fields;
109
- /* `name: type`, or `name: type = default`, its type qualified where an earlier method shadows a builtin */
134
+ // `name: type`, or `name: type = default`, its type qualified where an earlier method shadows a builtin
110
135
  const param = (text) => {
111
136
  const [name, rest] = [text.slice(0, text.indexOf(": ")), text.slice(text.indexOf(": ") + 2)];
112
137
  const unset = rest.endsWith(" = None");
@@ -144,13 +169,15 @@ function methodLines(parts, async, env, shadowed) {
144
169
  ` return ${async ? "await " : ""}self._t.${answer.run}(${args.join(", ")})`,
145
170
  ];
146
171
  }
147
- /** The runtime and `collections.abc` names `op`'s methods spell. */
148
- function noteImports(op, env) {
172
+ /** The runtime and `collections.abc` names `op`'s methods spell: none for a socket of its own class. */
173
+ function noteImports(op, answer, env) {
149
174
  const names = { realtime: "ResumableConnection", sse: "EventStream", ws: "TypedWebSocket" };
150
- if (op.stream !== null)
175
+ if (op.stream !== null && answer.kind === undefined)
151
176
  env.imports.add(names[op.stream]);
152
- if (op.stream === "ws" || op.stream === "realtime")
177
+ if (op.stream === "ws")
153
178
  env.imports.add("Sequence");
179
+ if (op.stream === "realtime")
180
+ env.imports.add("TransportOpts");
154
181
  }
155
182
  /** The method of `op` named `name`: its constant, its sync method (none for a stream), its async one, its plan. */
156
183
  export function pyMethod(op, name, env) {
@@ -160,7 +187,7 @@ export function pyMethod(op, name, env) {
160
187
  const answer = op.stream === null ? answerOf(op, env) : STREAMS[op.stream].answer(op, env);
161
188
  const constant = env.constants.claim(`_${pyIdentifier(op.id).toUpperCase()}`);
162
189
  const parts = { answer, constant, headers: responseHeaders(op, env), keywords, name, op, path };
163
- noteImports(op, env);
190
+ noteImports(op, answer, env);
164
191
  env.imports.add("Operation").add("RequestOptions");
165
192
  const by = (where) => Object.fromEntries(keywords.filter((k) => k.where === where).map(({ ident, param }) => [param.name, ident]));
166
193
  const plan = {
@@ -1 +0,0 @@
1
- export {};
@@ -14,8 +14,6 @@ export declare const PYTHON_REQUIRES = ">=3.11";
14
14
  export declare const PYTHON_CLASSIFIERS: readonly string[];
15
15
  /** The lowest httpx2 every emitted package accepts. */
16
16
  export declare const HTTPX2_FLOOR = "2.12.0";
17
- /** The dependency string every emitted package declares (`httpx2[ws]` when it needs WebSockets). */
18
- export declare const HTTPX2 = "httpx2>=2.12.0,<3";
19
17
  /** `name` when it is an import name a package may take: lower snake case, no keyword, not the runtime's. */
20
18
  export declare function validatePackageName(name: string): string;
21
19
  /** `version` when it is in PEP 440's release, pre, post and dev subset. */
@@ -20,26 +20,24 @@ export const PYTHON_CLASSIFIERS = [
20
20
  "Programming Language :: Python :: 3.14",
21
21
  "Typing :: Typed",
22
22
  ];
23
- /* clients' own record of what it wrote (gen/write.ts MANIFEST), which no sdist ships */
23
+ // clients' own record of what it wrote (gen/write.ts MANIFEST), which no sdist ships
24
24
  const MANIFEST = ".clients-generated.json";
25
25
  /** The lowest httpx2 every emitted package accepts. */
26
26
  export const HTTPX2_FLOOR = "2.12.0";
27
27
  /** The dependency string every emitted package declares (`httpx2[ws]` when it needs WebSockets). */
28
- export const HTTPX2 = `httpx2>=${HTTPX2_FLOOR},<3`;
29
- /* the hard keywords and the soft ones, none an import name */
28
+ const HTTPX2 = `httpx2>=${HTTPX2_FLOOR},<3`;
29
+ // the hard keywords and the soft ones, none an import name
30
30
  const KEYWORDS = " False None True and as assert async await break class continue def del elif else except finally for from global if import in is lambda nonlocal not or pass raise return try while with yield match case type _ ";
31
31
  /** `name` when it is an import name a package may take: lower snake case, no keyword, not the runtime's. */
32
32
  export function validatePackageName(name) {
33
- if (!/^[a-z][a-z0-9_]*$/.test(name) || KEYWORDS.includes(` ${name} `) || name === "_http") {
33
+ if (!/^[a-z][a-z0-9_]*$/.test(name) || KEYWORDS.includes(` ${name} `) || name === "_http")
34
34
  throw new Error(`Invalid package name: "${name}"`);
35
- }
36
35
  return name;
37
36
  }
38
37
  /** `version` when it is in PEP 440's release, pre, post and dev subset. */
39
38
  export function validateVersion(version) {
40
- if (!/^\d+(\.\d+)*((a|b|rc)\d+)?(\.post\d+)?(\.dev\d+)?$/.test(version)) {
39
+ if (!/^\d+(\.\d+)*((a|b|rc)\d+)?(\.post\d+)?(\.dev\d+)?$/.test(version))
41
40
  throw new Error(`Invalid version: "${version}"`);
42
- }
43
41
  return version;
44
42
  }
45
43
  /** A TOML basic string of `text`. */
@@ -74,7 +72,9 @@ function urls(metadata) {
74
72
  ["Documentation", documentation],
75
73
  ["Changelog", changelog],
76
74
  ].filter((entry) => entry[1] !== undefined);
77
- return labeled.length === 0 ? [] : ["[project.urls]", ...labeled.map(([label, url]) => `${label} = ${toml(url)}`), ""];
75
+ return labeled.length === 0
76
+ ? []
77
+ : ["[project.urls]", ...labeled.map(([label, url]) => `${label} = ${toml(url)}`), ""];
78
78
  }
79
79
  /** The manifest of package `pkg` (its import name; the distribution name has `-` for `_`). */
80
80
  export function pyproject(pkg, ws, metadata = {}) {
@@ -1,5 +1,5 @@
1
- import type { PythonCallPlan } from "./sdk-plan.ts";
2
1
  import { type Metadata, type PackageIdentity } from "../shared/metadata.ts";
2
+ import type { PythonCallPlan } from "./sdk-plan.ts";
3
3
  export type PythonSdkOptions = {
4
4
  /** the import name; `http_sdk` by default, its distribution name with `-` for `_` */
5
5
  readonly packageName?: string;