@withgateway/sdk 0.3.0 → 0.3.3

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 (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  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 +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -0,0 +1,344 @@
1
+ """What the call log keeps of a request: everything but a credential.
2
+
3
+ A field is a credential by its dotted path (``card.number``, ``cards.*.number``,
4
+ ``newPassword``), its words split at case changes and separators with trailing
5
+ digits dropped (``password2``) and a plural parent read singular. A list item,
6
+ or a field named only for what it holds (:data:`NAMED_BY_HOLDER`: ``value``,
7
+ ``answer``, ``new``...), is named by the field it sits in, read singular
8
+ (``passwords.*``, Okta's ``credentials.password.value``):
9
+
10
+ * its last word is one of :data:`CREDENTIAL_WORDS`, or ends in one of
11
+ :data:`CREDENTIAL_SUFFIXES` (``newpassword``, ``accesstoken``);
12
+ * its last two words are one of :data:`CREDENTIAL_PAIRS`, or its last word ends
13
+ in one joined (``cardnumber``, ``licensekey``), or its holder's last word and
14
+ its own key are one (``security.answer``);
15
+ * the whole key is one of :data:`WHOLE_KEY_CREDENTIALS` (``pass``, ``auth``,
16
+ ``pan``), which elsewhere name other things (``boarding_pass``);
17
+ * it is a ``number``, ``no`` or ``pan`` under a ``card``.
18
+
19
+ A value is a credential by its shape, whatever its field: a provider key, an
20
+ AWS key id or a bearer header (:data:`~gatewaysdk.environment.secret_values.SECRET_VALUE`,
21
+ the browser recorder's rule), the further token shapes of
22
+ :data:`~gatewaysdk.environment.secret_values.SECRET_TOKEN`, a Basic
23
+ authorization value, and a Luhn-valid 13 to 19 digit number in a field named
24
+ only one of :data:`LUHN_KEYS` (an ``order_number`` is not one). Pagination
25
+ cursors (``pageToken``, ``nextToken``, ``syncToken``, Graph's ``$skiptoken``
26
+ and ``$deltatoken``) and NetSuite's payment authorizations (``amountPendingAuthorization``)
27
+ are kept (:data:`KEPT_PAIRS`, :data:`KEPT_SUFFIXES`).
28
+
29
+ Each string or number so named or shaped reads :data:`REDACTED`; the key stays,
30
+ so a grader can still ask whether it was sent. Booleans, nulls and every other
31
+ field are kept as sent, so a grader reads what the agent asked, with what
32
+ no reply can carry read as text: an unpaired surrogate as U+FFFD, a NaN or an
33
+ infinity as ``"NaN"``, ``"Infinity"``, ``"-Infinity"``. A query-auth world's own
34
+ credential parameter is dropped. A request holding more than
35
+ :data:`MAX_LOGGED_VALUES` values, keys and key parts, or :data:`MAX_LOGGED_CHARS`
36
+ characters of text, its keys included, is too large to keep
37
+ (:class:`RequestTooLarge`): its whole request shares one :class:`RequestBudget`.
38
+ """
39
+
40
+ from __future__ import annotations
41
+
42
+ import re
43
+ import urllib.parse
44
+ from dataclasses import dataclass, replace
45
+ from functools import cached_property
46
+ from typing import Any, Iterator
47
+
48
+ from ..secret_values import SECRET_TOKEN, SECRET_VALUE, basic_credentials
49
+ from .connector import PLACEHOLDER, Operation, Spec
50
+ from .handler_errors import carried_scalar
51
+
52
+ REDACTED = "[redacted]"
53
+ MAX_LOGGED_VALUES = 100_000
54
+ MAX_LOGGED_CHARS = 1 << 20
55
+
56
+ CREDENTIAL_WORDS = frozenset(
57
+ {
58
+ "password",
59
+ "passwd",
60
+ "passphrase",
61
+ "passcode",
62
+ "pwd",
63
+ "pw",
64
+ "secret",
65
+ "token",
66
+ "apikey",
67
+ "credential",
68
+ "credentials",
69
+ "authorization",
70
+ "bearer",
71
+ "jwt",
72
+ "cookie",
73
+ "pin",
74
+ "otp",
75
+ "totp",
76
+ "cvv",
77
+ "cvc",
78
+ "csc",
79
+ "ssn",
80
+ "esig",
81
+ "esign",
82
+ "esignature",
83
+ }
84
+ )
85
+ CREDENTIAL_SUFFIXES = (
86
+ "password",
87
+ "passwd",
88
+ "passphrase",
89
+ "passcode",
90
+ "secret",
91
+ "token",
92
+ "apikey",
93
+ "credential",
94
+ "credentials",
95
+ "authorization",
96
+ "cookie",
97
+ "esignature",
98
+ )
99
+ CREDENTIAL_PAIRS = frozenset(
100
+ {
101
+ ("api", "key"),
102
+ ("private", "key"),
103
+ ("secret", "key"),
104
+ ("access", "key"),
105
+ ("license", "key"),
106
+ ("encryption", "key"),
107
+ ("signing", "key"),
108
+ ("card", "number"),
109
+ ("card", "no"),
110
+ ("card", "num"),
111
+ ("cc", "number"),
112
+ ("cc", "num"),
113
+ ("pan", "number"),
114
+ ("pan", "no"),
115
+ ("credit", "card"),
116
+ ("security", "code"),
117
+ ("security", "answer"),
118
+ ("security", "number"),
119
+ ("security", "question"),
120
+ ("recovery", "answer"),
121
+ ("recovery", "question"),
122
+ ("pin", "code"),
123
+ ("pin", "number"),
124
+ ("pin", "block"),
125
+ ("pass", "code"),
126
+ ("pass", "phrase"),
127
+ ("otp", "code"),
128
+ ("mfa", "code"),
129
+ ("auth", "code"),
130
+ ("authorization", "code"),
131
+ ("verification", "code"),
132
+ ("password", "confirm"),
133
+ ("password", "confirmation"),
134
+ ("e", "sig"),
135
+ ("e", "sign"),
136
+ ("e", "signature"),
137
+ ("electronic", "signature"),
138
+ }
139
+ )
140
+ JOINED_PAIRS = tuple(first + second for first, second in CREDENTIAL_PAIRS)
141
+ WHOLE_KEY_CREDENTIALS = frozenset({"pass", "auth", "pan"})
142
+ CARD_FIELDS = frozenset({"number", "no", "pan"})
143
+ LUHN_KEYS = frozenset({"number", "no", "num", "card", "cc"})
144
+ NAMED_BY_HOLDER = frozenset({"*", "value", "answer", "current", "new", "old", "previous", "confirm", "confirmation"})
145
+ KEPT_PAIRS = frozenset(
146
+ {
147
+ ("page", "token"),
148
+ ("next", "token"),
149
+ ("sync", "token"),
150
+ ("continuation", "token"),
151
+ ("pending", "authorization"),
152
+ ("payment", "authorization"),
153
+ }
154
+ )
155
+ KEPT_SUFFIXES = (
156
+ "pagetoken",
157
+ "nexttoken",
158
+ "synctoken",
159
+ "continuationtoken",
160
+ "skiptoken",
161
+ "deltatoken",
162
+ "preauthorization",
163
+ )
164
+ _WORD = re.compile(r"[A-Z]?[a-z]+\d*|[A-Z]+\d*(?![a-z])|\d+")
165
+ _CARD_DIGITS = re.compile(r"^\d(?:[ -]?\d){12,18}$")
166
+
167
+
168
+ class RequestTooLarge(Exception):
169
+ """A request past the call log's budget: logged without its arguments."""
170
+
171
+
172
+ def _singular(word: str) -> str:
173
+ return word[:-1] if len(word) > 3 and word.endswith("s") and not word.endswith("ss") else word
174
+
175
+
176
+ def _words(field: str) -> list[str]:
177
+ stripped = (word.lower().rstrip("0123456789") for word in _WORD.findall(field))
178
+ return [word for word in stripped if word]
179
+
180
+
181
+ def _scalar(value: Any) -> bool:
182
+ return isinstance(value, (str, int, float)) and not isinstance(value, bool)
183
+
184
+
185
+ def _luhn(digits: str) -> bool:
186
+ total = 0
187
+ for index, digit in enumerate(reversed(digits)):
188
+ doubled = int(digit) * (2 if index % 2 else 1)
189
+ total += doubled - 9 if doubled > 9 else doubled
190
+ return total % 10 == 0
191
+
192
+
193
+ def _card_digits(text: str) -> bool:
194
+ return bool(_CARD_DIGITS.match(text)) and _luhn(re.sub(r"[ -]", "", text))
195
+
196
+
197
+ def _shaped_like_a_secret(value: Any) -> bool:
198
+ if not isinstance(value, str):
199
+ return False
200
+ return bool(SECRET_VALUE.match(value) or SECRET_TOKEN.search(value)) or basic_credentials(value)
201
+
202
+
203
+ @dataclass(frozen=True)
204
+ class FieldName:
205
+ """What a field's dotted path says about it (module docstring), built one
206
+ key at a time so a request is read in time linear in its size: the field's
207
+ last word and the word before it, whether a ``card`` comes earlier, its own
208
+ key, and the key it is held under when it is a list item or a field named
209
+ only for what it holds."""
210
+
211
+ last: str = ""
212
+ prior: str = ""
213
+ under_card: bool = False
214
+ segment: str = ""
215
+ held: str = ""
216
+
217
+ def child(self, key: str) -> FieldName:
218
+ name = self
219
+ for part in key.split("."):
220
+ name = name._part(part)
221
+ return name
222
+
223
+ def _part(self, part: str) -> FieldName:
224
+ lowered = part.lower()
225
+ if self.segment and lowered in NAMED_BY_HOLDER:
226
+ return replace(self, held=lowered)
227
+ words = _words(part)
228
+ if not words:
229
+ return replace(self, segment=lowered, held="")
230
+ earlier = [self.last, *words[:-1]] if self.last else words[:-1]
231
+ return FieldName(
232
+ last=words[-1],
233
+ prior=_singular(earlier[-1]) if earlier else "",
234
+ under_card=self.under_card or any(_singular(word) == "card" for word in earlier),
235
+ segment=lowered,
236
+ )
237
+
238
+ @cached_property
239
+ def credential(self) -> bool:
240
+ last = _singular(self.last) if self.held else self.last
241
+ pair = (self.prior, last)
242
+ if not last or pair in KEPT_PAIRS or last.endswith(KEPT_SUFFIXES):
243
+ return False
244
+ return (
245
+ last in CREDENTIAL_WORDS
246
+ or last.endswith(CREDENTIAL_SUFFIXES)
247
+ or pair in CREDENTIAL_PAIRS
248
+ or (last, self.held) in CREDENTIAL_PAIRS
249
+ or last.endswith(JOINED_PAIRS)
250
+ or self.segment in WHOLE_KEY_CREDENTIALS
251
+ or (last in CARD_FIELDS and self.under_card)
252
+ )
253
+
254
+ @cached_property
255
+ def holds_a_card_number(self) -> bool:
256
+ return (_singular(self.segment) if self.held else self.segment) in LUHN_KEYS
257
+
258
+ def redacts(self, value: Any) -> bool:
259
+ if self.credential or _shaped_like_a_secret(value):
260
+ return True
261
+ return self.holds_a_card_number and _card_digits(str(value))
262
+
263
+
264
+ ROOT = FieldName()
265
+
266
+
267
+ class RequestBudget:
268
+ """What one request may cost the call log: :data:`MAX_LOGGED_VALUES` values,
269
+ keys and key parts, and :data:`MAX_LOGGED_CHARS` characters of text, its
270
+ keys included, an integer counted by its bytes. Each is charged before it is read, so a request past it costs
271
+ no more than the budget; what it spent is what the logged entry holds, which
272
+ the call log charges to its own, per-session budget."""
273
+
274
+ def __init__(self) -> None:
275
+ self.values = MAX_LOGGED_VALUES
276
+ self.chars = MAX_LOGGED_CHARS
277
+
278
+ def spent(self) -> tuple[int, int]:
279
+ return MAX_LOGGED_VALUES - self.values, MAX_LOGGED_CHARS - self.chars
280
+
281
+ def spend(self, values: int, chars: int) -> None:
282
+ self.values -= values
283
+ self.chars -= chars
284
+ if self.values < 0 or self.chars < 0:
285
+ raise RequestTooLarge
286
+
287
+
288
+ def _size(value: Any) -> int:
289
+ """What a scalar holds beyond one value: a string's characters, an integer's bytes."""
290
+ if isinstance(value, str):
291
+ return len(value)
292
+ if isinstance(value, int) and not isinstance(value, bool):
293
+ return (value.bit_length() + 7) // 8
294
+ return 0
295
+
296
+
297
+ def _kept(value: Any, name: FieldName, budget: RequestBudget) -> Any:
298
+ budget.spend(1, _size(value))
299
+ if isinstance(value, dict):
300
+ return {carried_scalar(key): _kept(item, name.child(key), budget) for key, item in _keys(value, budget)}
301
+ if isinstance(value, list):
302
+ item_name = name.child("*")
303
+ return [_kept(item, item_name, budget) for item in value]
304
+ if _scalar(value) and name.redacts(value):
305
+ return REDACTED
306
+ return carried_scalar(value)
307
+
308
+
309
+ def _keys(value: dict, budget: RequestBudget) -> Iterator[tuple[str, Any]]:
310
+ for key, item in value.items():
311
+ text = str(key)
312
+ budget.spend(text.count(".") + 1, len(text))
313
+ yield text, item
314
+
315
+
316
+ class CallRedaction:
317
+ """The call log's redaction (module docstring), for one world: ``credential_param``
318
+ is a query-auth world's credential parameter, dropped from every logged query."""
319
+
320
+ def __init__(self, credential_param: str | None = None):
321
+ self.credential_param = credential_param
322
+
323
+ @classmethod
324
+ def of(cls, spec: Spec) -> CallRedaction:
325
+ return cls(spec.auth_name if spec.scheme == "query" else None)
326
+
327
+ @staticmethod
328
+ def value(value: Any, budget: RequestBudget | None = None) -> Any:
329
+ return _kept(value, ROOT, budget or RequestBudget())
330
+
331
+ def query(self, query_all: dict, budget: RequestBudget | None = None) -> dict:
332
+ kept = {k: (v[0] if len(v) == 1 else list(v)) for k, v in query_all.items() if k != self.credential_param}
333
+ return self.value(kept, budget)
334
+
335
+ def path(self, operation: Operation, path: str, args: dict) -> str:
336
+ """The request path as sent, or, when a path argument is a credential,
337
+ the operation's path with that segment :data:`REDACTED`."""
338
+ if not any(self.value({name: value}) != {name: value} for name, value in args.items()):
339
+ return path
340
+ return PLACEHOLDER.sub(lambda found: self._segment(found.group(1), args), operation.path)
341
+
342
+ def _segment(self, name: str, args: dict) -> str:
343
+ kept = self.value({name: args.get(name, "")})[name]
344
+ return REDACTED if kept == REDACTED else urllib.parse.quote(str(kept), safe="")
@@ -36,11 +36,19 @@ _MISSING = object()
36
36
  @dataclass(frozen=True)
37
37
  class FieldType:
38
38
  """One field as ``gateway worlds describe`` reports it: ``type`` is the JSON Schema
39
- type word(s) joined by ``" | "``, a ``$ref`` name, or None when the schema says nothing."""
39
+ type word(s) joined by ``" | "``, a ``$ref`` name, or None when the schema says nothing;
40
+ ``enum`` the values the schema allows, when it lists them."""
40
41
 
41
42
  name: str
42
43
  type: str | None
43
44
  required: bool
45
+ enum: tuple | None = None
46
+
47
+ def describe(self) -> dict:
48
+ described: dict = {"name": self.name, "type": self.type, "required": self.required}
49
+ if self.enum is not None:
50
+ described["enum"] = list(self.enum)
51
+ return described
44
52
 
45
53
 
46
54
  def _article(kind: str) -> str:
@@ -160,7 +168,7 @@ class RowCaster:
160
168
  return row
161
169
 
162
170
 
163
- #: Text cells as the untyped reader always made them: the text, or None for an empty cell.
171
+ #: The untyped reader: every cell as its text, or None for an empty cell.
164
172
  TEXT_CASTER = RowCaster([])
165
173
 
166
174
  EntityCasters = Callable[[str], "RowCaster | None"]
@@ -178,7 +186,6 @@ def _definition(world: dict, entity: Any) -> dict:
178
186
  if isinstance(ref, str) and ref.startswith("#/$defs/"):
179
187
  definition = (world.get("$defs") or {}).get(ref[len("#/$defs/") :])
180
188
  return definition if isinstance(definition, dict) else {}
181
- # An inline payload (`schema entity add --schema '{…}'`) declares its fields right here.
182
189
  if isinstance(schema, dict) and isinstance(schema.get("properties"), dict):
183
190
  return schema
184
191
  return {}
@@ -196,19 +203,39 @@ def _field_type(field_schema: Any) -> str | None:
196
203
  return kind if isinstance(kind, str) else None
197
204
 
198
205
 
206
+ def _field_enum(field_schema: Any, defs: dict) -> tuple | None:
207
+ if not isinstance(field_schema, dict):
208
+ return None
209
+ branches = field_schema.get("anyOf") or field_schema.get("oneOf")
210
+ if isinstance(branches, list):
211
+ return _branches_enum(branches, defs)
212
+ ref = field_schema.get("$ref")
213
+ target = defs.get(ref[len("#/$defs/") :]) if isinstance(ref, str) and ref.startswith("#/$defs/") else field_schema
214
+ values = target.get("enum") if isinstance(target, dict) else None
215
+ return tuple(values) if isinstance(values, list) else None
216
+
217
+
218
+ def _branches_enum(branches: list, defs: dict) -> tuple | None:
219
+ """A nullable enum (``anyOf: [{$ref: Enum}, {type: null}]``) allows the enum's values and null."""
220
+ values = [value for branch in branches for value in (_field_enum(branch, defs) or ())]
221
+ nullable = any(isinstance(branch, dict) and branch.get("type") == "null" for branch in branches)
222
+ return tuple(values) + ((None,) if nullable else ()) if values else None
223
+
224
+
199
225
  def world_fields(world: dict) -> dict[str, list[FieldType]]:
200
226
  """Every entity's fields as a world.json document declares them (the ``$defs`` entry its
201
227
  ``schema.$ref`` names, or an inline ``properties``), sorted by entity name — the field
202
228
  list ``gateway worlds describe`` reports and a CSV import casts by."""
203
229
  gateway = world.get("x-gateway") if isinstance(world, dict) else None
204
230
  entities = (gateway.get("entities") or {}) if isinstance(gateway, dict) else {}
231
+ defs = world.get("$defs") or {}
205
232
  fields: dict[str, list[FieldType]] = {}
206
233
  for name, entity in sorted(entities.items()):
207
234
  definition = _definition(world, entity)
208
235
  required = set(definition.get("required") or [])
209
236
  properties = definition.get("properties") or {}
210
237
  fields[name] = [
211
- FieldType(field_name, _field_type(field_schema), field_name in required)
238
+ FieldType(field_name, _field_type(field_schema), field_name in required, _field_enum(field_schema, defs))
212
239
  for field_name, field_schema in properties.items()
213
240
  ]
214
241
  return fields