@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,210 @@
1
+ """A route its declaration answers alone: ``[operations.api]`` action ``read``,
2
+ ``create``, ``update`` or ``delete`` over the route's entity, no handler.
3
+
4
+ Its rows are the ones its filter selects: a declared ``filter``, else each path
5
+ segment naming a field of the entity, and for a read each query parameter naming
6
+ one. They are read through the store's selection (``WorldDatabase.select``), so a
7
+ keyed or related read decodes its page and never every row of the entity.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ from typing import TYPE_CHECKING, Any
14
+
15
+ from .database.matching import RowMatch, dig
16
+ from .envelope import Page, Paging, page_headers, single, wrap
17
+ from .validation import ContractError
18
+
19
+ if TYPE_CHECKING:
20
+ from .api import ApiContext, OperationSettings
21
+ from .connector import Operation
22
+
23
+
24
+ class MisdeclaredRoute(ContractError):
25
+ """A declared route that cannot answer the request it took: the world author's bug, answered
26
+ as one (the 400 a handler's bug gets), never as the contract refusing the caller's write."""
27
+
28
+
29
+ class DeclaredRoute:
30
+ """One request to a declared route; :meth:`answer` is its action's answer."""
31
+
32
+ def __init__(
33
+ self,
34
+ op: OperationSettings,
35
+ operation: Operation,
36
+ ctx: ApiContext,
37
+ args: dict[str, str],
38
+ query: dict[str, str],
39
+ body: Any,
40
+ ) -> None:
41
+ self.op = op
42
+ self.operation = operation
43
+ self.ctx = ctx
44
+ self.args = args
45
+ self.query = query
46
+ self.body = body
47
+ self.entity = operation.entity or ""
48
+
49
+ def answer(self) -> Any:
50
+ if not self.operation.entity:
51
+ return 501, {"error": "not_modelled", "operation": self.operation.name}
52
+ return ACTIONS[self.op.action](self)
53
+
54
+ def _create(self) -> Any:
55
+ return self.op.status, self._one(self.ctx.insert(self.entity, self._bound(self.body)))
56
+
57
+ def _read(self) -> Any:
58
+ match = self._match()
59
+ if self.op.single:
60
+ rows, _ = self.ctx.select(self.entity, match, limit=1)
61
+ return (
62
+ (self.op.status, single(rows[0], self.op.envelope, self.op.wrapper)) if rows else self.ctx.not_found()
63
+ )
64
+ paging = self._paging()
65
+ offset, limit = paging.window(self.query)
66
+ rows, total = self.ctx.select(self.entity, match, limit=limit, offset=offset)
67
+ page = Page.of(rows, total, offset, limit, paging.style)
68
+ settings = self.ctx.settings
69
+ body = wrap(
70
+ page,
71
+ settings,
72
+ self.op.envelope,
73
+ paging=paging,
74
+ link=self.ctx.page_link,
75
+ omit_done_cursor=settings.omits_done_cursor(self.op),
76
+ wrapper=self.op.wrapper,
77
+ )
78
+ return self.op.status, body, page_headers(page, settings, paging, self.ctx.page_link)
79
+
80
+ def _update(self) -> Any:
81
+ row = self._only()
82
+ if row is None:
83
+ return self.ctx.not_found()
84
+ written = self.ctx.update(self.entity, self.ctx.key_of(self.entity, row), self._bound(self.body, current=row))
85
+ return self.op.status, self._one(written)
86
+
87
+ def _delete(self) -> Any:
88
+ row = self._only()
89
+ if row is None:
90
+ return self.ctx.not_found()
91
+ self.ctx.delete(self.entity, self.ctx.key_of(self.entity, row))
92
+ return self.op.status, None
93
+
94
+ def _only(self) -> dict | None:
95
+ """The one row the route writes, or None when its filter selects none or several."""
96
+ rows, total = self.ctx.select(self.entity, self._match(), limit=1)
97
+ return rows[0] if total == 1 else None
98
+
99
+ def _match(self) -> RowMatch:
100
+ op, operation = self.op, self.operation
101
+ selection = op.filter or self._segment_filter()
102
+ if not selection and (op.action in ("update", "delete") or (op.single and operation.placeholders)):
103
+ raise MisdeclaredRoute(
104
+ "spec",
105
+ f"route {operation.name} finds its row by nothing: its path names no field of {self.entity} and it "
106
+ "declares no api.filter; map a path argument to a field with api.filter, or answer the route with "
107
+ 'action = "handler"',
108
+ schema_path=f"/operations/{operation.name}/api/filter",
109
+ )
110
+ filters = selection
111
+ if not op.filter and op.action == "read":
112
+ filters = {**self._query_field_filter(), **filters}
113
+ # Every value sent filters: ``status[]=a&status[]=b`` reads as either, never as a with b dropped.
114
+ values: dict[str, str | list[str]] = {
115
+ **{k: v for k, v in self.ctx.query_all.items() if k in operation.params or k in filters},
116
+ **self.args,
117
+ }
118
+ return RowMatch(filters, values, op.match or {})
119
+
120
+ def _segment_filter(self) -> dict[str, str]:
121
+ """The filter a route with no ``filter`` of its own implies: each ``{segment}`` of its
122
+ path that names a top-level field of its entity narrows to the rows carrying that value
123
+ (``GET /wallets/{id}``, ``GET /records/by-email/{email}``). A segment naming no field
124
+ (``/users/{userId}/labels``, a scope the caller must send) implies nothing; a declared
125
+ ``filter`` says it all itself. Twin: ``route_bindings.implied_filters``."""
126
+ fields = self.ctx.fields_of(self.entity)
127
+ return {name: name for name in self.operation.placeholders if name in fields}
128
+
129
+ def _query_field_filter(self) -> dict[str, str]:
130
+ """What a read route with no ``filter`` implies from its query string: each
131
+ parameter that names a top-level field of the entity narrows to rows carrying
132
+ that value (``GET /accounts?status=frozen``), the way every vendor's list
133
+ endpoint reads. Paging parameters and names the entity does not declare are
134
+ left to the pager and the handler."""
135
+ fields = self.ctx.fields_of(self.entity)
136
+ skipped = self.ctx.settings.paging.params
137
+ return {name: name for name in self.ctx.query_all if name in fields and name not in skipped}
138
+
139
+ def _paging(self) -> Paging:
140
+ default = self.ctx.settings.paging
141
+ if self.op.paging is None:
142
+ return default
143
+ return Paging(
144
+ self.op.paging, default.limit_param, default.offset_param, default.cursor_param, default.page_size
145
+ )
146
+
147
+ def _one(self, row: dict) -> Any:
148
+ """A written row answered the route's way: alone (at its own envelope), or as a list of one."""
149
+ if self.op.single:
150
+ return single(row, self.op.envelope, self.op.wrapper)
151
+ return wrap([row], self.ctx.settings, self.op.envelope, wrapper=self.op.wrapper)
152
+
153
+ def _bound(self, body: Any, current: dict | None = None) -> dict:
154
+ """The row a create or update writes: defaults, then the body (mapped or as-is), then generated fields."""
155
+ sent = body if isinstance(body, dict) else {}
156
+ row: dict = json.loads(json.dumps(self.op.defaults)) if current is None else {}
157
+ self._fill(row, sent, current)
158
+ if current is None:
159
+ self._generate(row)
160
+ return row
161
+
162
+ def _fill(self, row: dict, body: dict, current: dict | None) -> None:
163
+ if not self.op.body:
164
+ row.update(body)
165
+ return
166
+ for field_name, path in self.op.body.items():
167
+ value = dig(body, path)
168
+ if value is not None:
169
+ _assign(row, field_name, value, current)
170
+
171
+ def _generate(self, row: dict) -> None:
172
+ for field_name, kind in self.op.generate.items():
173
+ if row.get(field_name) is None:
174
+ row[field_name] = GENERATED[kind](self, field_name)
175
+
176
+ def _next_int(self, field_name: str) -> int:
177
+ existing = [r.get(field_name) for r in self.ctx.rows(self.entity)]
178
+ return max([v for v in existing if isinstance(v, int)] + [0]) + 1
179
+
180
+
181
+ ACTIONS = {
182
+ "read": DeclaredRoute._read,
183
+ "create": DeclaredRoute._create,
184
+ "update": DeclaredRoute._update,
185
+ "delete": DeclaredRoute._delete,
186
+ }
187
+ GENERATED = {
188
+ "uuid": lambda route, _field: route.ctx.uuid(),
189
+ "now": lambda route, _field: route.ctx.now(),
190
+ "int": DeclaredRoute._next_int,
191
+ }
192
+
193
+
194
+ def _assign(row: dict, target: str, value: Any, current: dict | None) -> None:
195
+ """Assign a dotted target (``attributes.note``), keeping the rest of a nested
196
+ object an update leaves alone."""
197
+ parts = target.split(".")
198
+ if len(parts) == 1:
199
+ row[target] = value
200
+ return
201
+ head = parts[0]
202
+ if head not in row:
203
+ base = current.get(head) if current else None
204
+ row[head] = json.loads(json.dumps(base)) if isinstance(base, dict) else {}
205
+ node = row[head]
206
+ for part in parts[1:-1]:
207
+ if not isinstance(node.get(part), dict):
208
+ node[part] = {}
209
+ node = node[part]
210
+ node[parts[-1]] = value