@withgateway/sdk 0.3.1 → 0.4.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 (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  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 +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -26,7 +26,6 @@ body the document's example does not supply.
26
26
 
27
27
  from __future__ import annotations
28
28
 
29
- import base64
30
29
  import json
31
30
  import threading
32
31
  import urllib.error
@@ -34,23 +33,25 @@ import urllib.parse
34
33
  import urllib.request
35
34
  from dataclasses import dataclass, field
36
35
  from pathlib import Path
37
- from typing import Any
36
+ from typing import Any, Literal
38
37
 
39
38
  from .._toml import tomllib
40
39
  from .api import WorldState, load_api_settings, serve
41
40
  from .connector import SPEC, Operation, load_spec
41
+ from .door import Door
42
42
  from .validation import fail
43
43
 
44
44
  PIN = "conform"
45
45
 
46
46
 
47
- # ---------------------------------------------------------------- the document
48
-
49
-
50
47
  def load_openapi(path: str | Path) -> dict:
51
48
  return parse_openapi(Path(path).read_text(encoding="utf-8"), str(path))
52
49
 
53
50
 
51
+ #: Word for word the TypeScript CLI's ``YAML_NEEDS_PYYAML`` (client.ts), which refuses before sending.
52
+ YAML_NEEDS_PYYAML = "Reading a YAML document needs PyYAML in the Python that runs the schema runtime: pip install pyyaml there, set GATEWAY_PYTHON to an interpreter that has it, or convert the document to JSON"
53
+
54
+
54
55
  def parse_openapi(text: str, name: str, *, location: str = "/conform/openapi") -> dict:
55
56
  """The one OpenAPI reader: YAML when the name says so or the text is not JSON,
56
57
  JSON otherwise. ``conform`` and ``schema init --from-openapi`` both read through
@@ -72,8 +73,8 @@ def _parse_json(text: str, name: str, location: str) -> Any:
72
73
  def _parse_yaml(text: str, name: str, location: str) -> Any:
73
74
  try:
74
75
  import yaml # optional at runtime; the SDK depends on it, the vendored server does not
75
- except ImportError: # pragma: no cover
76
- fail("conform", "Reading a YAML document needs PyYAML; convert it to JSON", location)
76
+ except ImportError:
77
+ fail("conform", YAML_NEEDS_PYYAML, location)
77
78
  try:
78
79
  return yaml.safe_load(text)
79
80
  except yaml.YAMLError as error:
@@ -118,9 +119,6 @@ def find_operation(document: dict, prefixes: list[str], operation: Operation) ->
118
119
  return None
119
120
 
120
121
 
121
- # ---------------------------------------------------------------- lenient validation
122
-
123
-
124
122
  class Checker:
125
123
  def __init__(self, document: dict):
126
124
  self.document = document
@@ -300,9 +298,6 @@ class Checker:
300
298
  return None
301
299
 
302
300
 
303
- # ---------------------------------------------------------------- the run
304
-
305
-
306
301
  @dataclass
307
302
  class Outcome:
308
303
  operation: str
@@ -311,7 +306,7 @@ class Outcome:
311
306
  documented: bool
312
307
  status: int | None = None
313
308
  expected: list[str] = field(default_factory=list)
314
- schema: str = "unchecked" # ok | violations | no-schema | unchecked
309
+ schema: Literal["ok", "violations", "no-schema", "unchecked"] = "unchecked"
315
310
  problems: list[str] = field(default_factory=list)
316
311
  request: dict = field(default_factory=dict)
317
312
 
@@ -346,27 +341,6 @@ class Report:
346
341
  return {"world": self.world, "summary": self.summary, "operations": [o.__dict__ for o in self.outcomes]}
347
342
 
348
343
 
349
- def _credentials(base: str, spec, settings) -> dict[str, str]:
350
- """Headers that get the conformance run through the world's own auth, using the pin."""
351
- if spec.scheme == "none":
352
- return {}
353
- if spec.scheme == "header":
354
- return {spec.auth_name or "": PIN}
355
- if spec.scheme == "bearer":
356
- return {"Authorization": f"Bearer {PIN}"}
357
- if spec.scheme == "basic":
358
- return {"Authorization": "Basic " + base64.b64encode(PIN.encode()).decode()}
359
- if spec.scheme == "query":
360
- return {}
361
- form = urllib.parse.urlencode(
362
- {"grant_type": "client_credentials", "client_id": "conform", "client_secret": PIN}
363
- ).encode()
364
- prefix = urllib.parse.urlsplit(spec.base_url).path.rstrip("/")
365
- request = urllib.request.Request(base + prefix + (settings.token_path or "/oauth/token"), data=form, method="POST")
366
- with urllib.request.urlopen(request, timeout=10) as reply:
367
- return {"Authorization": "Bearer " + json.loads(reply.read())["access_token"]}
368
-
369
-
370
344
  def request_samples(world: str | Path) -> dict[str, tuple[dict[str, str], Any]]:
371
345
  """Per operation, the ``[operations.api] sample_headers`` (header -> value) and
372
346
  ``sample_body`` (a table or array, sent as JSON) declared in ``connector.toml``.
@@ -415,9 +389,10 @@ def _hints(spec, settings) -> dict[str, tuple[str, str]]:
415
389
 
416
390
 
417
391
  def _first_value(rows: list[dict], path: str) -> Any:
392
+ parts = path[1:].split("/") if path.startswith("/") else path.split(".")
418
393
  for row in rows:
419
394
  found: Any = row
420
- for part in path.split("."):
395
+ for part in parts:
421
396
  found = found.get(part) if isinstance(found, dict) else None
422
397
  if found is not None and not isinstance(found, (dict, list)):
423
398
  return found
@@ -472,7 +447,7 @@ def conform(world: str | Path, openapi: list[str | Path], *, max_operations: int
472
447
  state: WorldState = server.world_state # type: ignore[attr-defined]
473
448
  outcomes: list[Outcome] = []
474
449
  try:
475
- headers = _credentials(base, spec, settings)
450
+ door = Door.of(spec, settings, PIN)
476
451
  for operation in list(spec.operations.values())[:max_operations]:
477
452
  located = None
478
453
  checker = None
@@ -489,8 +464,8 @@ def conform(world: str | Path, openapi: list[str | Path], *, max_operations: int
489
464
  responses = documented.get("responses") or {}
490
465
  outcome.expected = [code for code in responses if code.startswith("2")] or ["200"]
491
466
  args, params = _sample_args(operation, spec, settings, state, checker, documented)
492
- if spec.scheme == "query":
493
- params[spec.auth_name or ""] = PIN
467
+ headers, credential_query = door.present()
468
+ params.update(credential_query)
494
469
  path = operation.path
495
470
  for name, value in args.items():
496
471
  path = path.replace("{" + name + "}", urllib.parse.quote(value, safe=""))