@workerstack/clients 0.0.0-stage → 1.0.0-rc.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +619 -2
- package/bin/honey-clients.js +94 -0
- package/dist/cli.d.ts +102 -0
- package/dist/cli.js +190 -0
- package/dist/emit/cli/channels.d.ts +73 -0
- package/dist/emit/cli/channels.js +197 -0
- package/dist/emit/cli/commands.d.ts +27 -0
- package/dist/emit/cli/commands.js +187 -0
- package/dist/emit/cli/discovery.d.ts +35 -0
- package/dist/emit/cli/discovery.js +202 -0
- package/dist/emit/cli/flags.d.ts +59 -0
- package/dist/emit/cli/flags.js +186 -0
- package/dist/emit/cli/index.d.ts +1 -0
- package/dist/emit/cli/index.js +1 -0
- package/dist/emit/cli/install.d.ts +37 -0
- package/dist/emit/cli/install.js +88 -0
- package/dist/emit/cli/layout.d.ts +23 -0
- package/dist/emit/cli/layout.js +118 -0
- package/dist/emit/cli/module.d.ts +30 -0
- package/dist/emit/cli/module.js +186 -0
- package/dist/emit/cli/release.d.ts +40 -0
- package/dist/emit/cli/release.js +183 -0
- package/dist/emit/cli/skills.d.ts +11 -0
- package/dist/emit/cli/skills.js +56 -0
- package/dist/emit/csharp/errors.d.ts +7 -0
- package/dist/emit/csharp/errors.js +69 -0
- package/dist/emit/csharp/index.d.ts +1 -0
- package/dist/emit/csharp/index.js +1 -0
- package/dist/emit/csharp/json.d.ts +13 -0
- package/dist/emit/csharp/json.js +113 -0
- package/dist/emit/csharp/realtime.d.ts +10 -0
- package/dist/emit/csharp/realtime.js +33 -0
- package/dist/emit/csharp/sdk-answer.d.ts +48 -0
- package/dist/emit/csharp/sdk-answer.js +85 -0
- package/dist/emit/csharp/sdk-body.d.ts +10 -0
- package/dist/emit/csharp/sdk-body.js +87 -0
- package/dist/emit/csharp/sdk-client.d.ts +32 -0
- package/dist/emit/csharp/sdk-client.js +177 -0
- package/dist/emit/csharp/sdk-csproj.d.ts +36 -0
- package/dist/emit/csharp/sdk-csproj.js +136 -0
- package/dist/emit/csharp/sdk-doc.d.ts +12 -0
- package/dist/emit/csharp/sdk-doc.js +35 -0
- package/dist/emit/csharp/sdk-method.d.ts +26 -0
- package/dist/emit/csharp/sdk-method.js +187 -0
- package/dist/emit/csharp/sdk-plan.d.ts +38 -0
- package/dist/emit/csharp/sdk-plan.js +1 -0
- package/dist/emit/csharp/sdk.d.ts +40 -0
- package/dist/emit/csharp/sdk.js +105 -0
- package/dist/emit/csharp/sse.d.ts +18 -0
- package/dist/emit/csharp/sse.js +29 -0
- package/dist/emit/csharp/transport.d.ts +11 -0
- package/dist/emit/csharp/transport.js +67 -0
- package/dist/emit/csharp/types-enum.d.ts +19 -0
- package/dist/emit/csharp/types-enum.js +63 -0
- package/dist/emit/csharp/types-names.d.ts +33 -0
- package/dist/emit/csharp/types-names.js +182 -0
- package/dist/emit/csharp/types-record.d.ts +25 -0
- package/dist/emit/csharp/types-record.js +65 -0
- package/dist/emit/csharp/types-union.d.ts +27 -0
- package/dist/emit/csharp/types-union.js +113 -0
- package/dist/emit/csharp/types.d.ts +36 -0
- package/dist/emit/csharp/types.js +126 -0
- package/dist/emit/csharp/ws.d.ts +20 -0
- package/dist/emit/csharp/ws.js +14 -0
- package/dist/emit/go/errors.d.ts +7 -0
- package/dist/emit/go/errors.js +44 -0
- package/dist/emit/go/http.d.ts +11 -0
- package/dist/emit/go/http.js +50 -0
- package/dist/emit/go/index.d.ts +1 -0
- package/dist/emit/go/index.js +1 -0
- package/dist/emit/go/module-path.d.ts +2 -0
- package/dist/emit/go/module-path.js +27 -0
- package/dist/emit/go/sdk-answer.d.ts +28 -0
- package/dist/emit/go/sdk-answer.js +41 -0
- package/dist/emit/go/sdk-body.d.ts +24 -0
- package/dist/emit/go/sdk-body.js +76 -0
- package/dist/emit/go/sdk-client.d.ts +29 -0
- package/dist/emit/go/sdk-client.js +141 -0
- package/dist/emit/go/sdk-method.d.ts +68 -0
- package/dist/emit/go/sdk-method.js +172 -0
- package/dist/emit/go/sdk-mirror.d.ts +23 -0
- package/dist/emit/go/sdk-mirror.js +97 -0
- package/dist/emit/go/sdk-opts.d.ts +55 -0
- package/dist/emit/go/sdk-opts.js +100 -0
- package/dist/emit/go/sdk.d.ts +26 -0
- package/dist/emit/go/sdk.js +111 -0
- package/dist/emit/go/sse.d.ts +16 -0
- package/dist/emit/go/sse.js +26 -0
- package/dist/emit/go/types-codec.d.ts +15 -0
- package/dist/emit/go/types-codec.js +171 -0
- package/dist/emit/go/types-names.d.ts +14 -0
- package/dist/emit/go/types-names.js +64 -0
- package/dist/emit/go/types-struct.d.ts +29 -0
- package/dist/emit/go/types-struct.js +65 -0
- package/dist/emit/go/types-union.d.ts +17 -0
- package/dist/emit/go/types-union.js +84 -0
- package/dist/emit/go/types.d.ts +32 -0
- package/dist/emit/go/types.js +177 -0
- package/dist/emit/go/ws.d.ts +12 -0
- package/dist/emit/go/ws.js +70 -0
- package/dist/emit/java/gradle.d.ts +57 -0
- package/dist/emit/java/gradle.js +221 -0
- package/dist/emit/java/index.d.ts +2 -0
- package/dist/emit/java/index.js +2 -0
- package/dist/emit/java/json.d.ts +13 -0
- package/dist/emit/java/json.js +84 -0
- package/dist/emit/java/layout-ast.d.ts +146 -0
- package/dist/emit/java/layout-ast.js +102 -0
- package/dist/emit/java/layout-decl.d.ts +20 -0
- package/dist/emit/java/layout-decl.js +155 -0
- package/dist/emit/java/layout-doc.d.ts +55 -0
- package/dist/emit/java/layout-doc.js +166 -0
- package/dist/emit/java/layout-dot.d.ts +18 -0
- package/dist/emit/java/layout-dot.js +127 -0
- package/dist/emit/java/layout-strings.d.ts +8 -0
- package/dist/emit/java/layout-strings.js +76 -0
- package/dist/emit/java/layout-types.d.ts +11 -0
- package/dist/emit/java/layout-types.js +95 -0
- package/dist/emit/java/layout-visitor.d.ts +38 -0
- package/dist/emit/java/layout-visitor.js +232 -0
- package/dist/emit/java/layout.d.ts +61 -0
- package/dist/emit/java/layout.js +121 -0
- package/dist/emit/java/models-enum.d.ts +17 -0
- package/dist/emit/java/models-enum.js +51 -0
- package/dist/emit/java/models-names.d.ts +29 -0
- package/dist/emit/java/models-names.js +97 -0
- package/dist/emit/java/models-record.d.ts +24 -0
- package/dist/emit/java/models-record.js +79 -0
- package/dist/emit/java/models-union.d.ts +27 -0
- package/dist/emit/java/models-union.js +86 -0
- package/dist/emit/java/models.d.ts +28 -0
- package/dist/emit/java/models.js +118 -0
- package/dist/emit/java/realtime.d.ts +50 -0
- package/dist/emit/java/realtime.js +69 -0
- package/dist/emit/java/sdk-client.d.ts +66 -0
- package/dist/emit/java/sdk-client.js +207 -0
- package/dist/emit/java/sdk-decl.d.ts +11 -0
- package/dist/emit/java/sdk-decl.js +63 -0
- package/dist/emit/java/sdk-errors.d.ts +13 -0
- package/dist/emit/java/sdk-errors.js +141 -0
- package/dist/emit/java/sdk-headers.d.ts +12 -0
- package/dist/emit/java/sdk-headers.js +74 -0
- package/dist/emit/java/sdk-mirror.d.ts +14 -0
- package/dist/emit/java/sdk-mirror.js +107 -0
- package/dist/emit/java/sdk-models.d.ts +16 -0
- package/dist/emit/java/sdk-models.js +68 -0
- package/dist/emit/java/sdk-op.d.ts +57 -0
- package/dist/emit/java/sdk-op.js +216 -0
- package/dist/emit/java/sdk-params.d.ts +38 -0
- package/dist/emit/java/sdk-params.js +133 -0
- package/dist/emit/java/sdk-plan.d.ts +52 -0
- package/dist/emit/java/sdk-plan.js +1 -0
- package/dist/emit/java/sdk-record.d.ts +16 -0
- package/dist/emit/java/sdk-record.js +99 -0
- package/dist/emit/java/sdk.d.ts +49 -0
- package/dist/emit/java/sdk.js +216 -0
- package/dist/emit/java/sse.d.ts +35 -0
- package/dist/emit/java/sse.js +57 -0
- package/dist/emit/java/ws.d.ts +27 -0
- package/dist/emit/java/ws.js +31 -0
- package/dist/emit/mcp/annotations.d.ts +15 -0
- package/dist/emit/mcp/annotations.js +15 -0
- package/dist/emit/mcp/files.d.ts +18 -0
- package/dist/emit/mcp/files.js +42 -0
- package/dist/emit/mcp/index.d.ts +3 -0
- package/dist/emit/mcp/index.js +3 -0
- package/dist/emit/mcp/literal.d.ts +2 -0
- package/dist/emit/mcp/literal.js +33 -0
- package/dist/emit/mcp/mounted.d.ts +21 -0
- package/dist/emit/mcp/mounted.js +89 -0
- package/dist/emit/mcp/output-schema.d.ts +18 -0
- package/dist/emit/mcp/output-schema.js +38 -0
- package/dist/emit/mcp/registry.d.ts +23 -0
- package/dist/emit/mcp/registry.js +83 -0
- package/dist/emit/mcp/runtime.d.ts +10 -0
- package/dist/emit/mcp/runtime.js +47 -0
- package/dist/emit/mcp/schema.d.ts +19 -0
- package/dist/emit/mcp/schema.js +88 -0
- package/dist/emit/mcp/server.d.ts +30 -0
- package/dist/emit/mcp/server.js +246 -0
- package/dist/emit/mcp/tools.d.ts +51 -0
- package/dist/emit/mcp/tools.js +153 -0
- package/dist/emit/python/errors.d.ts +8 -0
- package/dist/emit/python/errors.js +68 -0
- package/dist/emit/python/index.d.ts +1 -0
- package/dist/emit/python/index.js +1 -0
- package/dist/emit/python/realtime.d.ts +10 -0
- package/dist/emit/python/realtime.js +33 -0
- package/dist/emit/python/sdk-answer.d.ts +49 -0
- package/dist/emit/python/sdk-answer.js +89 -0
- package/dist/emit/python/sdk-body.d.ts +11 -0
- package/dist/emit/python/sdk-body.js +40 -0
- package/dist/emit/python/sdk-client.d.ts +36 -0
- package/dist/emit/python/sdk-client.js +163 -0
- package/dist/emit/python/sdk-doc.d.ts +9 -0
- package/dist/emit/python/sdk-doc.js +32 -0
- package/dist/emit/python/sdk-imports.d.ts +14 -0
- package/dist/emit/python/sdk-imports.js +38 -0
- package/dist/emit/python/sdk-method.d.ts +29 -0
- package/dist/emit/python/sdk-method.js +183 -0
- package/dist/emit/python/sdk-plan.d.ts +33 -0
- package/dist/emit/python/sdk-plan.js +1 -0
- package/dist/emit/python/sdk-pyproject.d.ts +27 -0
- package/dist/emit/python/sdk-pyproject.js +103 -0
- package/dist/emit/python/sdk.d.ts +22 -0
- package/dist/emit/python/sdk.js +154 -0
- package/dist/emit/python/sse.d.ts +12 -0
- package/dist/emit/python/sse.js +23 -0
- package/dist/emit/python/transport.d.ts +15 -0
- package/dist/emit/python/transport.js +60 -0
- package/dist/emit/python/types-dict.d.ts +31 -0
- package/dist/emit/python/types-dict.js +45 -0
- package/dist/emit/python/types-names.d.ts +16 -0
- package/dist/emit/python/types-names.js +52 -0
- package/dist/emit/python/types-union.d.ts +32 -0
- package/dist/emit/python/types-union.js +46 -0
- package/dist/emit/python/types.d.ts +36 -0
- package/dist/emit/python/types.js +128 -0
- package/dist/emit/python/ws.d.ts +14 -0
- package/dist/emit/python/ws.js +16 -0
- package/dist/emit/rust/errors.d.ts +7 -0
- package/dist/emit/rust/errors.js +107 -0
- package/dist/emit/rust/http.d.ts +13 -0
- package/dist/emit/rust/http.js +67 -0
- package/dist/emit/rust/index.d.ts +1 -0
- package/dist/emit/rust/index.js +1 -0
- package/dist/emit/rust/realtime.d.ts +11 -0
- package/dist/emit/rust/realtime.js +29 -0
- package/dist/emit/rust/sdk-body.d.ts +19 -0
- package/dist/emit/rust/sdk-body.js +53 -0
- package/dist/emit/rust/sdk-cargo.d.ts +43 -0
- package/dist/emit/rust/sdk-cargo.js +178 -0
- package/dist/emit/rust/sdk-client.d.ts +25 -0
- package/dist/emit/rust/sdk-client.js +108 -0
- package/dist/emit/rust/sdk-method.d.ts +15 -0
- package/dist/emit/rust/sdk-method.js +119 -0
- package/dist/emit/rust/sdk-opts.d.ts +58 -0
- package/dist/emit/rust/sdk-opts.js +117 -0
- package/dist/emit/rust/sdk-plan.d.ts +33 -0
- package/dist/emit/rust/sdk-plan.js +1 -0
- package/dist/emit/rust/sdk.d.ts +23 -0
- package/dist/emit/rust/sdk.js +111 -0
- package/dist/emit/rust/sse.d.ts +19 -0
- package/dist/emit/rust/sse.js +20 -0
- package/dist/emit/rust/types-enum.d.ts +13 -0
- package/dist/emit/rust/types-enum.js +62 -0
- package/dist/emit/rust/types-names.d.ts +19 -0
- package/dist/emit/rust/types-names.js +66 -0
- package/dist/emit/rust/types-struct.d.ts +21 -0
- package/dist/emit/rust/types-struct.js +59 -0
- package/dist/emit/rust/types-union.d.ts +24 -0
- package/dist/emit/rust/types-union.js +97 -0
- package/dist/emit/rust/types.d.ts +34 -0
- package/dist/emit/rust/types.js +105 -0
- package/dist/emit/rust/ws.d.ts +21 -0
- package/dist/emit/rust/ws.js +20 -0
- package/dist/emit/shared/escape.d.ts +55 -0
- package/dist/emit/shared/escape.js +144 -0
- package/dist/emit/shared/format.d.ts +24 -0
- package/dist/emit/shared/format.js +23 -0
- package/dist/emit/shared/gofmt.d.ts +3 -0
- package/dist/emit/shared/gofmt.js +26 -0
- package/dist/emit/shared/lang.d.ts +60 -0
- package/dist/emit/shared/lang.js +233 -0
- package/dist/emit/shared/literals.d.ts +4 -0
- package/dist/emit/shared/literals.js +31 -0
- package/dist/emit/shared/metadata.d.ts +106 -0
- package/dist/emit/shared/metadata.js +130 -0
- package/dist/emit/shared/mirror.d.ts +22 -0
- package/dist/emit/shared/mirror.js +26 -0
- package/dist/emit/shared/ruff.d.ts +3 -0
- package/dist/emit/shared/ruff.js +31 -0
- package/dist/emit/shared/rustfmt.d.ts +3 -0
- package/dist/emit/shared/rustfmt.js +32 -0
- package/dist/emit/shared/status-keys.d.ts +7 -0
- package/dist/emit/shared/status-keys.js +67 -0
- package/dist/emit/shared/type-emitter.d.ts +19 -0
- package/dist/emit/shared/type-emitter.js +100 -0
- package/dist/emit/ts/app-client.d.ts +4 -0
- package/dist/emit/ts/app-client.js +68 -0
- package/dist/emit/ts/http.d.ts +20 -0
- package/dist/emit/ts/http.js +74 -0
- package/dist/emit/ts/package.d.ts +36 -0
- package/dist/emit/ts/package.js +126 -0
- package/dist/emit/ts/route-tree.d.ts +68 -0
- package/dist/emit/ts/route-tree.js +240 -0
- package/dist/emit/ts/sdk-types-preamble.d.ts +14 -0
- package/dist/emit/ts/sdk-types-preamble.js +123 -0
- package/dist/emit/ts/sdk-types.d.ts +13 -0
- package/dist/emit/ts/sdk-types.js +213 -0
- package/dist/emit/ts/sdk.d.ts +21 -0
- package/dist/emit/ts/sdk.js +173 -0
- package/dist/emit/ts/service-map.d.ts +40 -0
- package/dist/emit/ts/service-map.js +171 -0
- package/dist/emit/ts/tanstack-query.d.ts +12 -0
- package/dist/emit/ts/tanstack-query.js +156 -0
- package/dist/emit/ts/type-gen.d.ts +26 -0
- package/dist/emit/ts/type-gen.js +255 -0
- package/dist/emit/ts/webhooks.d.ts +19 -0
- package/dist/emit/ts/webhooks.js +81 -0
- package/dist/extract/chain.d.ts +34 -0
- package/dist/extract/chain.js +84 -0
- package/dist/extract/extract.d.ts +41 -0
- package/dist/extract/extract.js +191 -0
- package/dist/extract/serialize.d.ts +34 -0
- package/dist/extract/serialize.js +295 -0
- package/dist/extract/walk.d.ts +47 -0
- package/dist/extract/walk.js +109 -0
- package/dist/gen/args.d.ts +28 -0
- package/dist/gen/args.js +133 -0
- package/dist/gen/formatters.d.ts +62 -0
- package/dist/gen/formatters.js +146 -0
- package/dist/gen/process.d.ts +13 -0
- package/dist/gen/process.js +35 -0
- package/dist/gen/shipped.d.ts +17 -0
- package/dist/gen/shipped.js +55 -0
- package/dist/gen/targets.d.ts +93 -0
- package/dist/gen/targets.js +171 -0
- package/dist/gen/write.d.ts +33 -0
- package/dist/gen/write.js +118 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +15 -0
- package/dist/ir/build.d.ts +37 -0
- package/dist/ir/build.js +152 -0
- package/dist/ir/load.d.ts +11 -0
- package/dist/ir/load.js +112 -0
- package/dist/ir/model.d.ts +206 -0
- package/dist/ir/model.js +5 -0
- package/dist/ir/resolve-refs.d.ts +11 -0
- package/dist/ir/resolve-refs.js +66 -0
- package/dist/ir/resource-tree.d.ts +9 -0
- package/dist/ir/resource-tree.js +53 -0
- package/dist/ir/route-tree-intern.d.ts +18 -0
- package/dist/ir/route-tree-intern.js +174 -0
- package/dist/ir/schema.d.ts +11 -0
- package/dist/ir/schema.js +192 -0
- package/dist/ir/sdk-model.d.ts +86 -0
- package/dist/ir/sdk-model.js +204 -0
- package/dist/ir/slots.d.ts +42 -0
- package/dist/ir/slots.js +245 -0
- package/dist/runtime/cli/body.go +176 -0
- package/dist/runtime/cli/config.go +243 -0
- package/dist/runtime/cli/discovery.go +147 -0
- package/dist/runtime/cli/format.go +174 -0
- package/dist/runtime/cli/log.go +117 -0
- package/dist/runtime/cli/output.go +247 -0
- package/dist/runtime/cli/params.go +197 -0
- package/dist/runtime/cli/run.go +226 -0
- package/dist/runtime/cli/socket.go +60 -0
- package/dist/runtime/cli/stream.go +217 -0
- package/dist/runtime/cli/target.go +117 -0
- package/dist/runtime/csharp/Adapters.cs +183 -0
- package/dist/runtime/csharp/Auth.cs +56 -0
- package/dist/runtime/csharp/Body.cs +135 -0
- package/dist/runtime/csharp/Config.cs +161 -0
- package/dist/runtime/csharp/Envelope.cs +149 -0
- package/dist/runtime/csharp/Errors.cs +194 -0
- package/dist/runtime/csharp/Events.cs +155 -0
- package/dist/runtime/csharp/Exchange.cs +247 -0
- package/dist/runtime/csharp/Handler.cs +103 -0
- package/dist/runtime/csharp/Hooks.cs +128 -0
- package/dist/runtime/csharp/Invalidation.cs +102 -0
- package/dist/runtime/csharp/Json.cs +144 -0
- package/dist/runtime/csharp/Log.cs +48 -0
- package/dist/runtime/csharp/Operation.cs +33 -0
- package/dist/runtime/csharp/Path.cs +65 -0
- package/dist/runtime/csharp/Query.cs +72 -0
- package/dist/runtime/csharp/Realtime.cs +118 -0
- package/dist/runtime/csharp/RealtimeLoop.cs +236 -0
- package/dist/runtime/csharp/Redirect.cs +53 -0
- package/dist/runtime/csharp/Result.cs +57 -0
- package/dist/runtime/csharp/Sse.cs +122 -0
- package/dist/runtime/csharp/Stale.cs +151 -0
- package/dist/runtime/csharp/Transport.cs +143 -0
- package/dist/runtime/csharp/TransportLongPoll.cs +63 -0
- package/dist/runtime/csharp/TransportSse.cs +54 -0
- package/dist/runtime/csharp/TransportWs.cs +40 -0
- package/dist/runtime/csharp/Wire.cs +109 -0
- package/dist/runtime/csharp/Ws.cs +300 -0
- package/dist/runtime/csharp/WsDial.cs +127 -0
- package/dist/runtime/go/auth.go +127 -0
- package/dist/runtime/go/body.go +129 -0
- package/dist/runtime/go/config.go +75 -0
- package/dist/runtime/go/errors.go +185 -0
- package/dist/runtime/go/export.go +37 -0
- package/dist/runtime/go/hooks.go +53 -0
- package/dist/runtime/go/invalidation.go +112 -0
- package/dist/runtime/go/log.go +92 -0
- package/dist/runtime/go/nullable.go +64 -0
- package/dist/runtime/go/options.go +118 -0
- package/dist/runtime/go/path.go +156 -0
- package/dist/runtime/go/query.go +147 -0
- package/dist/runtime/go/realtime.go +239 -0
- package/dist/runtime/go/realtime_loop.go +208 -0
- package/dist/runtime/go/redirect.go +124 -0
- package/dist/runtime/go/request.go +222 -0
- package/dist/runtime/go/result.go +86 -0
- package/dist/runtime/go/sse.go +186 -0
- package/dist/runtime/go/stale.go +229 -0
- package/dist/runtime/go/stream.go +105 -0
- package/dist/runtime/go/transport.go +242 -0
- package/dist/runtime/go/transport_longpoll.go +121 -0
- package/dist/runtime/go/transport_sse.go +175 -0
- package/dist/runtime/go/ws.go +205 -0
- package/dist/runtime/java/Answer.java +107 -0
- package/dist/runtime/java/ApiException.java +110 -0
- package/dist/runtime/java/BinaryBody.java +36 -0
- package/dist/runtime/java/Body.java +105 -0
- package/dist/runtime/java/Call.java +23 -0
- package/dist/runtime/java/CallLog.java +51 -0
- package/dist/runtime/java/ClientConfig.java +233 -0
- package/dist/runtime/java/ConnectionState.java +12 -0
- package/dist/runtime/java/Credential.java +58 -0
- package/dist/runtime/java/Deadline.java +38 -0
- package/dist/runtime/java/Decode.java +181 -0
- package/dist/runtime/java/Envelope.java +141 -0
- package/dist/runtime/java/ErrorEnvelope.java +23 -0
- package/dist/runtime/java/EventStream.java +129 -0
- package/dist/runtime/java/Exchange.java +62 -0
- package/dist/runtime/java/FilePart.java +5 -0
- package/dist/runtime/java/Flight.java +306 -0
- package/dist/runtime/java/HoneyException.java +14 -0
- package/dist/runtime/java/Hooks.java +47 -0
- package/dist/runtime/java/Hops.java +133 -0
- package/dist/runtime/java/InvalidationConfig.java +73 -0
- package/dist/runtime/java/Json.java +23 -0
- package/dist/runtime/java/Keepalive.java +60 -0
- package/dist/runtime/java/LogEntry.java +14 -0
- package/dist/runtime/java/LongPollAdapter.java +68 -0
- package/dist/runtime/java/Operation.java +21 -0
- package/dist/runtime/java/Opt.java +121 -0
- package/dist/runtime/java/Pump.java +160 -0
- package/dist/runtime/java/RawResponse.java +48 -0
- package/dist/runtime/java/Realtime.java +152 -0
- package/dist/runtime/java/RealtimeLoop.java +371 -0
- package/dist/runtime/java/RedirectPolicy.java +13 -0
- package/dist/runtime/java/Redirects.java +126 -0
- package/dist/runtime/java/RequestContext.java +78 -0
- package/dist/runtime/java/RequestHook.java +9 -0
- package/dist/runtime/java/RequestOptions.java +91 -0
- package/dist/runtime/java/ResponseContext.java +70 -0
- package/dist/runtime/java/ResponseHook.java +12 -0
- package/dist/runtime/java/Result.java +32 -0
- package/dist/runtime/java/ResumableConnection.java +165 -0
- package/dist/runtime/java/SdkException.java +11 -0
- package/dist/runtime/java/Socket.java +301 -0
- package/dist/runtime/java/Sse.java +171 -0
- package/dist/runtime/java/SseAdapter.java +61 -0
- package/dist/runtime/java/SseEvent.java +10 -0
- package/dist/runtime/java/StaleMeta.java +16 -0
- package/dist/runtime/java/StaleTracker.java +287 -0
- package/dist/runtime/java/Transport.java +16 -0
- package/dist/runtime/java/TransportAdapter.java +14 -0
- package/dist/runtime/java/TransportConnection.java +15 -0
- package/dist/runtime/java/TransportKind.java +12 -0
- package/dist/runtime/java/TransportMessage.java +9 -0
- package/dist/runtime/java/TransportOptions.java +138 -0
- package/dist/runtime/java/TypedWebSocket.java +83 -0
- package/dist/runtime/java/UrlPath.java +49 -0
- package/dist/runtime/java/UrlQuery.java +99 -0
- package/dist/runtime/java/WsAdapter.java +52 -0
- package/dist/runtime/java/WsClose.java +47 -0
- package/dist/runtime/java/WsDial.java +148 -0
- package/dist/runtime/java/WsMessage.java +18 -0
- package/dist/runtime/mcp/call.ts +167 -0
- package/dist/runtime/mcp/files.ts +183 -0
- package/dist/runtime/mcp/guard.ts +176 -0
- package/dist/runtime/mcp/http.ts +159 -0
- package/dist/runtime/mcp/jsonrpc.ts +50 -0
- package/dist/runtime/mcp/listen.ts +76 -0
- package/dist/runtime/mcp/mount.ts +123 -0
- package/dist/runtime/mcp/protocol.ts +219 -0
- package/dist/runtime/mcp/reader.ts +57 -0
- package/dist/runtime/mcp/result.ts +85 -0
- package/dist/runtime/mcp/stdio.ts +79 -0
- package/dist/runtime/mcp/stream.ts +62 -0
- package/dist/runtime/python/__init__.py +2 -0
- package/dist/runtime/python/auth.py +67 -0
- package/dist/runtime/python/body.py +83 -0
- package/dist/runtime/python/config.py +139 -0
- package/dist/runtime/python/errors.py +213 -0
- package/dist/runtime/python/events.py +152 -0
- package/dist/runtime/python/exchange.py +298 -0
- package/dist/runtime/python/hooks.py +86 -0
- package/dist/runtime/python/invalidation.py +57 -0
- package/dist/runtime/python/log.py +60 -0
- package/dist/runtime/python/operation.py +25 -0
- package/dist/runtime/python/path.py +41 -0
- package/dist/runtime/python/query.py +48 -0
- package/dist/runtime/python/realtime.py +244 -0
- package/dist/runtime/python/redirect.py +93 -0
- package/dist/runtime/python/result.py +58 -0
- package/dist/runtime/python/send_async.py +189 -0
- package/dist/runtime/python/send_sync.py +105 -0
- package/dist/runtime/python/sse.py +81 -0
- package/dist/runtime/python/stale.py +94 -0
- package/dist/runtime/python/transport.py +157 -0
- package/dist/runtime/python/transport_longpoll.py +60 -0
- package/dist/runtime/python/transport_sse.py +60 -0
- package/dist/runtime/python/transport_ws.py +57 -0
- package/dist/runtime/python/ws.py +276 -0
- package/dist/runtime/rust/Cargo.lock +1763 -0
- package/dist/runtime/rust/answer.rs +120 -0
- package/dist/runtime/rust/auth.rs +80 -0
- package/dist/runtime/rust/body.rs +150 -0
- package/dist/runtime/rust/call.rs +200 -0
- package/dist/runtime/rust/config.rs +254 -0
- package/dist/runtime/rust/envelope.rs +84 -0
- package/dist/runtime/rust/errors.rs +235 -0
- package/dist/runtime/rust/events.rs +177 -0
- package/dist/runtime/rust/exchange.rs +287 -0
- package/dist/runtime/rust/hooks.rs +63 -0
- package/dist/runtime/rust/invalidation.rs +84 -0
- package/dist/runtime/rust/log.rs +88 -0
- package/dist/runtime/rust/nullable.rs +13 -0
- package/dist/runtime/rust/path.rs +83 -0
- package/dist/runtime/rust/query.rs +84 -0
- package/dist/runtime/rust/realtime.rs +182 -0
- package/dist/runtime/rust/realtime_loop.rs +177 -0
- package/dist/runtime/rust/redirect.rs +121 -0
- package/dist/runtime/rust/request.rs +178 -0
- package/dist/runtime/rust/result.rs +101 -0
- package/dist/runtime/rust/sse.rs +104 -0
- package/dist/runtime/rust/stale.rs +209 -0
- package/dist/runtime/rust/transport.rs +221 -0
- package/dist/runtime/rust/transport_longpoll.rs +108 -0
- package/dist/runtime/rust/transport_sse.rs +91 -0
- package/dist/runtime/rust/transport_ws.rs +75 -0
- package/dist/runtime/rust/ws.rs +322 -0
- package/dist/runtime/ts/app-types.ts +200 -0
- package/dist/runtime/ts/app.ts +104 -0
- package/dist/runtime/ts/config.ts +124 -0
- package/dist/runtime/ts/defaults.ts +48 -0
- package/dist/runtime/ts/error.ts +113 -0
- package/dist/runtime/ts/hooks.ts +92 -0
- package/dist/runtime/ts/http.ts +228 -0
- package/dist/runtime/ts/media-type.ts +36 -0
- package/dist/runtime/ts/path.ts +152 -0
- package/dist/runtime/ts/realtime-connection.ts +296 -0
- package/dist/runtime/ts/realtime-transports.ts +149 -0
- package/dist/runtime/ts/realtime.ts +293 -0
- package/dist/runtime/ts/redirect-policy.ts +17 -0
- package/dist/runtime/ts/redirects.ts +74 -0
- package/dist/runtime/ts/request.ts +239 -0
- package/dist/runtime/ts/response.ts +219 -0
- package/dist/runtime/ts/sdk-realtime.ts +10 -0
- package/dist/runtime/ts/sdk-sse.ts +55 -0
- package/dist/runtime/ts/sdk-ws.ts +21 -0
- package/dist/runtime/ts/sdk.ts +242 -0
- package/dist/runtime/ts/sse.ts +175 -0
- package/dist/runtime/ts/stale.ts +137 -0
- package/dist/runtime/ts/stream.ts +87 -0
- package/dist/runtime/ts/webhook.ts +116 -0
- package/dist/runtime/ts/ws.ts +155 -0
- package/dist/runtime/ts-tanstack-query/invalidate.ts +152 -0
- package/dist/runtime/ts-tanstack-query/query.ts +261 -0
- package/package.json +84 -5
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lovro Žagar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,620 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @workerstack/clients
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a Go command-line client and a Model Context Protocol
|
|
4
|
+
server from an OpenAPI 3.x document, or straight from a
|
|
5
|
+
[`@workerstack/backend`](https://www.npmjs.com/package/@workerstack/backend) app.
|
|
6
|
+
|
|
7
|
+
Every target reads one intermediate representation and vendors its own small runtime, so a generated SDK has no
|
|
8
|
+
dependency on honey, and a spec from another framework generates just as well. The output is formatted and
|
|
9
|
+
deterministic: regenerating an unchanged spec changes nothing on disk.
|
|
10
|
+
|
|
11
|
+
This page is the whole generator — every target, every flag, and what each client looks like to call.
|
|
12
|
+
|
|
13
|
+
- [Install](#install)
|
|
14
|
+
- [Start](#start)
|
|
15
|
+
- [honey-clients generate](#honey-clients-generate)
|
|
16
|
+
- [Every flag](#every-flag)
|
|
17
|
+
- [The six SDKs](#the-six-sdks)
|
|
18
|
+
- [The TypeScript SDK](#the-typescript-sdk)
|
|
19
|
+
- [The Go SDK](#the-go-sdk)
|
|
20
|
+
- [The Rust SDK](#the-rust-sdk)
|
|
21
|
+
- [The Python SDK](#the-python-sdk)
|
|
22
|
+
- [The C# SDK](#the-c-sdk)
|
|
23
|
+
- [The Java SDK](#the-java-sdk)
|
|
24
|
+
- [Errors and the safe mirror](#errors-and-the-safe-mirror)
|
|
25
|
+
- [The command-line client](#the-command-line-client)
|
|
26
|
+
- [The MCP server](#the-mcp-server)
|
|
27
|
+
- [Configuring generation](#configuring-generation)
|
|
28
|
+
- [What a run writes](#what-a-run-writes)
|
|
29
|
+
- [Documentation](#documentation)
|
|
30
|
+
- [License](#license)
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
honey moved to the workerstack org in 1.0.0-rc.23, and [the migration note](https://github.com/workerstack/backend/blob/main/docs/migrating-to-workerstack.md)
|
|
35
|
+
maps each old package name to its new one. 1.0 is out as a release candidate, published under npm's `next` tag, so
|
|
36
|
+
an install without a tag gets a deprecated placeholder.
|
|
37
|
+
Add `@next` until the final release:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npm install --save-dev @workerstack/clients@next
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Node 22.12 or later, or Bun 1.3 or later.
|
|
44
|
+
|
|
45
|
+
Each target formats what it writes with that language's own formatter, when it can find it:
|
|
46
|
+
|
|
47
|
+
| target | formatter | found by |
|
|
48
|
+
| ----------- | --------- | --------------------------------------------------------------------------- |
|
|
49
|
+
| `go`, `cli` | gofmt | `$GOFMT`, `$GOROOT/bin/gofmt`, `gofmt` on `PATH`, beside the `go` on `PATH` |
|
|
50
|
+
| `python` | ruff | `$RUFF`, then `ruff` on `PATH` |
|
|
51
|
+
| `rust` | rustfmt | `$RUSTFMT`, the active toolchain's own binary beside `rustc`, `PATH` |
|
|
52
|
+
| `ts` | oxfmt | the `oxfmt` optional peer, installed beside honey-clients |
|
|
53
|
+
|
|
54
|
+
A formatter it cannot find is named on standard error and skipped: the files go out as the emitter wrote them,
|
|
55
|
+
which is valid source either way, so generating a Python SDK never requires you to install ruff. Set
|
|
56
|
+
`HONEY_REQUIRE_FORMATTERS=1` to make a missing formatter fail the run instead, for a pipeline that would
|
|
57
|
+
rather stop than ship unformatted code. An override that points at nothing is refused by name.
|
|
58
|
+
|
|
59
|
+
oxfmt is the exception and says nothing when absent: it is honey's own choice of TypeScript formatter and a
|
|
60
|
+
declared optional peer, so not having it is the documented normal rather than news. `HONEY_REQUIRE_FORMATTERS`
|
|
61
|
+
still stops for it.
|
|
62
|
+
|
|
63
|
+
The `csharp` and `java` targets are not formatted today: `dotnet format` and google-java-format work over a
|
|
64
|
+
project rather than a stream, which honey's post-pass does not yet do.
|
|
65
|
+
|
|
66
|
+
## Start
|
|
67
|
+
|
|
68
|
+
From a document:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
npx honey-clients generate --spec openapi.json --target ts --target python --out generated
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
From a honey app module, with no document written first:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
npx honey-clients generate --app src/app.ts --target ts --target go --go-module-path github.com/acme/shop/sdk \
|
|
78
|
+
--out generated
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The targets are `ts`, `go`, `rust`, `python`, `csharp`, `java`, `cli` and `mcp`. Each target's files go under
|
|
82
|
+
`<out>/<target>`.
|
|
83
|
+
|
|
84
|
+
## honey-clients generate
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
honey-clients generate --spec openapi.json --target ts --target cli --out generated \
|
|
88
|
+
--cli-binary-name shop --cli-module-path github.com/acme/shop --cli-repo acme/shop
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- `--spec <file>`: the OpenAPI document, as JSON.
|
|
92
|
+
- `--app <module>[#export]`: a honey app module instead of `--spec` (give one, never both). Its named export, else
|
|
93
|
+
`app`, else `default`, is the app; its document is made by the app's own `@workerstack/backend/openapi`, resolved from
|
|
94
|
+
the app as at run time, and the module's `openApi` export, if any, is that document's options (`info`,
|
|
95
|
+
`securitySchemes`, `invalidate`, …, as `generateOpenApi` takes them). Started by `bun run`, the bin hands the load to
|
|
96
|
+
that Bun, so a module needing Bun's loaders works; a run ends once it has written, whatever the module left open.
|
|
97
|
+
The module exports the app and serves nothing: one that calls `serve()` as it loads is outside `--app`'s contract,
|
|
98
|
+
since honey never serves implicitly and has no switch to stop it.
|
|
99
|
+
- `--target <name>`: `ts`, `go`, `rust`, `python`, `csharp`, `java`, `cli` or `mcp`; repeat it for more than one.
|
|
100
|
+
- `--out <dir>`: each target's files go under `<dir>/<target>`.
|
|
101
|
+
- `--<target>-<option>`: a target's options are its generator's, passed through as given. Each takes a value.
|
|
102
|
+
- `--watch`: generate again on each change of the spec (or the `--app` module), each run in a fresh process.
|
|
103
|
+
- `-h`, `--help`: the usage text, with every target's options.
|
|
104
|
+
|
|
105
|
+
Parsing is strict, because a typo that generates the wrong thing silently is worse than a refusal: an unknown flag, a
|
|
106
|
+
missing value, a stray argument, an unknown target, or an option for a target no `--target` names is a usage error.
|
|
107
|
+
`--k v` and `--k=v` both work, and a value is never the next flag.
|
|
108
|
+
|
|
109
|
+
## Every flag
|
|
110
|
+
|
|
111
|
+
One table, since a flag that is not written down is a flag nobody finds:
|
|
112
|
+
|
|
113
|
+
| Flag | Target | What it sets |
|
|
114
|
+
| -------------------------- | ------ | --------------------------------------------------------------------------------- |
|
|
115
|
+
| `--spec <file>` | — | the OpenAPI document to generate from |
|
|
116
|
+
| `--app <module>[#export]` | — | a honey app module instead of a document |
|
|
117
|
+
| `--target <name>` | — | which target to emit; repeat for more than one |
|
|
118
|
+
| `--out <dir>` | — | the output root; each target writes under `<dir>/<target>` |
|
|
119
|
+
| `--watch` | — | regenerate on each change, in a fresh process |
|
|
120
|
+
| `-h`, `--help` | — | the usage text |
|
|
121
|
+
| `--ts-name` | ts | the client class's name (default `SDK`) |
|
|
122
|
+
| `--ts-stem` | ts | the file stem the generated modules share |
|
|
123
|
+
| `--ts-package-name` | ts | the npm name, and the JSR name when scoped; the stem by default |
|
|
124
|
+
| `--ts-version` | ts | the version both registries carry; the document's by default |
|
|
125
|
+
| `--ts-tanstack-query` | ts | also write the TanStack Query adapter; takes no value |
|
|
126
|
+
| `--go-module-path` | go | the Go module path the SDK is imported by |
|
|
127
|
+
| `--go-version` | go | its semver; from v2 on, the major suffix (`/v2`) it puts on the module path |
|
|
128
|
+
| `--rust-crate-name` | rust | the crate's name |
|
|
129
|
+
| `--rust-version` | rust | the crate's version |
|
|
130
|
+
| `--rust-description` | rust | what crates.io shows; `cargo publish` needs one |
|
|
131
|
+
| `--rust-license` | rust | its SPDX license; `cargo publish` needs one |
|
|
132
|
+
| `--rust-repository` | rust | the repository crates.io links |
|
|
133
|
+
| `--rust-homepage` | rust | the home page crates.io links |
|
|
134
|
+
| `--rust-keywords` | rust | its crates.io keywords, comma separated: five at most, each 20 ASCII characters |
|
|
135
|
+
| `--rust-categories` | rust | its crates.io category slugs, comma separated: five at most |
|
|
136
|
+
| `--rust-documentation` | rust | the https documentation crates.io links; docs.rs by default |
|
|
137
|
+
| `--python-package-name` | python | the Python package's name |
|
|
138
|
+
| `--python-version` | python | the package's version |
|
|
139
|
+
| `--csharp-client-name` | csharp | the client class's name |
|
|
140
|
+
| `--csharp-package-id` | csharp | the NuGet package id |
|
|
141
|
+
| `--csharp-root-namespace` | csharp | the root namespace |
|
|
142
|
+
| `--csharp-version` | csharp | the package's version |
|
|
143
|
+
| `--csharp-description` | csharp | what nuget.org shows |
|
|
144
|
+
| `--csharp-authors` | csharp | its authors, comma separated |
|
|
145
|
+
| `--csharp-license` | csharp | its SPDX license expression |
|
|
146
|
+
| `--csharp-homepage` | csharp | the https home page nuget.org links |
|
|
147
|
+
| `--csharp-repository` | csharp | the https URL of its git repository |
|
|
148
|
+
| `--csharp-copyright` | csharp | the copyright notice nuget.org shows |
|
|
149
|
+
| `--csharp-tags` | csharp | its NuGet tags, comma separated |
|
|
150
|
+
| `--java-artifact-id` | java | the Maven artifact id; `sdk` by default |
|
|
151
|
+
| `--java-group-id` | java | the Maven group id; `com.example` by default, yours to publish |
|
|
152
|
+
| `--java-package-name` | java | the Java package name |
|
|
153
|
+
| `--java-client-name` | java | the client class's name |
|
|
154
|
+
| `--java-version` | java | the publication's version |
|
|
155
|
+
| `--java-description` | java | the POM's description; the document's by default |
|
|
156
|
+
| `--java-homepage` | java | the POM's https project URL |
|
|
157
|
+
| `--java-license` | java | its SPDX license id, linked to spdx.org |
|
|
158
|
+
| `--java-repository` | java | the https URL of its git repository, the POM's scm |
|
|
159
|
+
| `--java-developers` | java | the POM's developers, comma separated: each a name or `Name <email>` |
|
|
160
|
+
| `--cli-binary-name` | cli | the command's own name (`shop`) |
|
|
161
|
+
| `--cli-base-url` | cli | the base URL it calls by default; the document's server by default |
|
|
162
|
+
| `--cli-module-path` | cli | the Go module path the CLI is built from |
|
|
163
|
+
| `--cli-version` | cli | its semver; from v2 on, the major suffix (`/v2`) it puts on the module path |
|
|
164
|
+
| `--cli-repo` | cli | the GitHub repository its release workflow and install scripts use |
|
|
165
|
+
| `--cli-env-prefix` | cli | the prefix of the environment variables it reads |
|
|
166
|
+
| `--cli-install-url` | cli | the https directory its install scripts are served from; the release's by default |
|
|
167
|
+
| `--cli-description` | cli | what the package managers show; every channel needs one |
|
|
168
|
+
| `--cli-homepage` | cli | the home page the package managers link; every channel needs one |
|
|
169
|
+
| `--cli-license` | cli | its SPDX license; every channel needs one |
|
|
170
|
+
| `--cli-maintainer` | cli | `Name <email>`, which AUR and the Linux packages name |
|
|
171
|
+
| `--cli-homebrew-tap` | cli | the Homebrew tap (`owner/name`) its cask is pushed to |
|
|
172
|
+
| `--cli-scoop-bucket` | cli | the Scoop bucket (`owner/name`) its manifest is pushed to |
|
|
173
|
+
| `--cli-winget-fork` | cli | the winget-pkgs fork (`owner/name`) its manifests are proposed from |
|
|
174
|
+
| `--cli-winget-publisher` | cli | the publisher winget files it under |
|
|
175
|
+
| `--cli-aur` | cli | a switch: publish the `<bin>-bin` AUR package |
|
|
176
|
+
| `--cli-packages` | cli | Linux packages beside the archives: `deb`, `rpm`, `apk`, comma separated |
|
|
177
|
+
| `--mcp-name` | mcp | the server's name, and the stem of its bin |
|
|
178
|
+
| `--mcp-env-prefix` | mcp | the prefix of the environment variables it reads |
|
|
179
|
+
| `--mcp-version` | mcp | its server info and package version; the document's by default |
|
|
180
|
+
| `--mcp-package-name` | mcp | the npm name it publishes under; `<name>-mcp` by default |
|
|
181
|
+
| `--mcp-mcp-name` | mcp | its MCP registry name (`io.github.acme/shop`), package.json's `mcpName` |
|
|
182
|
+
| `--metadata-description` | all | what every registry shows |
|
|
183
|
+
| `--metadata-homepage` | all | the https home page the registries link |
|
|
184
|
+
| `--metadata-repository` | all | the https URL of its git repository |
|
|
185
|
+
| `--metadata-license` | all | its SPDX license expression |
|
|
186
|
+
| `--metadata-authors` | all | each `Name <email>` or a name, comma separated |
|
|
187
|
+
| `--metadata-keywords` | all | registry keywords, comma separated |
|
|
188
|
+
| `--metadata-copyright` | all | the copyright line |
|
|
189
|
+
| `--metadata-documentation` | all | the https URL of its documentation |
|
|
190
|
+
| `--metadata-changelog` | all | the https URL of its changelog |
|
|
191
|
+
| `--metadata-license-file` | all | the license file to ship in each package |
|
|
192
|
+
| `--metadata-readme` | all | the README to ship in each package |
|
|
193
|
+
| `--metadata-icon` | all | the package icon to ship where the registry shows one |
|
|
194
|
+
|
|
195
|
+
The `--metadata-<field>` flags fill one package block that every target which publishes reads where its registry has
|
|
196
|
+
a place for the field, so a description or license is given once, not once per target. A target's own option of the
|
|
197
|
+
same meaning wins: `--java-description` over `--metadata-description`. Each field is checked before anything
|
|
198
|
+
generates: URLs must be https, the license an SPDX expression, text one line.
|
|
199
|
+
|
|
200
|
+
`--metadata-readme` and `--metadata-license-file` name files on disk, read once relative to where honey runs. Every
|
|
201
|
+
target writes them into its package root as `README.md` and `LICENSE`, and each manifest points at the ones it has:
|
|
202
|
+
pyproject's `readme` and `license-files`, Cargo's `readme` and `include`, the `.csproj`'s `PackageReadmeFile` and packed
|
|
203
|
+
items, and jsr.json's publish list; npm packs both on its own. The README must be a `.md` file, and both must be UTF-8
|
|
204
|
+
text. `--metadata-icon` ships only into the C# package, as `icon` with its own extension in lower case (`icon.png`,
|
|
205
|
+
`icon.jpeg`) under `PackageIcon`, since nuget.org is the one registry that shows an icon: a PNG or JPEG whose bytes are
|
|
206
|
+
that image, at most 1 MB.
|
|
207
|
+
|
|
208
|
+
## The six SDKs
|
|
209
|
+
|
|
210
|
+
Every SDK takes the same configuration — a base URL, the auth the spec's security scheme names, a timeout, retries,
|
|
211
|
+
hooks around each HTTP call, and per-call overrides — and every one answers the same way: the normal call returns
|
|
212
|
+
your value and throws a typed error by status, while `client.safe` answers a result instead. What follows is each
|
|
213
|
+
language's client in a slice of a compiled example; the
|
|
214
|
+
[SDK recipes](https://github.com/workerstack/backend/blob/main/docs/sdk-recipes.md) page has the whole programs.
|
|
215
|
+
|
|
216
|
+
### The TypeScript SDK
|
|
217
|
+
|
|
218
|
+
```sh
|
|
219
|
+
honey-clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
```ts sdk
|
|
223
|
+
import { DecodeError, Kitchen, NotFoundError } from "./kitchen"
|
|
224
|
+
|
|
225
|
+
export function newClient(): Kitchen {
|
|
226
|
+
return new Kitchen({
|
|
227
|
+
baseURL: "https://api.example.com",
|
|
228
|
+
headers: { authorization: `Bearer ${process.env.KITCHEN_TOKEN ?? ""}` },
|
|
229
|
+
timeout: 10_000,
|
|
230
|
+
})
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
export async function organization(client: Kitchen, orgId: string): Promise<string | null> {
|
|
234
|
+
try {
|
|
235
|
+
await client.getApiV1OrganizationsByOrgId({ params: { orgId } })
|
|
236
|
+
return orgId
|
|
237
|
+
} catch (error) {
|
|
238
|
+
if (error instanceof NotFoundError) return null
|
|
239
|
+
throw error
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
export async function health(client: Kitchen): Promise<string> {
|
|
244
|
+
const result = await client.safe.getApiHealth()
|
|
245
|
+
if (result.ok) return "up"
|
|
246
|
+
if (result.error instanceof DecodeError) return `unreadable answer: ${result.error.message}`
|
|
247
|
+
return `answered ${result.error.status}`
|
|
248
|
+
}
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
#### Publishing it to npm and JSR
|
|
252
|
+
|
|
253
|
+
The target writes a package around the SDK, so the output directory publishes as it is. The sources stay where a
|
|
254
|
+
workspace imports them; they import each other as `.js`, which every TypeScript resolution and bundler maps to the
|
|
255
|
+
`.ts` file. Node will not strip types under `node_modules`, so `dist/` holds each source compiled to ES module
|
|
256
|
+
JavaScript beside its declarations, and `package.json` exports those: the root, `./webhook` when the document has
|
|
257
|
+
webhook events, and `./tanstack-query` with `@tanstack/query-core` as an optional peer. A scoped `--ts-package-name`
|
|
258
|
+
also gets a `jsr.json` that publishes the sources themselves, its `.js` imports mapped to their `.ts` files.
|
|
259
|
+
`--metadata-*` fills description, keywords, homepage, bugs, license, author and repository.
|
|
260
|
+
|
|
261
|
+
```sh
|
|
262
|
+
honey-clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen \
|
|
263
|
+
--ts-package-name @acme/kitchen --ts-version 1.4.0 --metadata-license MIT
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
#### TanStack Query, from the same document
|
|
267
|
+
|
|
268
|
+
`--ts-tanstack-query` writes one more file beside the SDK, `<stem>.tanstack-query.gen.ts`. It takes no value:
|
|
269
|
+
|
|
270
|
+
```sh
|
|
271
|
+
honey-clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen --ts-tanstack-query
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Its `createQueryHelpers(sdk, { getQueryClient })` gives five surfaces — `query`, `mutation`, `infiniteQuery`,
|
|
275
|
+
`queryKey` and `mutationKey` — each nested exactly as the client is, so `query.org.member.list(…)` sits where
|
|
276
|
+
`client.org.member.list(…)` does. `sdk` may be a client or a thunk for one, which an isomorphic app needs.
|
|
277
|
+
|
|
278
|
+
The document decides what goes where. A `GET` is on `query`, every other method is on `mutation`, and an event
|
|
279
|
+
stream, a WebSocket or an `x-realtime` operation is on neither, because a stream is not a cache entry. Nothing
|
|
280
|
+
is keyed off a method's name.
|
|
281
|
+
|
|
282
|
+
**Keys.** A read's key is `[<SDK name>, ...the member path, the request]` — the request object whole, so
|
|
283
|
+
`params`, `search` and anything else the SDK sends are all in it. That is what TanStack requires: every input
|
|
284
|
+
the `queryFn` depends on belongs in the key, so two reads of one route that differ only by `search` are two
|
|
285
|
+
cache entries. `init` is not in the key, since a signal and a timeout say nothing about the answer. A read with
|
|
286
|
+
no request keys as `[<SDK name>, ...the member path]`. `queryKey.<…>(req)` returns exactly the key
|
|
287
|
+
`query.<…>({ reqOptions: { req } })` writes. A paged read carries a trailing `"infinite"` marker, because its
|
|
288
|
+
cached shape is `InfiniteData` and it must not share the plain read's entry.
|
|
289
|
+
|
|
290
|
+
**Invalidation** works by prefix, which is why the two are not the same shape. A successful write makes stale
|
|
291
|
+
the reads its `x-invalidate` selectors name, with the mutation's own path params filled in:
|
|
292
|
+
`[<SDK name>, ...the member path, { params }]`. TanStack matches objects partially and compares only the
|
|
293
|
+
filter's own positions, so that reaches every search of that read, the paged entry included. When a selector's
|
|
294
|
+
params are not all known the filter stays the bare prefix, which reaches everything under it — made stale
|
|
295
|
+
rather than missed.
|
|
296
|
+
|
|
297
|
+
Two notes. `@tanstack/query-core` is your dependency, not honey's — install it yourself; the file imports it for
|
|
298
|
+
types only. And a read's options carry `initialData: undefined`, which is what solid-query needs to keep the
|
|
299
|
+
unseeded overload; it is harmless under react-query.
|
|
300
|
+
|
|
301
|
+
Drop the flag and the next run deletes the file, the way `.honey-generated.json` deletes anything the previous
|
|
302
|
+
run wrote and this one did not. The index file never re-exports the adapter, so an SDK generated without the
|
|
303
|
+
flag names no TanStack type anywhere.
|
|
304
|
+
|
|
305
|
+
### The Go SDK
|
|
306
|
+
|
|
307
|
+
Idiomatic Go: a `Config`, `context.Context` on every call, errors read with `errors.As`, and an event stream as a
|
|
308
|
+
`range` over a function.
|
|
309
|
+
|
|
310
|
+
```sh
|
|
311
|
+
honey-clients generate --spec openapi.json --target go --out generated --go-module-path github.com/acme/shop/sdk
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Go wants a v2-or-later module's major version at the end of its path, so pass the base path and the version:
|
|
315
|
+
`--go-version 2.1.0` makes go.mod declare `github.com/acme/shop/sdk/v2`, and the CLI target's `--cli-version` does the
|
|
316
|
+
same for its module and the version it links in. A path Go would not publish (no domain first, or a suffix such as
|
|
317
|
+
`/v1`) is refused, as is a suffix next to a version, since the version gives it.
|
|
318
|
+
|
|
319
|
+
```go
|
|
320
|
+
func listing(ctx context.Context, client *sdk.Client) string {
|
|
321
|
+
r, err := client.Safe().GetApi(ctx, nil)
|
|
322
|
+
if err != nil {
|
|
323
|
+
return fmt.Sprintf("no answer: %v", err) // never sent, refused, dropped, timed out or canceled
|
|
324
|
+
}
|
|
325
|
+
var unreadable *sdk.DecodeError
|
|
326
|
+
var failed *sdk.ClientError
|
|
327
|
+
switch {
|
|
328
|
+
case r.Ok():
|
|
329
|
+
return fmt.Sprintf("answered %d: %v", r.Response.StatusCode, r.Data)
|
|
330
|
+
case errors.As(r.Err, &unreadable):
|
|
331
|
+
return fmt.Sprintf("answered %d, unreadable: %v", r.Response.StatusCode, unreadable.Err)
|
|
332
|
+
case errors.As(r.Err, &failed):
|
|
333
|
+
return fmt.Sprintf("answered %d: %s", failed.StatusCode, failed.Key)
|
|
334
|
+
}
|
|
335
|
+
return r.Err.Error()
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
### The Rust SDK
|
|
340
|
+
|
|
341
|
+
Async over `reqwest`, each call taking its options struct, with the safe mirror as a second client style.
|
|
342
|
+
|
|
343
|
+
```sh
|
|
344
|
+
honey-clients generate --spec openapi.json --target rust --out generated --rust-crate-name shop-sdk
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
```rust
|
|
348
|
+
async fn listing(client: &Client) -> String {
|
|
349
|
+
match client.safe().get_api(&GetApiOpts::default()).await {
|
|
350
|
+
Ok(Answer::Ok { data, response }) => format!("answered {}: {data:?}", response.status),
|
|
351
|
+
Ok(Answer::Err {
|
|
352
|
+
error: SafeError::Api(failed),
|
|
353
|
+
response,
|
|
354
|
+
}) => format!("answered {}: {}", response.status, failed.message()),
|
|
355
|
+
Ok(Answer::Err {
|
|
356
|
+
error: SafeError::Decode(unreadable),
|
|
357
|
+
response,
|
|
358
|
+
}) => format!("answered {}, unreadable: {unreadable}", response.status),
|
|
359
|
+
Err(no_answer) => format!("no answer: {no_answer}"), // never sent, refused, timed out or canceled
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
### The Python SDK
|
|
365
|
+
|
|
366
|
+
A sync `SDK` and an async `AsyncSDK`, both context managers, typed for `mypy --strict`, with results as frozen
|
|
367
|
+
dataclasses to narrow with `match`.
|
|
368
|
+
|
|
369
|
+
```sh
|
|
370
|
+
honey-clients generate --spec openapi.json --target python --out generated --python-package-name shop_sdk
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
`pyproject.toml` builds with hatchling and carries what PyPI shows: `--metadata-*` gives the description, the SPDX
|
|
374
|
+
`license` (PEP 639, so no `License ::` classifier), authors, keywords, and `[project.urls]` (Homepage, Source,
|
|
375
|
+
Issues, Documentation, Changelog). The classifiers name the Python versions honey tests and `Typing :: Typed`, and
|
|
376
|
+
honey's own manifest stays out of the sdist.
|
|
377
|
+
|
|
378
|
+
```python
|
|
379
|
+
async def health(client: AsyncSDK) -> str:
|
|
380
|
+
match await client.safe.get_api_health():
|
|
381
|
+
case Ok(data, response):
|
|
382
|
+
return f"answered {response.status}: {data}"
|
|
383
|
+
case Err(DecodeError() as unreadable, response):
|
|
384
|
+
return f"answered {response.status}, unreadable: {unreadable}"
|
|
385
|
+
case Err(error, response):
|
|
386
|
+
return f"answered {response.status}: {error}"
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
### The C# SDK
|
|
390
|
+
|
|
391
|
+
A .NET project with its own `HttpClient` pipeline, `IAsyncDisposable` streams, and `client.Safe` answering
|
|
392
|
+
`Result<T>`.
|
|
393
|
+
|
|
394
|
+
```sh
|
|
395
|
+
honey-clients generate --spec openapi.json --target csharp --out generated --csharp-package-id Acme.Shop
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
nuget.org shows a package's description, authors, license and links: give them with `--csharp-description`,
|
|
399
|
+
`--csharp-authors`, `--csharp-license`, `--csharp-homepage` and `--csharp-repository`, and the `.csproj` carries them
|
|
400
|
+
into `dotnet pack`.
|
|
401
|
+
|
|
402
|
+
```csharp
|
|
403
|
+
public static async Task<string> Listing(HoneySdkClient client, string id)
|
|
404
|
+
{
|
|
405
|
+
var result = await client.Safe.GetApiAsync(id); // no answer (never sent, refused, timed out, canceled) still throws
|
|
406
|
+
return result.Match(
|
|
407
|
+
found => $"answered {result.Response.Status}: {found}",
|
|
408
|
+
error => error switch
|
|
409
|
+
{
|
|
410
|
+
DecodeException unreadable => $"answered {result.Response.Status}, unreadable: {unreadable.Message}",
|
|
411
|
+
ApiStatusException failed => $"answered {failed.Status}: {failed.Key}",
|
|
412
|
+
_ => error.Message,
|
|
413
|
+
});
|
|
414
|
+
}
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
### The Java SDK
|
|
418
|
+
|
|
419
|
+
A Java 17 library on Jackson 3, with builders, `try`-with-resources streams, `client.safe()` answering a sealed
|
|
420
|
+
`Result<T>`, and a Gradle publication.
|
|
421
|
+
|
|
422
|
+
```sh
|
|
423
|
+
honey-clients generate --spec openapi.json --target java --out generated --java-group-id com.acme
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
Maven Central refuses a POM without a URL, a license, a developer and scm: give them with `--java-homepage`,
|
|
427
|
+
`--java-license`, `--java-developers "Name <email>, Other Name"` and `--java-repository`, or once for every target in
|
|
428
|
+
the metadata block, whose authors are the POM's developers. Signing the publication stays yours.
|
|
429
|
+
|
|
430
|
+
```java
|
|
431
|
+
static String listing(KitchenClient client) {
|
|
432
|
+
// no answer (never sent, refused, timed out, canceled) still throws
|
|
433
|
+
Result<ListApiResponse200> result = client.safe().getApi(GetApiParams.builder().build());
|
|
434
|
+
int status = result.response().status();
|
|
435
|
+
return result.fold(
|
|
436
|
+
found -> "answered " + status + ": " + found,
|
|
437
|
+
error ->
|
|
438
|
+
error instanceof ApiException failed
|
|
439
|
+
? "answered " + status + ": " + failed.key()
|
|
440
|
+
: "answered " + status + ", unreadable: " + error.getMessage());
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
## Errors and the safe mirror
|
|
445
|
+
|
|
446
|
+
Two styles, in all six SDKs, over the same calls:
|
|
447
|
+
|
|
448
|
+
- **The normal call** answers its value and throws on any failure: an error status as its typed error
|
|
449
|
+
(`NotFoundError` and so on, each a `ClientError`), and an undecodable or over-cap 2xx as a `DecodeError`.
|
|
450
|
+
- **`client.safe`** holds the same calls, each answering a result. On `ok` it carries the data, the raw response, and
|
|
451
|
+
the declared response headers when the operation has any. Otherwise it carries the error the normal call would have
|
|
452
|
+
thrown, with the parsed body on it. A declared status narrows the error's type and body; any other status is the
|
|
453
|
+
base client error with an `unknown` body.
|
|
454
|
+
- **No answer throws in both styles.** A call never sent, a refused or dropped connection, a timeout, a cancel, and a
|
|
455
|
+
stream that drops after it opened are not answers, so there is nothing for a result to carry.
|
|
456
|
+
|
|
457
|
+
A name of yours that collides with the mirror, or with a runtime type, is renamed and reported on stderr — never
|
|
458
|
+
silently. An operation or root resource named `safe` becomes `safe_`, and a component named like one of the runtime
|
|
459
|
+
types becomes `<Name>Model`.
|
|
460
|
+
|
|
461
|
+
Full reference: [generated clients](https://github.com/workerstack/backend/blob/main/docs/client.md).
|
|
462
|
+
|
|
463
|
+
## The command-line client
|
|
464
|
+
|
|
465
|
+
`--target cli` writes a Go command-line client for the API: one command per operation, grouped by its dotted
|
|
466
|
+
`operationId`, with `--help` everywhere, `commands` and `schema` for discovery, typed flags, table/JSON/NDJSON/YAML
|
|
467
|
+
output, streams, pagination, shell completion, and an embedded `SKILL.md` so an agent can drive it. It ships with a
|
|
468
|
+
release workflow, which can publish to Homebrew, Scoop, winget, AUR and deb/rpm/apk packages, and, with `--cli-repo`,
|
|
469
|
+
install scripts that verify what they install.
|
|
470
|
+
|
|
471
|
+
```sh
|
|
472
|
+
honey-clients generate --spec openapi.json --target cli --out ./cli --cli-repo acme/shop-cli
|
|
473
|
+
shop orders list --status open --output json
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
| Value | Default | What it does |
|
|
477
|
+
| ------------------------------------------------------------------- | --------------- | ---------------------------------------------------- |
|
|
478
|
+
| a command per operation | — | grouped by the dotted operationId resource tree |
|
|
479
|
+
| `--json` | off | one machine-readable shape on every command |
|
|
480
|
+
| `--output <json\|ndjson\|yaml\|table>` | table | human and machine formats |
|
|
481
|
+
| `--api-key` / `--base-url` / `--config` / `--timeout` / `--verbose` | from config/env | auth, target, config file, deadline, logging |
|
|
482
|
+
| `commands`, `schema` | — | a listable command index and per-call schemas |
|
|
483
|
+
| `--output <file>` | stdout | a binary response written as bytes, pipe-safe |
|
|
484
|
+
| exit codes | usage/standard | non-zero on usage error, distinct from a runtime one |
|
|
485
|
+
|
|
486
|
+
Its configuration has one precedence, everywhere: **flag, then environment, then config file.** The environment
|
|
487
|
+
variables are the `--cli-env-prefix` (or the API's name) upper-cased.
|
|
488
|
+
|
|
489
|
+
Full reference: [the generated CLI](https://github.com/workerstack/backend/blob/main/docs/cli.md) and
|
|
490
|
+
[releasing it](https://github.com/workerstack/backend/blob/main/docs/cli-release.md).
|
|
491
|
+
|
|
492
|
+
## The MCP server
|
|
493
|
+
|
|
494
|
+
`--target mcp` writes a standalone Model Context Protocol server: one tool per operation marked for MCP, its
|
|
495
|
+
`inputSchema` from the operation's parameters and body, an `outputSchema` from its success response, and
|
|
496
|
+
`structuredContent` an agent reads as data beside a text rendering. A failure comes back as a tool error with its
|
|
497
|
+
status and key, never as a successful result. Read-only operations are annotated as such. It speaks stdio by
|
|
498
|
+
default, and Streamable HTTP with `--http`.
|
|
499
|
+
|
|
500
|
+
```sh
|
|
501
|
+
honey-clients generate --spec openapi.json --target mcp --out ./mcp --mcp-name acme
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
Its package publishes to npm as written. `--mcp-package-name @acme/shop-mcp` names it (its bin keeps the server's
|
|
505
|
+
name), the metadata block fills its description, license, repository and the rest as it does the TS SDK's, and
|
|
506
|
+
`--mcp-mcp-name io.github.acme/shop` writes the `mcpName` the MCP registry checks the npm package by. With it the
|
|
507
|
+
server also gets the `server.json` that `mcp-publisher publish` reads from the package's root, on the registry's
|
|
508
|
+
2025-12-11 schema: that name, the description (100 characters at most, else refused), the version npm publishes, the
|
|
509
|
+
npm package over stdio with every environment variable the server reads, the home page as `websiteUrl`, and a GitHub
|
|
510
|
+
or GitLab repository. Where a hosted server runs is yours, so it lists no `remotes`.
|
|
511
|
+
|
|
512
|
+
```json
|
|
513
|
+
{
|
|
514
|
+
"name": "orders_get",
|
|
515
|
+
"inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] },
|
|
516
|
+
"outputSchema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } }
|
|
517
|
+
}
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
The server reads its configuration from the environment, under the `--mcp-env-prefix` (or the document's title,
|
|
521
|
+
upper-cased):
|
|
522
|
+
|
|
523
|
+
| Variable | Default | What it does |
|
|
524
|
+
| ---------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
525
|
+
| `$<PREFIX>_BASE_URL` | the document's first server | the API every call goes to |
|
|
526
|
+
| `$<PREFIX>_API_KEY` | none | the credential, sent as the document's scheme says; scrubbed from every result |
|
|
527
|
+
| `$<PREFIX>_HEADERS` | none | a JSON object of headers sent on every call, each scrubbed from results |
|
|
528
|
+
| `$<PREFIX>_REDIRECT` | `same-origin` | `same-origin`, or `follow` to follow a redirect off the API's origin with its credentials dropped |
|
|
529
|
+
| `$<PREFIX>_TIMEOUT_MS` | `30000` | each call's bound, an event stream's collect included |
|
|
530
|
+
| `$<PREFIX>_FILE_ROOT` | the client's working dir | the only directory a `{ path }` file argument is read from |
|
|
531
|
+
| `$<PREFIX>_MAX_FILE_BYTES` | `52428800` | the largest file a path may name |
|
|
532
|
+
| `$<PREFIX>_MAX_INLINE_BYTES` | `1048576` | all inline files of one call together, decoded |
|
|
533
|
+
| `$<PREFIX>_MCP_TOKEN` | none | the bearer token `--http` requires; it never reaches the API |
|
|
534
|
+
|
|
535
|
+
**The standalone server needs Node**: it holds a listening socket and reads local files, so it belongs on a machine
|
|
536
|
+
or a container, never on serverless or Workers. To serve the same tools remotely, mount them in the app instead with
|
|
537
|
+
`mcp()` from `@workerstack/backend/mcp`, which runs wherever the app runs and is guarded by the app's own auth.
|
|
538
|
+
|
|
539
|
+
Full reference: [the generated MCP server](https://github.com/workerstack/backend/blob/main/docs/mcp.md).
|
|
540
|
+
|
|
541
|
+
## Configuring generation
|
|
542
|
+
|
|
543
|
+
In a honey project the generation is configured once, in the Vite plugin, and `honey-clients generate --app` reads
|
|
544
|
+
the same app. `codegen.mcp` writes the handler `mcp()` mounts, and `codegen.openApi` the document the SDKs are
|
|
545
|
+
generated from:
|
|
546
|
+
|
|
547
|
+
```sh
|
|
548
|
+
# the whole set, from the app module, in one run
|
|
549
|
+
npx honey-clients generate --app src/app.ts \
|
|
550
|
+
--target ts --target go --target python --target cli --target mcp \
|
|
551
|
+
--go-module-path github.com/acme/shop/sdk --cli-repo acme/shop-cli --out generated
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
```json
|
|
555
|
+
{
|
|
556
|
+
"scripts": {
|
|
557
|
+
"generate": "honey generate && honey-clients generate --app src/app.ts --target ts --out generated"
|
|
558
|
+
}
|
|
559
|
+
}
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
What each target names its package, its client class and its environment variables is the `--<target>-<option>` set
|
|
563
|
+
above; nothing is read from a config file of ours, so one command line is the whole input and a CI run cannot drift
|
|
564
|
+
from a developer's.
|
|
565
|
+
|
|
566
|
+
## What a run writes
|
|
567
|
+
|
|
568
|
+
**Stale files are deleted, edited ones kept.** Each `<out>/<target>` keeps `.honey-generated.json`: every file the
|
|
569
|
+
run wrote, with its sha256. A file is rewritten only when its bytes change, through a temp file renamed over it. A
|
|
570
|
+
regeneration deletes a file the last run wrote and this one does not (a `cli` target's old `<name>_cmds.go`, say),
|
|
571
|
+
unless it was edited since: that one is kept and named on stderr. A file the manifest never listed is never deleted,
|
|
572
|
+
nothing outside `<out>/<target>` is touched, and no symlink is followed. Without a manifest, nothing is deleted.
|
|
573
|
+
|
|
574
|
+
Every target is held to the same conformance grid: one shared scenario suite runs against a live reference server
|
|
575
|
+
for all eight targets, and each decoded answer and each request on the wire must match one expected table. A feature
|
|
576
|
+
that works in one SDK and breaks in another fails the grid.
|
|
577
|
+
|
|
578
|
+
To lay the files out yourself, `generated(run, document, ctx)` from `@workerstack/clients` returns each
|
|
579
|
+
target's `files` unwritten, each as its text but for the C# package's icon, which is its bytes, and its `packages`:
|
|
580
|
+
the package on each registry it publishes to, as `{ registry, name, version }` (`npm` and `jsr` for a scoped TS SDK,
|
|
581
|
+
`npm` and `mcp-registry` for an MCP server with an `mcpName`, `pypi`, `crates.io`, `nuget`, `maven-central` as
|
|
582
|
+
`group:artifact`, and `go` by the module path, its `/vN` included and no version when none is given).
|
|
583
|
+
`writeTarget(dir, files, packages)` writes one target's into a directory you pick under the same rules, keeping
|
|
584
|
+
`MANIFEST` (`.honey-generated.json`) there with the packages recorded beside the files, so a release reads each name
|
|
585
|
+
and version from it. A file the last call wrote that you leave out of `files` is stale: deleted if unedited, kept and
|
|
586
|
+
named in the result's `kept` if you changed it, and dropped from the manifest either way, so a file you take over by
|
|
587
|
+
editing is never touched again.
|
|
588
|
+
|
|
589
|
+
A run kept as data (a release manifest, say) is checked with the same tables the command parses. `TARGETS` lists
|
|
590
|
+
every target, and `targetOptionSchemas[target]` is a Standard Schema for that target's options: its option names only,
|
|
591
|
+
each a non-empty string, a switch `"true"` or `"false"`. `generated` checks each target's options with it before
|
|
592
|
+
anything generates, and `GenerateRun` types them by target, so a misspelled option is a type error, then a refusal.
|
|
593
|
+
`GenerateRun`'s `metadata` is the `--metadata-<field>` block as a `Metadata` object, `authors` and `keywords` as
|
|
594
|
+
arrays, checked with the same rules.
|
|
595
|
+
|
|
596
|
+
```ts
|
|
597
|
+
import { TARGETS, targetOptionSchemas } from "@workerstack/clients"
|
|
598
|
+
|
|
599
|
+
const result = targetOptionSchemas.go["~standard"].validate({ modulePath: "github.com/acme/shop-go" })
|
|
600
|
+
export const ok = result.issues === undefined && TARGETS.includes("go")
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
This package also exports the app-side generators the honey CLI and Vite plugin use: `generateRouteTree`,
|
|
604
|
+
`generateTypes` and `extractTypes` from `@workerstack/clients`, and the command's own entry at
|
|
605
|
+
`@workerstack/clients/cli`.
|
|
606
|
+
|
|
607
|
+
## Documentation
|
|
608
|
+
|
|
609
|
+
- [Code generation](https://github.com/workerstack/backend/blob/main/docs/codegen.md): every target and its options.
|
|
610
|
+
- [Generated clients](https://github.com/workerstack/backend/blob/main/docs/client.md) and their
|
|
611
|
+
[per-language recipes](https://github.com/workerstack/backend/blob/main/docs/sdk-recipes.md).
|
|
612
|
+
- [The generated CLI](https://github.com/workerstack/backend/blob/main/docs/cli.md),
|
|
613
|
+
[releasing it](https://github.com/workerstack/backend/blob/main/docs/cli-release.md), and
|
|
614
|
+
[the MCP server](https://github.com/workerstack/backend/blob/main/docs/mcp.md).
|
|
615
|
+
- [SDK conformance](https://github.com/workerstack/backend/blob/main/docs/conformance.md) and
|
|
616
|
+
[the framework itself](https://github.com/workerstack/backend/blob/main/packages/core/README.md).
|
|
617
|
+
|
|
618
|
+
## License
|
|
619
|
+
|
|
620
|
+
MIT
|