@withgateway/sdk 0.2.6 → 0.2.9

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 (110) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +15468 -11263
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +15233 -11028
  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 +291 -40
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +284 -37
  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 +203 -47
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +198 -42
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
  19. package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
  20. package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
  21. package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
  22. package/dist/index.d.mts +3 -3
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.js +2149 -615
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2053 -566
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/traces/index.js +268 -31
  29. package/dist/traces/index.js.map +1 -1
  30. package/dist/traces/index.mjs +262 -28
  31. package/dist/traces/index.mjs.map +1 -1
  32. package/dist/tracing/index.js +19 -11
  33. package/dist/tracing/index.js.map +1 -1
  34. package/dist/tracing/index.mjs +19 -11
  35. package/dist/tracing/index.mjs.map +1 -1
  36. package/dist/worlds/index.d.mts +886 -117
  37. package/dist/worlds/index.d.ts +886 -117
  38. package/dist/worlds/index.js +1770 -452
  39. package/dist/worlds/index.js.map +1 -1
  40. package/dist/worlds/index.mjs +1752 -434
  41. package/dist/worlds/index.mjs.map +1 -1
  42. package/package.json +14 -10
  43. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  44. package/runtime/gatewaysdk/environment/_world.py +95 -28
  45. package/runtime/gatewaysdk/environment/runtime.py +10 -6
  46. package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
  47. package/runtime/gatewaysdk/environment/schema/api.py +19 -23
  48. package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
  49. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
  50. package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
  51. package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
  52. package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
  53. package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
  54. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
  56. package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
  57. package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
  58. package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
  59. package/runtime/gatewaysdk/environment/schema/data.py +21 -5
  60. package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
  61. package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
  62. package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
  63. package/runtime/gatewaysdk/environment/schema/host.py +68 -115
  64. package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
  65. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
  66. package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
  67. package/runtime/gatewaysdk/environment/schema/local.py +7 -10
  68. package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
  69. package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
  70. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
  72. package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
  74. package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
  75. package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
  76. package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
  79. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
  80. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
  81. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
  83. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
  89. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  90. package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
  92. package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
  93. package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
  94. package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
  95. package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
  96. package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
  97. package/runtime/gatewaysdk/environment/world.py +42 -3
  98. package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
  99. package/skills/benchmarks-getting-started/SKILL.md +70 -22
  100. package/skills/connector-schema-authoring/SKILL.md +54 -4
  101. package/skills/connector-schema-authoring/connector-worlds.md +21 -7
  102. package/skills/connector-schema-authoring/world-schema.md +144 -83
  103. package/skills/hooks-getting-started/SKILL.md +27 -2
  104. package/skills/world-data-ingestion/ROWS.md +62 -0
  105. package/skills/world-data-ingestion/SKILL.md +91 -54
  106. package/skills/worlds-getting-started/SKILL.md +146 -146
  107. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  108. package/skills/worlds-getting-started/references/gotchas.md +30 -0
  109. package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  110. package/skills/worlds-getting-started/references/openapi-import.md +90 -0
