stitchkit 0.106.1 → 0.108.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/CHANGELOG.md +151 -0
  2. package/README.md +2 -0
  3. package/darwin-native.cjs +17 -4
  4. package/dist/agent-runtime/deferred-tool-types.d.ts +6 -27
  5. package/dist/agent-runtime/deferred-tool-types.d.ts.map +1 -1
  6. package/dist/browser/stream.d.ts +38 -12
  7. package/dist/browser/stream.d.ts.map +1 -1
  8. package/dist/entrypoints/agent-runtime/browser.js +2 -3
  9. package/dist/entrypoints/agent-runtime/coding-tools.js +6 -8
  10. package/dist/entrypoints/agent-runtime/harness.js +7 -11
  11. package/dist/entrypoints/agent-runtime/realtime.js +2 -3
  12. package/dist/entrypoints/agent-runtime/sandbox.js +6 -8
  13. package/dist/entrypoints/agent-runtime.d.ts +2 -1
  14. package/dist/entrypoints/agent-runtime.d.ts.map +1 -1
  15. package/dist/entrypoints/agent-runtime.js +20 -23
  16. package/dist/entrypoints/application/diagnostic-journal.js +3 -3
  17. package/dist/entrypoints/application/directory-inbox.js +8 -9
  18. package/dist/entrypoints/application/grammy.js +3 -3
  19. package/dist/entrypoints/application.js +7 -8
  20. package/dist/entrypoints/bin/upgrade-cli.d.ts +32 -0
  21. package/dist/entrypoints/bin/upgrade-cli.d.ts.map +1 -1
  22. package/dist/entrypoints/bin/upgrade-cli.js +451 -8
  23. package/dist/entrypoints/cli/publish.js +10 -11
  24. package/dist/entrypoints/cli.js +12 -16
  25. package/dist/entrypoints/contract.js +1 -1
  26. package/dist/entrypoints/files/packaging.d.ts +3 -1
  27. package/dist/entrypoints/files/packaging.d.ts.map +1 -1
  28. package/dist/entrypoints/files/packaging.js +171 -55
  29. package/dist/entrypoints/files.js +16 -16
  30. package/dist/entrypoints/index.d.ts +1 -1
  31. package/dist/entrypoints/index.d.ts.map +1 -1
  32. package/dist/entrypoints/index.js +47 -41
  33. package/dist/entrypoints/node.js +27 -29
  34. package/dist/entrypoints/observability.js +10 -12
  35. package/dist/entrypoints/process.js +2 -2
  36. package/dist/entrypoints/react.js +3 -4
  37. package/dist/entrypoints/remote.js +8 -9
  38. package/dist/entrypoints/server.js +48 -51
  39. package/dist/entrypoints/telegram/html.js +3 -3
  40. package/dist/entrypoints/telegram/screens.js +6 -6
  41. package/dist/entrypoints/telegram.d.ts +2 -0
  42. package/dist/entrypoints/telegram.d.ts.map +1 -1
  43. package/dist/entrypoints/telegram.js +344 -11
  44. package/dist/entrypoints/testing.d.ts +1 -0
  45. package/dist/entrypoints/testing.d.ts.map +1 -1
  46. package/dist/entrypoints/testing.js +138 -11
  47. package/dist/entrypoints/tools/connections.js +11 -11
  48. package/dist/entrypoints/tools/invoker.js +5 -9
  49. package/dist/entrypoints/tools/mcp.js +8 -14
  50. package/dist/entrypoints/tools.js +19 -25
  51. package/dist/entrypoints/tracking.js +3 -3
  52. package/dist/files/native-artifact.d.ts +14 -0
  53. package/dist/files/native-artifact.d.ts.map +1 -0
  54. package/dist/files/native-packaging-layout.d.ts +11 -2
  55. package/dist/files/native-packaging-layout.d.ts.map +1 -1
  56. package/dist/files/native-packaging-plugin.d.ts +53 -0
  57. package/dist/files/native-packaging-plugin.d.ts.map +1 -0
  58. package/dist/files/native-packaging.d.ts +44 -43
  59. package/dist/files/native-packaging.d.ts.map +1 -1
  60. package/dist/{index-v5ee8ath.js → index-1h2zv8rx.js} +10 -40
  61. package/dist/index-2kbysk9s.js +42 -0
  62. package/dist/{index-wbhdzxar.js → index-2s6fpehp.js} +5 -5
  63. package/dist/{index-ksfagmyz.js → index-4qh90tyw.js} +8 -8
  64. package/dist/{index-yvfk3y36.js → index-636mggad.js} +4 -3
  65. package/dist/{index-f199nfq5.js → index-6y9t2fwz.js} +7 -7
  66. package/dist/{index-w8etpm8j.js → index-9j2atjte.js} +1 -1
  67. package/dist/index-a5qr2rj6.js +26 -0
  68. package/dist/{index-azx12jgv.js → index-bh2ht9y5.js} +13 -7
  69. package/dist/{index-pz3y6b6g.js → index-cx2nh595.js} +3 -3
  70. package/dist/{index-2k91mewf.js → index-dm2fv45z.js} +9 -9
  71. package/dist/{index-9bskshe3.js → index-dwf0gymy.js} +10 -10
  72. package/dist/{index-qaqbdm7s.js → index-h7qms8f9.js} +8 -8
  73. package/dist/{index-drs41arz.js → index-ktjmgq9p.js} +1 -1
  74. package/dist/{index-916yh4e2.js → index-mep4sb48.js} +14 -14
  75. package/dist/{index-wdy68sh6.js → index-njs9gvrh.js} +17 -17
  76. package/dist/{index-1ptj98e0.js → index-nx49x0tw.js} +2 -2
  77. package/dist/{index-1pwwan01.js → index-p5kx5vqd.js} +214 -59
  78. package/dist/{index-sj28htvf.js → index-pvh3z03x.js} +1 -1
  79. package/dist/{index-r393tnfp.js → index-q6crhe1n.js} +4 -4
  80. package/dist/{index-dsnjzb62.js → index-t2bsd0hm.js} +1 -1
  81. package/dist/{index-4vsby8n8.js → index-w9mqgnz9.js} +1 -1
  82. package/dist/{index-z23rfxhj.js → index-xmgjtkvr.js} +1 -1
  83. package/dist/{index-e05cjgtf.js → index-xvj9h8yh.js} +28 -1
  84. package/dist/{index-gr5g3xfw.js → index-yz8x0hbx.js} +1 -1
  85. package/dist/{index-gxm9rc97.js → index-zrtrjkbf.js} +1 -1
  86. package/dist/internal/bounded-lines.d.ts +46 -2
  87. package/dist/internal/bounded-lines.d.ts.map +1 -1
  88. package/dist/internal/darwin-binding-error.d.ts +9 -1
  89. package/dist/internal/darwin-binding-error.d.ts.map +1 -1
  90. package/dist/internal/darwin-binding.d.ts.map +1 -1
  91. package/dist/internal/process-identity.d.ts.map +1 -1
  92. package/dist/internal/until-aborted.d.ts +9 -0
  93. package/dist/internal/until-aborted.d.ts.map +1 -0
  94. package/dist/internal/upgrade-affects.d.ts +58 -0
  95. package/dist/internal/upgrade-affects.d.ts.map +1 -0
  96. package/dist/internal/upgrade-plan.d.ts +20 -0
  97. package/dist/internal/upgrade-plan.d.ts.map +1 -1
  98. package/dist/internal/upgrade-usage.d.ts +61 -0
  99. package/dist/internal/upgrade-usage.d.ts.map +1 -0
  100. package/dist/telegram/bot-api.d.ts +10 -4
  101. package/dist/telegram/bot-api.d.ts.map +1 -1
  102. package/dist/telegram/broadcast.d.ts +2 -1
  103. package/dist/telegram/broadcast.d.ts.map +1 -1
  104. package/dist/telegram/not-dispatched.d.ts +26 -0
  105. package/dist/telegram/not-dispatched.d.ts.map +1 -0
  106. package/dist/telegram/operator-channel.d.ts +2 -1
  107. package/dist/telegram/operator-channel.d.ts.map +1 -1
  108. package/dist/telegram/send-failure.d.ts +4 -3
  109. package/dist/telegram/send-failure.d.ts.map +1 -1
  110. package/dist/telegram/transport-connect.d.ts +38 -0
  111. package/dist/telegram/transport-connect.d.ts.map +1 -0
  112. package/dist/telegram/transport.d.ts +43 -0
  113. package/dist/telegram/transport.d.ts.map +1 -0
  114. package/dist/telegram/webhook.d.ts +2 -1
  115. package/dist/telegram/webhook.d.ts.map +1 -1
  116. package/dist/testing/manual-clock.d.ts +82 -0
  117. package/dist/testing/manual-clock.d.ts.map +1 -0
  118. package/dist/tools/internal/surface-projector.d.ts +0 -7
  119. package/dist/tools/internal/surface-projector.d.ts.map +1 -1
  120. package/dist/tools/runtime-tool-declaration.d.ts +11 -0
  121. package/dist/tools/runtime-tool-declaration.d.ts.map +1 -1
  122. package/dist/tools/runtime-tool.d.ts +2 -3
  123. package/dist/tools/runtime-tool.d.ts.map +1 -1
  124. package/llms/files-packaging.txt +13 -6
  125. package/llms/process.txt +71 -15
  126. package/llms/stitchkit.2.txt +211 -628
  127. package/llms/stitchkit.txt +635 -10
  128. package/llms/telegram.txt +36 -3
  129. package/llms/testing.txt +47 -0
  130. package/llms/{upgrading-0.96.0-0.106.0.txt → upgrading-0.100.0-0.108.0.txt} +112 -144
  131. package/llms/{upgrading-0.37.0-0.53.0.txt → upgrading-0.37.0-0.58.0.txt} +209 -3
  132. package/llms/{upgrading-0.55.0-0.68.0.txt → upgrading-0.59.0-0.71.0.txt} +149 -209
  133. package/llms/{upgrading-0.69.0-0.95.0.txt → upgrading-0.72.0-0.99.0.txt} +137 -149
  134. package/llms/upgrading.txt +36 -4
  135. package/llms-full.txt +360 -39
  136. package/llms.txt +10 -10
  137. package/package.json +2 -1
  138. package/llms/stitchkit.3.txt +0 -177
  139. package/dist/{index-cazts87s.js → index-07dcf2yn.js} +3 -3
  140. package/dist/{index-n1nszyk0.js → index-7jvwrjqa.js} +3 -3
  141. package/dist/{index-cmzvhhtd.js → index-85qve8mq.js} +3 -3
  142. package/dist/{index-rpzewktb.js → index-fynr93w4.js} +3 -3
  143. package/dist/{index-37asdw3a.js → index-k7qdkh3n.js} +3 -3
  144. package/dist/{index-x7w1z6pf.js → index-q4hjtyye.js} +4 -4
  145. package/dist/{index-7n68nmc6.js → index-y3nemndz.js} +3 -3
  146. package/dist/{index-12zsej7b.js → index-y70v24cw.js} +3 -3
  147. package/dist/{index-pzb63z66.js → index-ykdcnq1f.js} +3 -3
