@withgateway/sdk 0.3.3 → 0.6.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 (158) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +3005 -1401
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2996 -1392
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +128 -37
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +126 -35
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  19. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  20. package/dist/index.d.mts +4 -4
  21. package/dist/index.d.ts +4 -4
  22. package/dist/index.js +1078 -260
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +1040 -251
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/replay/index.d.mts +1 -1
  27. package/dist/replay/index.d.ts +1 -1
  28. package/dist/replay/index.js.map +1 -1
  29. package/dist/replay/index.mjs.map +1 -1
  30. package/dist/traces/index.js +125 -34
  31. package/dist/traces/index.js.map +1 -1
  32. package/dist/traces/index.mjs +123 -32
  33. package/dist/traces/index.mjs.map +1 -1
  34. package/dist/tracing/index.d.mts +1 -1
  35. package/dist/tracing/index.d.ts +1 -1
  36. package/dist/tracing/index.js +7 -1
  37. package/dist/tracing/index.js.map +1 -1
  38. package/dist/tracing/index.mjs +7 -1
  39. package/dist/tracing/index.mjs.map +1 -1
  40. package/dist/worlds/index.d.mts +819 -438
  41. package/dist/worlds/index.d.ts +819 -438
  42. package/dist/worlds/index.js +912 -236
  43. package/dist/worlds/index.js.map +1 -1
  44. package/dist/worlds/index.mjs +908 -232
  45. package/dist/worlds/index.mjs.map +1 -1
  46. package/package.json +1 -1
  47. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  48. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  49. package/runtime/gatewaysdk/environment/_world.py +82 -66
  50. package/runtime/gatewaysdk/environment/backing.py +20 -24
  51. package/runtime/gatewaysdk/environment/core.py +1 -16
  52. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  53. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  54. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  55. package/runtime/gatewaysdk/environment/schema/api.py +198 -474
  56. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  57. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  58. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  59. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  60. package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
  61. package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
  62. package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
  63. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  64. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  65. package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
  66. package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
  67. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  68. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  69. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  70. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
  71. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  72. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  75. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  76. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  77. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  78. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  81. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  82. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  83. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  84. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  85. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  87. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  88. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  89. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  90. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  91. package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
  92. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  93. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  94. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  95. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  96. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  97. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
  99. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
  112. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  113. package/runtime/gatewaysdk/environment/schema/local.py +32 -116
  114. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  115. package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
  116. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  117. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  118. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  119. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  120. package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
  121. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  122. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  123. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  124. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  125. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  126. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  127. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
  128. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  129. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
  130. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
  131. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  132. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
  133. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  134. package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
  135. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  136. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  137. package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
  138. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  139. package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
  140. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  141. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  142. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  143. package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
  144. package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
  145. package/runtime/gatewaysdk/environment/world.py +1 -1
  146. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  147. package/skills/agents/connector-template-author.md +5 -1
  148. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  149. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  150. package/skills/connector-schema-authoring/SKILL.md +50 -28
  151. package/skills/connector-schema-authoring/connector-worlds.md +282 -18
  152. package/skills/connector-schema-authoring/world-schema.md +7 -6
  153. package/skills/world-data-ingestion/ROWS.md +12 -8
  154. package/skills/world-data-ingestion/SKILL.md +20 -22
  155. package/skills/worlds-getting-started/SKILL.md +25 -25
  156. package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  157. package/skills/worlds-getting-started/references/gotchas.md +71 -7
  158. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -0,0 +1,238 @@