@@ -0,0 +1,382 @@
1
+ """``gateway worlds schema init <dir> --from-openapi <source>``: an OpenAPI or
2
+ Swagger document as a world.
3
+
4
+ :class:`OpenApiImport` owns the conversion; :class:`OpenApiWorldPlan` is what it
5
+ produces: the entities and routes it chose, the warnings, and the files
6
+ (``schema/world.json``, ``connector.toml``, ``schema/provenance.json``) it
7
+ renders from them. It writes nothing itself: ``init_bundle_from_files`` (the
8
+ one scaffold writer) takes the rendered files, validates and compiles the tree
9
+ and removes it whole when anything refuses, so a rejected import leaves no
10
+ directory behind. ``--plan-only`` stops at the plan.
11
+
12
+ Entities are the keyed object schemas the selected operations reach (through
13
+ their responses and request bodies, then every ``$ref`` from there); a spec
14
+ whose operations name no schema gets every keyed schema instead. A schema with
15
+ no key stays a ``$defs`` entry referenced inline. Keys, names and the shape
16
+ rules are in ``openapi_schemas``; routes in ``openapi_routes``.
17
+
18
+ Trust boundary: the source is read where the command runs (``openapi_source``:
19
+ a local file, or a public URL behind the private-address guard); a
20
+ ``drive:<path>`` is staged by the platform CLI before this code sees bytes. The
21
+ provenance file records the source label with credentials and query strings
22
+ removed, the document's version and title, its sha256 and the importer version.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import base64
28
+ import binascii
29
+ import json
30
+ import re
31
+ from dataclasses import dataclass, field
32
+ from pathlib import Path
33
+ from typing import Any
34
+
35
+ from .compiler import Contract
36
+ from .connector import SPEC
37
+ from .openapi_document import OpenApiDocument, OpenApiOperation
38
+ from .openapi_routes import Entity, OperationPlan, RoutePlanner, Selection, Skipped
39
+ from .openapi_schemas import EntityKey, Names, Namespace, SchemaConverter
40
+ from .openapi_source import OpenApiSource
41
+ from .scaffold import init_bundle_from_files
42
+ from .validation import DIALECT, MAX_ENTITY_NAME, fail
43
+
44
+ IMPORTER_VERSION = "1.0.0"
45
+ #: Template-relative, as ``init_bundle_from_files`` takes them; the scaffold lands
46
+ #: ``world.json`` and ``provenance.json`` under ``schema/``.
47
+ WORLD = "world.json"
48
+ PROVENANCE = "provenance.json"
49
+ _REF = re.compile(r'"\$ref":\s*"([^"]+)"')
50
+
51
+
52
+ @dataclass
53
+ class OpenApiWorldPlan:
54
+ """What an import will create, and the files that create it."""
55
+
56
+ source: OpenApiSource
57
+ document: OpenApiDocument
58
+ slug: str
59
+ entities: list[Entity]
60
+ operations: list[OperationPlan]
61
+ skipped: list[Skipped]
62
+ excluded: int
63
+ defs: dict[str, dict]
64
+ warnings: list[str] = field(default_factory=list)
65
+
66
+ # ------------------------------------------------------------- the plan
67
+
68
+ def summary(self) -> dict:
69
+ return {
70
+ "source": self.source.label,
71
+ "document": {"version": self.document.version, "title": self.document.title, "sha256": self.source.sha256},
72
+ "connector": self.slug,
73
+ "entities": [e.summary() for e in self.entities],
74
+ "operations": [o.summary() for o in self.operations],
75
+ "skipped": [s.summary() for s in self.skipped],
76
+ "excluded": self.excluded,
77
+ "warnings": list(self.warnings),
78
+ }
79
+
80
+ # ------------------------------------------------------------- the files
81
+
82
+ def world(self) -> dict:
83
+ entities = {
84
+ e.name: {"schema": {"$ref": f"#/$defs/{_pointer(e.source)}"}, "primary_key": [e.key]}
85
+ for e in sorted(self.entities, key=lambda e: e.name)
86
+ }
87
+ return {
88
+ "$schema": DIALECT,
89
+ "$id": f"urn:gateway:connector:{self.slug}",
90
+ "title": self.document.title,
91
+ "description": f"Imported from {self.source.label} ({self.document.version})",
92
+ "x-gateway": {
93
+ "version": 1,
94
+ "domain_version": "1.0.0",
95
+ "package": {"id": self.slug, "version": "1.0.0"},
96
+ "entities": entities,
97
+ "tools": {},
98
+ },
99
+ "$defs": self.defs,
100
+ }
101
+
102
+ def connector_toml(self) -> str:
103
+ head = [
104
+ "[connector]",
105
+ f"slug = {_s(self.slug)}",
106
+ f"base_url = {_s(self.base_url())}",
107
+ "",
108
+ *self._auth_lines(),
109
+ "[api]",
110
+ 'envelope = ""',
111
+ 'hits_key = ""',
112
+ "cursor_absent_when_done = true",
113
+ 'page = "none"',
114
+ "",
115
+ ]
116
+ return "\n".join(head) + "\n" + "\n".join(o.toml() for o in self.operations)
117
+
118
+ def base_url(self) -> str:
119
+ return self.document.base_url() or f"https://{self.slug}.invalid"
120
+
121
+ def _auth_lines(self) -> list[str]:
122
+ env = re.sub(r"[^A-Z0-9]+", "_", self.slug.upper()).strip("_") or "API"
123
+ for name, scheme in self.document.security_schemes().items():
124
+ lines = _auth(scheme, env)
125
+ if lines:
126
+ return ["[auth]", *lines, f"# from security scheme {name}", ""]
127
+ return ["[auth]", 'scheme = "none"', ""]
128
+
129
+ def provenance(self) -> dict:
130
+ return {
131
+ "importer": {"name": "gateway worlds schema init --from-openapi", "version": IMPORTER_VERSION},
132
+ "source": {
133
+ "kind": self.source.kind,
134
+ "label": self.source.label,
135
+ "sha256": self.source.sha256,
136
+ "bytes": self.source.size,
137
+ },
138
+ "document": {
139
+ "version": self.document.version,
140
+ "title": self.document.title,
141
+ "info_version": str(self.document.info.get("version", "")),
142
+ },
143
+ "entities": {
144
+ e.name: {"source": e.source, "pointer": e.pointer, "key": e.key, "fields": e.fields}
145
+ for e in self.entities
146
+ },
147
+ "operations": {o.name: {"pointer": o.pointer, "operation_id": o.operation_id} for o in self.operations},
148
+ }
149
+
150
+ def files(self) -> dict[str, bytes]:
151
+ return {
152
+ WORLD: _json_bytes(self.world()),
153
+ SPEC: self.connector_toml().encode("utf-8"),
154
+ PROVENANCE: _json_bytes(self.provenance()),
155
+ }
156
+
157
+ # ------------------------------------------------------------- writing
158
+
159
+ def write(self, destination: str | Path, *, name: str | None = None) -> Contract:
160
+ """Hand the rendered files to the scaffold writer; nothing is written here."""
161
+ if not self.entities:
162
+ fail(
163
+ "spec",
164
+ "No schema of the document has a key, so no entity can be made; nothing to import",
165
+ self.document.schemas_pointer,
166
+ )
167
+ return init_bundle_from_files(destination, self.files(), connector=self.slug, name=name)
168
+
169
+ def run(
170
+ self, destination: str | Path, *, plan_only: bool = False, name: str | None = None, shown: str | None = None
171
+ ) -> dict:
172
+ """What the CLI prints: the plan, and when writing, the compiled domain and
173
+ the next commands (naming ``shown``, the caller's directory, when the tree
174
+ is written somewhere else first). ``plan_only`` writes nothing."""
175
+ out = {"status": "ok", "written": not plan_only, "plan": self.summary()}
176
+ if plan_only:
177
+ return out
178
+ contract = self.write(destination, name=name)
179
+ out["domain"] = contract.target
180
+ out["next"] = self.next_steps(shown or str(destination))
181
+ return out
182
+
183
+ def next_steps(self, destination: str) -> list[str]:
184
+ listing = next((o for o in self.operations if o.entity and not o.single and o.method == "GET"), None)
185
+ entity = listing.entity if listing is not None and listing.entity else self.entities[0].name
186
+ steps = [
187
+ f"gateway worlds schema compile {destination} # after any edit to schema/ or connector.toml",
188
+ f"gateway worlds schema check {destination}",
189
+ f"gateway worlds data import {destination} <rows.json> --entity {entity} # rows shaped like the vendor's response",
190
+ f"gateway worlds serve {destination} # then, in another shell:",
191
+ ]
192
+ if listing is not None:
193
+ steps.append(
194
+ f"gateway worlds call http://127.0.0.1:<port> {listing.name} --args '{{}}' # GET {listing.path}"
195
+ )
196
+ steps.append(
197
+ f'gateway worlds sandbox commit <sandbox-id> -m "import {self.source.label}" # when {destination} is in a sandbox'
198
+ )
199
+ return steps
200
+
201
+
202
+ class OpenApiImport:
203
+ """One OpenAPI document, read once, planned into a world."""
204
+
205
+ def __init__(self, source: OpenApiSource, *, selection: Selection | None = None, slug: str | None = None):
206
+ self.source = source
207
+ self.selection = selection or Selection()
208
+ self.document = OpenApiDocument(source.document())
209
+ self.slug = slug or _slug(self.document.title)
210
+ self.warnings: list[str] = list(self.document.warnings)
211
+
212
+ @classmethod
213
+ def read(
214
+ cls, spec: str, *, include: tuple[str, ...] = (), exclude: tuple[str, ...] = (), slug: str | None = None
215
+ ) -> OpenApiImport:
216
+ return cls(OpenApiSource.read(spec), selection=Selection(tuple(include), tuple(exclude)), slug=slug)
217
+
218
+ @classmethod
219
+ def execute(cls, request: dict, root: Path) -> dict:
220
+ """The bridge's ``init-openapi``: ``{source, document, include?, exclude?,
221
+ plan_only?, name?}``. ``document`` is the base64 bytes the caller already
222
+ holds (a local file, a URL it fetched, or a drive file read with its own
223
+ credentials), labelled by ``source``. Like ``conform``, the bridge never
224
+ opens a caller-named path or URL itself: wherever it runs, the bytes come
225
+ with the request."""
226
+ name, include, exclude = (request.get("name"), request.get("include", []), request.get("exclude", []))
227
+ shown = request.get("destination")
228
+ if not all(v is None or isinstance(v, str) for v in (name, shown)):
229
+ fail("input", "Expected an optional name and destination label")
230
+ if not all(isinstance(v, list) and all(isinstance(p, str) for p in v) for v in (include, exclude)):
231
+ fail("input", "include and exclude are lists of path globs or tags")
232
+ importer = cls(_request_source(request), selection=Selection(tuple(include), tuple(exclude)))
233
+ return importer.plan().run(root, plan_only=request.get("plan_only") is True, name=name, shown=shown)
234
+
235
+ def plan(self) -> OpenApiWorldPlan:
236
+ everything = list(self.document.operations())
237
+ selected = [op for op in everything if self.selection.selects(op)]
238
+ if not selected:
239
+ fail("spec", "No operation matches --include/--exclude; nothing to import", "/paths")
240
+ converter = SchemaConverter(self.document, {})
241
+ entities = self._entities(converter, self._reachable(selected), self._returned(selected))
242
+ routes = RoutePlanner(self.document, entities, selected).plan()
243
+ defs = converter.convert_all(set(entities))
244
+ self.warnings.extend(routes.warnings)
245
+ self.warnings.extend(converter.warnings)
246
+ self.warnings.extend(
247
+ f"{at}: property {source} is stored as {legal} (not an identifier)"
248
+ for at, source, legal in converter.renamed
249
+ )
250
+ if converter.dropped:
251
+ kept = ", ".join(f"{k} x{n}" for k, n in sorted(converter.dropped.items()))
252
+ self.warnings.append(f"schema keywords the world validator does not model were dropped: {kept}")
253
+ return OpenApiWorldPlan(
254
+ source=self.source,
255
+ document=self.document,
256
+ slug=self.slug,
257
+ entities=sorted(entities.values(), key=lambda e: e.name),
258
+ operations=routes.operations,
259
+ skipped=routes.skipped,
260
+ excluded=len(everything) - len(selected),
261
+ defs=defs,
262
+ warnings=self.warnings,
263
+ )
264
+
265
+ # ------------------------------------------------------------- entities
266
+
267
+ def _reachable(self, selected: list[OpenApiOperation]) -> set[str]:
268
+ """Top-level schema names the selected operations reach through ``$ref``:
269
+ one pass over each schema's text, never a walk per reference."""
270
+ names = self.document.schema_name
271
+ queue = [n for op in selected for n in self._refs(op.request_body, *op.responses.values()) if n is not None]
272
+ queue = [n for n in queue if n in self.document.schemas]
273
+ seen: set[str] = set()
274
+ while queue:
275
+ name = queue.pop()
276
+ if name in seen:
277
+ continue
278
+ seen.add(name)
279
+ for ref in _REF.findall(json.dumps(self.document.schemas[name])):
280
+ target = names(ref)
281
+ if target is not None and target in self.document.schemas and target not in seen:
282
+ queue.append(target)
283
+ if seen:
284
+ return seen
285
+ self.warnings.append("no operation names a schema; every keyed schema becomes an entity")
286
+ return set(self.document.schemas)
287
+
288
+ def _refs(self, *nodes: Any) -> list[str | None]:
289
+ return [
290
+ self.document.schema_name(ref)
291
+ for node in nodes
292
+ if node is not None
293
+ for ref in _REF.findall(json.dumps(node))
294
+ ]
295
+
296
+ def _returned(self, selected: list[OpenApiOperation]) -> set[str]:
297
+ """Schemas some success response names directly: the only ones a key may be
298
+ guessed for (first required scalar); error and request shapes never are."""
299
+ successes = [op.success[1] for op in selected if op.success is not None]
300
+ return {n for n in self._refs(*successes) if n is not None}
301
+
302
+ def _entities(self, converter: SchemaConverter, candidates: set[str], returned: set[str]) -> dict[str, Entity]:
303
+ """The keyed object schemas among ``candidates``, registered as the converter's roots."""
304
+ names = Namespace(limit=MAX_ENTITY_NAME)
305
+ entities: dict[str, Entity] = {}
306
+ for source in sorted(candidates):
307
+ at = f"{self.document.schemas_pointer}/{_pointer(source)}"
308
+ resolved, chain = converter.resolve_named(self.document.schemas[source], at, (source,))
309
+ if not isinstance(resolved, dict):
310
+ continue
311
+ merged = converter.merged(resolved, at, chain)
312
+ properties = merged.get("properties")
313
+ if not isinstance(properties, dict) or not properties:
314
+ continue
315
+ required = {r for r in merged.get("required", []) if isinstance(r, str)}
316
+ detector = EntityKey(self.document, source, properties, required)
317
+ key = detector.detect(fallback=source in returned)
318
+ if key is None:
319
+ continue
320
+ name, renamed = names.claim(Names.entity(source, MAX_ENTITY_NAME))
321
+ if renamed:
322
+ self.warnings.append(f"{at}: entity name for {source} is taken; using {name}")
323
+ fields = Names.fields(properties)
324
+ filterable = frozenset(fields[p] for p in detector.scalars())
325
+ converter.roots[source] = key
326
+ entities[source] = Entity(
327
+ name, source, at, fields[key], self._key_type(properties[key], at), fields, filterable
328
+ )
329
+ return entities
330
+
331
+ def _key_type(self, schema: Any, at: str) -> str:
332
+ resolved = self.document.resolve(schema, at)
333
+ declared = resolved.get("type") if isinstance(resolved, dict) else None
334
+ listed = [declared] if isinstance(declared, str) else declared if isinstance(declared, list) else []
335
+ return "integer" if [t for t in listed if t != "null"] == ["integer"] else "string"
336
+
337
+
338
+ # ---------------------------------------------------------------- rendering helpers
339
+
340
+
341
+ def _request_source(request: dict) -> OpenApiSource:
342
+ source, document = request.get("source"), request.get("document")
343
+ if not isinstance(source, str) or not source:
344
+ fail("input", "Expected the OpenAPI source as a path, URL or drive:<path> label")
345
+ if not isinstance(document, str):
346
+ fail("input", "Expected the OpenAPI document as base64 text")
347
+ try:
348
+ data = base64.b64decode(document, validate=True)
349
+ except (ValueError, binascii.Error):
350
+ fail("input", "OpenAPI document content must be base64")
351
+ return OpenApiSource.from_bytes(data, OpenApiSource.safe_label(source), OpenApiSource.kind_of(source))
352
+
353
+
354
+ def _auth(scheme: dict, env: str) -> list[str]:
355
+ kind = scheme.get("type")
356
+ if kind == "http" and str(scheme.get("scheme", "")).lower() == "bearer" or kind == "oauth2":
357
+ return ['scheme = "bearer"', f"secret_env = {_s(env + '_TOKEN')}"]
358
+ if kind == "http" and str(scheme.get("scheme", "")).lower() == "basic" or kind == "basic":
359
+ return ['scheme = "basic"', f"secret_env = {_s(env + '_BASIC')}"]
360
+ if kind == "apiKey" and scheme.get("in") in ("header", "query") and isinstance(scheme.get("name"), str):
361
+ return [f"scheme = {_s(scheme['in'])}", f"name = {_s(scheme['name'])}", f"secret_env = {_s(env + '_API_KEY')}"]
362
+ return []
363
+
364
+
365
+ def _slug(title: str) -> str:
366
+ slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
367
+ slug = re.sub(r"-+", "-", slug)
368
+ if not slug or not slug[0].isalpha():
369
+ slug = "api-" + slug if slug else "imported-api"
370
+ return slug[:48].rstrip("-")
371
+
372
+
373
+ def _pointer(name: str) -> str:
374
+ return name.replace("~", "~0").replace("/", "~1")
375
+
376
+
377
+ def _s(text: str) -> str:
378
+ return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
379
+
380
+
381
+ def _json_bytes(value: Any) -> bytes:
382
+ return (json.dumps(value, indent=2, ensure_ascii=False, sort_keys=False) + "\n").encode("utf-8")