package/llms.txt CHANGED
@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
9
9
  Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
10
10
 
11
11
  ## Entrypoint slices
12
- - **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 17.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 46.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
12
+ - **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 46.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 36.5 KB
13
13
  - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
14
14
  - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
15
15
  - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.2 KB
@@ -39,10 +39,10 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
39
39
  - **stitchkit/application/directory-inbox**: [llms/application-directory-inbox.txt](llms/application-directory-inbox.txt) 0.3 KB
40
40
  - **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.8 KB
41
41
  - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
42
- - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.7 KB
42
+ - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 33.6 KB
43
43
  - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.3 KB
44
44
  - **stitchkit/files**: [llms/files.txt](llms/files.txt) 5.5 KB
45
- - **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 30.1 KB
45
+ - **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 32.9 KB
46
46
  - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
47
47
  - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB
48
48
  - **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 16.8 KB
@@ -56,15 +56,15 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
56
56
  - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
57
57
  - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
58
58
  - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 2.6 KB
59
- - **stitchkit/process**: [llms/process.txt](llms/process.txt) 39.9 KB
60
- - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 2.8 KB
59
+ - **stitchkit/process**: [llms/process.txt](llms/process.txt) 43.3 KB
60
+ - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
61
61
 
62
62
  ## Upgrading slices