1
+ """A route request's body as a world reads it: one :class:`RequestBody` kind per
2
+ media type, decided in :meth:`RequestBody.of` alone.
3
+
4
+ ``fields`` is what a route reads, a handler's ``body`` and a declared route's
5
+ input: a JSON value; a form's fields, each name's first value; a multipart
6
+ form's fields, each name's first part, a file part read as ``{"filename",
7
+ "content_type", "size"}`` with its bytes in ``files``; a multipart/related
8
+ body's first part as JSON, the parts after it in ``files`` keyed ``"1"``,
9
+ ``"2"``... A body of any other type is an upload (``application/octet-stream``,
10
+ ``text/csv``, ``image/png``): its fields are its JSON when it is JSON, since
11
+ clients label JSON many ways, and else None, which a declared route refuses as
12
+ the vendor's 400 and a handler route reads as ``{}`` beside the bytes
13
+ (``ctx.raw``). JSON that does not parse under a JSON label, and a multipart
14
+ body that does not split, are None to every route. Every part is found in time
15
+ linear in the body; a body of more than :data:`MAX_PARTS` parts, or a part
16
+ whose headers pass :data:`MAX_PART_HEAD` bytes, does not split.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import json
22
+ import re
23
+ import urllib.parse
24
+ from abc import ABC, abstractmethod
25
+ from dataclasses import dataclass
26
+ from functools import cached_property
27
+ from typing import Any, ClassVar, Mapping
28
+
29
+ MAX_PARTS = 1000
30
+ MAX_PART_HEAD = 8 * 1024
31
+ _BOUNDARY = re.compile(r"""(?:^|;)\s*boundary=(?:"([^"\r\n]{1,70})"|([^\s;"]{1,70}))""", re.IGNORECASE)
32
+ _PARAM = re.compile(r""";\s*([A-Za-z0-9!#$%&'*+.^_`|~-]+)\s*=\s*("(?:[^"\\]|\\.)*"|[^;]*)""")
33
+ _CRLF = b"\r\n"
34
+
35
+
36
+ def json_value(raw: bytes) -> Any:
37
+ """``raw`` as JSON: ``{}`` when empty, None when it is not JSON."""
38
+ if not raw:
39
+ return {}
40
+ try:
41
+ return json.loads(raw.decode("utf-8"))
42
+ except (ValueError, RecursionError):
43
+ return None
44
+
45
+
46
+ def form_fields(raw: bytes) -> dict[str, str]:
47
+ """``raw`` as an ``application/x-www-form-urlencoded`` form, each name's first value."""
48
+ pairs = urllib.parse.parse_qs(raw.decode("utf-8", "replace"), keep_blank_values=True)
49
+ return {name: values[0] for name, values in pairs.items()}
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class Upload:
54
+ """One file a request carried: its name and type as the client gave them, and its bytes."""
55
+
56
+ filename: str | None
57
+ content_type: str | None
58
+ content: bytes
59
+
60
+ def described(self) -> dict:
61
+ return {"filename": self.filename, "content_type": self.content_type, "size": len(self.content)}
62
+
63
+
64
+ @dataclass(frozen=True)
65
+ class Part:
66
+ """One part of a multipart body: its headers, names lower-cased, and its bytes."""
67
+
68
+ headers: dict[str, str]
69
+ content: bytes
70
+
71
+ @cached_property
72
+ def disposition(self) -> dict[str, str]:
73
+ params = _PARAM.findall(";" + self.headers.get("content-disposition", "").partition(";")[2])
74
+ return {name.lower(): _unquoted(value.strip()) for name, value in params}
75
+
76
+ @property
77
+ def name(self) -> str | None:
78
+ return self.disposition.get("name")
79
+
80
+ @property
81
+ def is_file(self) -> bool:
82
+ return "filename" in self.disposition
83
+
84
+ def upload(self) -> Upload:
85
+ return Upload(self.disposition.get("filename"), self.headers.get("content-type"), self.content)
86
+
87
+ def field(self) -> Any:
88
+ return self.upload().described() if self.is_file else self.content.decode("utf-8", "replace")
89
+
90
+
91
+ def _unquoted(value: str) -> str:
92
+ quoted = len(value) > 1 and value[0] == value[-1] == '"'
93
+ return re.sub(r"\\(.)", r"\1", value[1:-1]) if quoted else value
94
+
95
+
96
+ def _part(chunk: bytes) -> Part | None:
97
+ """One part from what follows its delimiter: transport padding, a line break, its
98
+ headers and a blank line, then its bytes."""
99
+ padded = chunk.lstrip(b" \t")
100
+ if not padded.startswith(_CRLF):
101
+ return None
102
+ body = padded[2:]
103
+ if body.startswith(_CRLF):
104
+ return Part({}, body[2:])
105
+ head, separator, content = body.partition(_CRLF + _CRLF)
106
+ if not separator or len(head) > MAX_PART_HEAD:
107
+ return None
108
+ named = [line.partition(":") for line in head.decode("utf-8", "replace").split("\r\n")]
109
+ return Part({name.strip().lower(): value.strip() for name, _, value in named}, content)
110
+
111
+
112
+ def multipart_parts(raw: bytes, content_type: str) -> list[Part] | None:
113
+ """The parts of a multipart body labelled ``content_type``, or None when it does not split."""
114
+ found = _BOUNDARY.search(content_type)
115
+ if found is None:
116
+ return None
117
+ delimiter = _CRLF + b"--" + (found.group(1) or found.group(2)).encode("latin-1")
118
+ chunks = (_CRLF + raw).split(delimiter, MAX_PARTS + 2)
119
+ if not 2 < len(chunks) <= MAX_PARTS + 2 or not chunks[-1].startswith(b"--"):
120
+ return None
121
+ parts = [_part(chunk) for chunk in chunks[1:-1]]
122
+ return None if None in parts else parts
123
+
124
+
125
+ def _first_by_name(parts: list[Part]) -> dict[str, Part]:
126
+ named: dict[str, Part] = {}
127
+ for part in parts:
128
+ named.setdefault(part.name or "", part)
129
+ named.pop("", None)
130
+ return named
131
+
132
+
133
+ @dataclass(frozen=True)
134
+ class RequestBody(ABC):
135
+ """A request's body (module docstring): the bytes as sent and the label they came under."""
136
+
137
+ raw: bytes
138
+ content_type: str = ""
139
+ media: ClassVar[tuple[str, ...]] = ()
140
+ uploads: ClassVar[bool] = False
141
+
142
+ @staticmethod
143
+ def of(raw: bytes, headers: Mapping[str, str]) -> RequestBody:
144
+ """The kind ``headers``' content type names, a new one for every request: the one
145
+ place a body's kind is decided. An empty body is ``{}`` whatever its label."""
146
+ content_type = headers.get("content-type") or ""
147
+ media = content_type.partition(";")[0].strip().lower()
148
+ labelled = KINDS.get(media) or (UploadBody if media and not media.endswith("+json") else JsonBody)
149
+ return (labelled if raw else JsonBody)(raw, content_type)
150
+
151
+ @property
152
+ @abstractmethod
153
+ def fields(self) -> Any:
154
+ """What a route reads (module docstring), or None when the body cannot be read so."""
155
+
156
+ @property
157
+ def files(self) -> dict[str, Upload]:
158
+ """The files the body carried, by the field or position that names each."""
159
+ return {}
160
+
161
+ def fields_for(self, handler: bool) -> Any:
162
+ """What one route reads: :attr:`fields`, or for a handler route ``{}`` beside an
163
+ upload's bytes; None when the route cannot read it."""
164
+ return {} if self.fields is None and self.uploads and handler else self.fields
165
+
166
+
167
+ @dataclass(frozen=True)
168
+ class JsonBody(RequestBody):
169
+ media = ("application/json",)
170
+
171
+ @cached_property
172
+ def fields(self) -> Any:
173
+ return json_value(self.raw)
174
+
175
+
176
+ @dataclass(frozen=True)
177
+ class UploadBody(RequestBody):
178
+ uploads = True
179
+
180
+ @cached_property
181
+ def fields(self) -> Any:
182
+ return json_value(self.raw)
183
+
184
+
185
+ @dataclass(frozen=True)
186
+ class FormBody(RequestBody):
187
+ """A form, or JSON under a form's label: no form field starts with ``{`` or ``[``,
188
+ and some clients label every POST a form."""
189
+
190
+ media = ("application/x-www-form-urlencoded",)
191
+
192
+ @cached_property
193
+ def fields(self) -> Any:
194
+ return json_value(self.raw) if self.raw.lstrip().startswith((b"{", b"[")) else form_fields(self.raw)
195
+
196
+
197
+ @dataclass(frozen=True)
198
+ class MultipartFormBody(RequestBody):
199
+ media = ("multipart/form-data",)
200
+
201
+ @cached_property
202
+ def named(self) -> dict[str, Part] | None:
203
+ parts = multipart_parts(self.raw, self.content_type)
204
+ return None if parts is None else _first_by_name(parts)
205
+
206
+ @cached_property
207
+ def fields(self) -> Any:
208
+ return None if self.named is None else {name: part.field() for name, part in self.named.items()}
209
+
210
+ @property
211
+ def files(self) -> dict[str, Upload]:
212
+ return {name: part.upload() for name, part in (self.named or {}).items() if part.is_file}
213
+
214
+ def fields_for(self, handler: bool) -> Any:
215
+ """A form with a file reaches a handler alone: a declared route reads no file."""
216
+ return None if self.files and not handler else self.fields
217
+
218
+
219
+ @dataclass(frozen=True)
220
+ class MultipartRelatedBody(RequestBody):
221
+ media = ("multipart/related",)
222
+
223
+ @cached_property
224
+ def parts(self) -> list[Part]:
225
+ return multipart_parts(self.raw, self.content_type) or []
226
+
227
+ @cached_property
228
+ def fields(self) -> Any:
229
+ return json_value(self.parts[0].content) if self.parts else None
230
+
231
+ @property
232
+ def files(self) -> dict[str, Upload]:
233
+ return {str(index): part.upload() for index, part in enumerate(self.parts[1:], start=1)}
234
+
235
+
236
+ KINDS: dict[str, type[RequestBody]] = {
237
+ media: kind for kind in (JsonBody, FormBody, MultipartFormBody, MultipartRelatedBody) for media in kind.media
238
+ }