63
- - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
64
- - **Upgrading 0.96.0 → 0.106.0**: [llms/upgrading-0.96.0-0.106.0.txt](llms/upgrading-0.96.0-0.106.0.txt) 46.6 KB
65
- - **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
66
- - **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB
67
- - **Upgrading 0.37.0 → 0.53.0**: [llms/upgrading-0.37.0-0.53.0.txt](llms/upgrading-0.37.0-0.53.0.txt) 32.6 KB
63
+ - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.1 KB
64
+ - **Upgrading 0.100.0 → 0.108.0**: [llms/upgrading-0.100.0-0.108.0.txt](llms/upgrading-0.100.0-0.108.0.txt) 46.1 KB
65
+ - **Upgrading 0.72.0 → 0.99.0**: [llms/upgrading-0.72.0-0.99.0.txt](llms/upgrading-0.72.0-0.99.0.txt) 46.4 KB
66
+ - **Upgrading 0.59.0 → 0.71.0**: [llms/upgrading-0.59.0-0.71.0.txt](llms/upgrading-0.59.0-0.71.0.txt) 45.6 KB
67
+ - **Upgrading 0.37.0 → 0.58.0**: [llms/upgrading-0.37.0-0.58.0.txt](llms/upgrading-0.37.0-0.58.0.txt) 40.0 KB
68
68
 
69
69
  ## Guide (web)
70
70
  - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stitchkit",
3
- "version": "0.106.1",
3
+ "version": "0.108.0",
4
4
  "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
5
5
  "keywords": [
6
6
  "bun",
@@ -30,6 +30,7 @@
30
30
  "url": "https://github.com/max-listov/stitchkit/issues"
31
31
  },
32
32
  "type": "module",
33
+ "sideEffects": false,
33
34
  "engines": {
34
35
  "bun": ">=1.2.0",
35
36
  "node": ">=22"
@@ -1,177 +0,0 @@
1
- # stitchkit — stitchkit docs slice, part 3 of 3
2
-
3
- > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
4
- > `llms.txt` in this package.
5
-
6
- Parts of this slice:
7
- - `llms/stitchkit.txt`: Guide: Getting started (docs/guide/getting-started.md)
8
- - `llms/stitchkit.2.txt`: Guide: Typed client (docs/guide/client.md)
9
- - `llms/stitchkit.3.txt`: API reference: `stitchkit` (docs/api/reference.md)
10
-
11
- Also read:
12
- - see `llms/contract.txt` for the Contracts guide
13
- - see `llms/server.txt` for the Realtime guide
14
- - see `llms/server.txt` for the Auth & errors guide
15
-
16
- ==============================================================================
17
- # API reference: `stitchkit` (docs/api/reference.md)
18
- ==============================================================================
19
-
20
- ## `stitchkit`
21
-
22
- The browser-and-server entrypoint. Re-exports everything from
23
- [`stitchkit/contract`](#stitchkitcontract), plus the client and browser realtime.
24
-
25
- ### Client
26
-
27
- | Export | Kind | Summary |
28
- |--------|------|---------|
29
- | `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
30
- | `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
31
- | `createScopedClients` | function | build one registry routed by contract scope; arrays compose contracts into one namespace |
32
- | `createScopedUrlBuilders` | function | build one URL registry routed by contract scope; arrays compose contracts into one namespace |
33
- | `ScopeClientConfigs` | _type_ | per-scope routing configuration consumed by scoped clients and URL builders |
34
- | `ScopedClientRegistry` | _type_ | exact composed registry returned by `createScopedClients` |
35
- | `ScopedUrlBuilderRegistry` | _type_ | exact composed registry returned by `createScopedUrlBuilders` |
36
- | `ClientRegistryValue` | _type_ | one contract or a contract array composing one client namespace |
37
- | `ClientContract` | _type_ | HTTP-client-compatible contract value used by scoped registries |
38
- | `RegistryScope` | _type_ | contract-scope union inferred from a scoped client registry value |
39
- | `createUrlBuilder` | function | build synchronous browser-native URLs for all HTTP endpoints; body methods accept URL-bound args only — [guide](../guide/client.md#contract-url-builders) |
40
- | `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
41
- | `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
42
- | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
43
- | `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned adapters |
44
- | `ClientRequestOptions` | _type_ | per-call `{ signal?, onUploadProgress? }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
45
- | `UploadProgress` | _type_ | `{ sentBytes, totalBytes, attempt }` heard by `onUploadProgress`: bytes of the encoded body handed to the network, first `0`, last `totalBytes`, counted again on each transport retry — [guide](../guide/client.md#upload-progress) |
46
- | `uploadInChunks` | function | send a file larger than one request as `init` → parts → `finalize` through three calls the app owns; client-minted id, repeats of a part on a failure that may pass, `finalize` never repeated, cancel checked between parts, progress in file bytes — [guide](../guide/client.md#chunked-uploads) |
47
- | `ChunkedUploadConfig` / `ChunkedUploadStart` / `ChunkedUploadPart` / `ChunkedUploadProgress` | _type_ | the driver's file, part size, retries and three calls; what `init` declares; one part; progress `{ sentBytes, totalBytes, index, chunkCount, attempt }` |
48
- | `ChunkSource` | _type_ | what the driver reads a file through — `size` and `slice(start, end)`; a `Blob` is one, so is a platform file that is not (an Expo `File`), and a part's `bytes` is what its `slice` returns |
49
- | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
50
- | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
51
- | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
52
- | `createHttpClient` | function | the Ky-based HTTP transport; on Next.js SSR its first attempt stays request-memoizable while every retry is a distinct transport attempt — [guide](../guide/client.md#createhttpclient) |
53
- | `ApiError` | class | a non-2xx or client failure, with `code` / `status` / `details` / `hint`, optional readonly `traceId` from `x-request-id`, and standard `cause` preserving an injected transport failure |
54
- | `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the exact projection a `VALIDATION_ERROR` carries in `ApiError.details.issues`, so a caller renders one shape. Also on `stitchkit/server`; same name, one definition |
55
- | `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) — the element type of `details.issues`. Also on `stitchkit/server` |
56
- | `formatZodError` | function | a `ZodError` → a readable, field-summarised string. Also on `stitchkit/server` |
57
- | `HttpClient` | _type_ | the transport interface `createClient` builds on |
58
- | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
59
- | `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |
60
- | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
61
- | `RequestOptions` | _type_ | per-call options — params, timeout, response type, `onUploadProgress` |
62
- | `HeaderProvider` | _type_ | static or per-request headers |
63
- | `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
64
- | `ApiEventListener` | _type_ | an `ApiEvent` handler |
65
-
66
- ### Realtime (client) & streaming
67
-
68
- | Export | Kind | Summary |
69
- |--------|------|---------|
70
- | `createSocketIOClient` | function | low-level typed Socket.IO transport primitive — [guide](../guide/realtime.md#low-level-transport) |
71
- | `defineRealtimeContract` | function | Zod-first shared Socket.IO event contract — [guide](../guide/realtime.md#zod-first-event-contract) |
72
- | `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
73
- | `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
74
- | `createLiveStateController` | function | keep typed application state current across one source-owned snapshot/event generation with finite pre-snapshot buffering, generation fencing and explicit resync — [guide](../guide/realtime.md#snapshot--event-state-synchronization) |
75
- | `LiveStateController` | _type_ | renderer-neutral `start` / `resync` / `getSnapshot` / `subscribe` / `close` handle |
76
- | `LiveStateControllerConfig` | _type_ | typed source, reducer, explicit event/byte bounds, event sizing and isolated error hooks |
77
- | `LiveStateControllerSnapshot` / `LiveStateControllerStatus` | _types_ | current value plus phase, generation, buffer and application/duplicate/gap/refusal counters |
78
- | `LiveStateControllerStatusSchema` | schema | strict runtime validation for controller status metadata |
79
- | `LiveStatePhaseSchema` / `LiveStatePhase` | schema / _type_ | `idle`, `opening`, `live`, `resync-required`, `unavailable` or `closed` |
80
- | `LiveStateStopReasonSchema` / `LiveStateStopReason` | schema / _type_ | explicit gap, overflow, source loss, controller failure and bounded `controller-capacity` reasons |
81
- | `LiveStateEventDecision` | _type_ | provider-owned reducer result: applied state, duplicate or gap |
82
- | `LiveStateSource` / `LiveStateSourceOpenInput` / `LiveStateSourceOpenResult` | _types_ | host binding for one continuous snapshot/event boundary; transport retry and cursor semantics remain host-owned |
83
- | `LiveStateControllerError` / `LiveStateSubscriberError` | _types_ | isolated observer failure payloads that do not change source or subscriber truth |
84
- | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
85
- | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
86
- | `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON; blank keep-alives are skipped and `finalLine: 'require-newline'` can make the delimiter mandatory — [guide](../guide/client.md#ndjson) |
87
- | `resumableIterator` | function | re-open a long-lived stream from the last delivered cursor, with jittered backoff, a caller-owned terminal item and prompt abort — [guide](../guide/client.md#resumable-streams) |
88
- | `createBackoff` | function | exponential backoff with subtractive jitter as a value: `next()` / `reset()` |
89
- | `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
90
- | `ContractStreamFraming` / `ContractStreamCompletion` | _types_ | opt-in item-vs-envelope framing and terminal-vs-stream-end completion policies |
91
- | `StreamFinalLinePolicy` | _type_ | permissive or newline-required final NDJSON line policy |
92
- | `DEFAULT_CONTRACT_STREAM_FRAME_BYTES` | const | default maximum encoded contract-stream frame: 256 KiB |
93
- | `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
94
- | `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
95
- | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
96
- | `SocketEventMap` | _type_ | the shape of an event map |
97
- | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
98
- | `RealtimeClientOptions` | _type_ | transport options plus rejected-event and metadata-only acknowledged-request phase hooks for `createRealtimeClient` |
99
- | `BoundRealtimeClient` | _type_ | validated non-owning `on`/`emit`/`request` client with no `connect`/`disconnect` |
100
- | `RealtimeClientTransport` | _type_ | minimal existing transport capability accepted by `bindRealtimeClient` |
101
- | `BindRealtimeClientOptions` | _type_ | rejection/logger options for a bound existing transport |
102
- | `RealtimeAcknowledgedEvent` | _type_ | event-name union restricted to definitions with an `ack` schema |
103
- | `RealtimeAcknowledgement` | _type_ | validated acknowledgement output inferred from an event definition |
104
- | `RealtimeRequestArguments` | _type_ | request arguments inferred from an acknowledged event tuple |
105
- | `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` plus an optional invocation-scoped `onPhase` observer |
106
- | `RealtimeRequestPhaseSchema` / `RealtimeRequestPhase` | schema / _type_ | closed `engine-handoff` / `engine-ack-received` / `settled` / `timeout` / `disconnected` lifecycle |
107
- | `RealtimeRequestPhaseEventSchema` / `RealtimeRequestPhaseEvent` | schema / _type_ | strict metadata-only `{ requestId, event, phase, elapsedMs }` observation |
108
- | `RealtimeRequestPhaseHook` | _type_ | isolated sync/async observer accepted globally by `RealtimeClientOptions.onRequestPhase` or per invocation by `RealtimeRequestOptions.onPhase` |
109
- | `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
110
- | `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
111
- | `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
112
- | `RealtimeRequestRejectedError` | class | the peer refused the frame against its own contract and said so — `reason`, `issues` — instead of leaving the sender to time out ([ADR 0106](../decisions/0106-a-refused-frame-answers-its-sender.md)) |
113
- | `REALTIME_REJECTION_KEY` | const | the reserved acknowledgement key a refusal travels under |
114
- | `RealtimeRejectionEnvelope` | _type_ | the wire shape of a refusal |
115
- | `RealtimeRejectionReport` | _type_ | what the sender is told: event, reason, message, issues |
116
- | `RealtimeRejectionIssue` | _type_ | one refused field, already flattened (`path: '0.v'`) |
117
- | `asRealtimeRejection` | function | recognise a refusal in an acknowledgement value, validating it |
118
- | `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
119
- | `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
120
- | `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
121
- | `RealtimeEventArguments` | _type_ | tuple inferred from an event definition |
122
- | `RealtimeEmitArguments` | _type_ | emit arguments including an inferred acknowledgement callback |
123
- | `RealtimeEventHandler` | _type_ | handler inferred from an event definition |
124
- | `InferRealtimeEventMap` | _type_ | inferred Socket.IO-compatible event map |
125
- | `RealtimeRejectDirection` / `RealtimeRejectPhase` / `RealtimeRejectReason` / `RealtimeRejectFault` | _types_ | canonical inferred rejection direction, validation phase, reason and fault classification |
126
- | `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
127
- | `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
128
- | `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
129
- | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
130
- | `ParseSSEOptions` | _type_ | options for `parseSSE` |
131
- | `ParseNDJSONOptions` | _type_ | options for `parseNDJSON` |
132
- | `BackoffPolicySchema` / `BackoffPolicy` | schema / _type_ | `minDelayMs`, `maxDelayMs` and a `0`–`1` jitter fraction; a ceiling below the floor is refused |
133
- | `Backoff` | _type_ | the backoff handle returned by `createBackoff` |
134
- | `ResumableIteratorConfig` | _type_ | caller-owned `open` / `advance` / `isTerminal`, retry policy, abort signal and `onAttempt` observer |
135
- | `ResumableAttempt` | _type_ | attempt number, the delay about to be waited and the error that caused it |
136
-
137
- ### Trace (client)
138
-
139
- Browser-safe W3C trace helpers — the same functions as on
140
- [`stitchkit/observability`](#stitchkitobservability), re-exported so a client
141
- can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
142
-
143
- | Export | Kind | Summary |
144
- |--------|------|---------|
145
- | `createTraceContext` | function | a fresh root trace |
146
- | `formatTraceparent` | function | render a `traceparent` header value |
147
- | `parseTraceparent` | function | parse a `traceparent` header |
148
- | `childSpan` | function | a child span of a parent trace |
149
- | `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId?, tracestate?, baggage? }` |
150
-
151
- ---
152
-
153
- ### Session lifetime and credential coordination
154
-
155
- `createSessionScope` (`stitchkit`) returns the generic `SessionScope`: `replace(context)`
156
- creates a new login lifetime (including same-account relogin), `capture()` returns
157
- its `SessionOperation<T>`, `clear()` invalidates it, `stop()` permanently closes
158
- the host, and `owns(operation)` answers whether an operation is this scope's current
159
- one — `current()` alone cannot tell an operation of another scope. Operations expose `id`, `generation`, `context`, `signal`, `current()` and
160
- `assertCurrent()`. `run(callback)` checks both success and failure across an await;
161
- `deliver(callback)` admits a synchronous final send/state change or returns false.
162
- `bindFetch(fetch, headers?)` guards every attempt and scopes its abort signal. Wrap
163
- the complete client call in `run` too: headers are not the response body boundary.
164
- Expired work throws `SessionExpiredError`, not a refresh instruction; when the work
165
- itself failed, that failure is its `cause`.
166
-
167
- `createSessionCredentials` accepts `SessionCredentialsConfig`:
168
- `scope`, `refresh(credentials, signal)`, `storage.write(session, credentials)`,
169
- `storage.clear()`, `maxPendingWrites` (128), `refreshTimeoutMs` (30000, at most one
170
- hour) and `storageTimeoutMs` (30000, at most one hour): a storage call past it
171
- rejects and frees the queue, so `logout()` still clears; when the late call settles,
172
- storage is written again from memory, or cleared when nobody is logged in. `SessionCredentials` provides `login`, `logout`, `read(operation)` and
173
- `refresh(operation)`. Concurrent refresh calls in one generation share the same
174
- promise. Logout invalidates memory before its returned persistence promise settles.
175
- Storage errors and queue-capacity refusals reject; callers must handle them. All
176
- writes must pass through the same instance. There is no cross-process/tab lock,
177
- provider error classifier or automatic retry of arbitrary application callbacks.
@@ -1,12 +1,12 @@
1
- import {
2
- stagingPath
3
- } from "./index-j4zh647a.js";
4
1
  import {
5
2
  closeAfter,
6
3
  closeAfterSync,
7
4
  publishAtomicFile,
8
5
  publishAtomicFileSync
9
6
  } from "./index-b56nnscm.js";
7
+ import {
8
+ stagingPath
9
+ } from "./index-j4zh647a.js";
10
10
 
11
11
  // src/internal/atomic-file.ts
12
12
  import { closeSync, fchmodSync, fsyncSync, openSync, unlinkSync, writeSync } from "node:fs";
@@ -1,10 +1,10 @@
1
+ import {
2
+ ApiError2
3
+ } from "./index-kfjkb396.js";
1
4
  import {
2
5
  createTraceContext2,
3
6
  formatTraceparent2
4
7
  } from "./index-yex7eg1v.js";
5
- import {
6
- ApiError2
7
- } from "./index-kfjkb396.js";
8
8
  import {
9
9
  isRecord,
10
10
  transportResult
@@ -1,9 +1,9 @@
1
- import {
2
- AppError2
3
- } from "./index-j9gxbztg.js";
4
1
  import {
5
2
  contractMethodFields
6
3
  } from "./index-1bx1xv1k.js";
4
+ import {
5
+ AppError2
6
+ } from "./index-j9gxbztg.js";
7
7
  import {
8
8
  typedEntries,
9
9
  callRuntimeHandler
@@ -1,10 +1,10 @@
1
- import {
2
- AppError2
3
- } from "./index-j9gxbztg.js";
4
1
  import {
5
2
  zodIssues2,
6
3
  formatZodError2
7
4
  } from "./index-1eeqpadm.js";
5
+ import {
6
+ AppError2
7
+ } from "./index-j9gxbztg.js";
8
8
  import {
9
9
  isRecord
10
10
  } from "./index-9jfdm5tg.js";
@@ -1,6 +1,3 @@
1
- import {
2
- unauthorized2
3
- } from "./index-j9gxbztg.js";
4
1
  import {
5
2
  deriveCodeChallenge2
6
3
  } from "./index-ap3gqe56.js";
@@ -8,6 +5,9 @@ import {
8
5
  bytesToBase64Url,
9
6
  base64UrlToBytes
10
7
  } from "./index-dwfv9a85.js";
8
+ import {
9
+ unauthorized2
10
+ } from "./index-j9gxbztg.js";
11
11
  import {
12
12
  safeJsonParse
13
13
  } from "./index-zsarb5xp.js";
@@ -1,15 +1,15 @@
1
1
  import {
2
2
  defineContract2
3
3
  } from "./index-fsw1ybf3.js";
4
+ import {
5
+ bytesToBase64Url,
6
+ base64UrlToBytes
7
+ } from "./index-dwfv9a85.js";
4
8
  import {
5
9
  AppError2,
6
10
  STITCH_ERROR_STATUS2,
7
11
  isStitchErrorCode2
8
12
  } from "./index-j9gxbztg.js";
9
- import {
10
- bytesToBase64Url,
11
- base64UrlToBytes
12
- } from "./index-dwfv9a85.js";
13
13
  import {
14
14
  typedEntries,
15
15
  transportResult,
@@ -1,10 +1,10 @@
1
- import {
2
- resolveTraceContext2
3
- } from "./index-yex7eg1v.js";
4
1
  import {
5
2
  resolveSocketIp2,
6
3
  getClientInfo2
7
4
  } from "./index-kw1ws0cs.js";
5
+ import {
6
+ resolveTraceContext2
7
+ } from "./index-yex7eg1v.js";
8
8
  import {
9
9
  isUnsafeKey
10
10
  } from "./index-zsarb5xp.js";
@@ -1,6 +1,3 @@
1
- import {
2
- AppError2
3
- } from "./index-j9gxbztg.js";
4
1
  import {
5
2
  ShutdownOptionsSchema2
6
3
  } from "./index-q0th8q0z.js";
@@ -12,6 +9,9 @@ import {
12
9
  import {
13
10
  managedResourceDependencyId2
14
11
  } from "./index-50ejfz75.js";
12
+ import {
13
+ AppError2
14
+ } from "./index-j9gxbztg.js";
15
15
 
16
16
  // src/application/kernel-contract.ts
17
17
  import { z } from "zod";
@@ -1,6 +1,3 @@
1
- import {
2
- AppError2
3
- } from "./index-j9gxbztg.js";
4
1
  import {
5
2
  RealtimeRequestInvalidAcknowledgementError2,
6
3
  RealtimeRequestRejectedError2
@@ -8,6 +5,9 @@ import {
8
5
  import {
9
6
  zodIssues2
10
7
  } from "./index-1eeqpadm.js";
8
+ import {
9
+ AppError2
10
+ } from "./index-j9gxbztg.js";
11
11
 
12
12
  // src/realtime/rejected-frame.ts
13
13
  var REALTIME_REJECTION_KEY2 = "@stitchkit/realtime-rejected";