@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,43 @@
1
+ # A world from nothing: `sandbox open --new`
2
+
3
+ `gateway worlds sandbox open --new <slug> --from custom|<template>` (`bench sandbox` is the
4
+ same command; MCP `open_world_sandbox({ new, from })`) opens a hosted sandbox for a world that
5
+ does not exist yet in the key's project. Nothing is needed on the caller's disk — not a
6
+ checkout, not `schema init`.
7
+
8
+ ```bash
9
+ gateway worlds sandbox open --new acme-crm --from custom # or --from slack|github|…
10
+ gateway worlds sandbox exec <id> "gateway worlds schema entity add . crm_accounts --fields id:string,name:string --key id"
11
+ gateway worlds sandbox exec <id> "gateway worlds schema compile . && gateway worlds schema check ."
12
+ gateway worlds sandbox check <id> # the push gate the first commit will run
13
+ gateway worlds sandbox commit <id> -m "first cut" # creates the world: first READY version on main
14
+ gateway worlds sandbox close <id>
15
+ ```
16
+
17
+ What `open` does and does not do:
18
+
19
+ - The slug goes through the one world slug validator and must be free in the project. A taken
20
+ slug is a 409 `world_exists`; the sandbox never renames it (pick another slug).
21
+ - `--from custom` seeds the working tree with exactly what `gateway worlds schema init <slug>`
22
+ writes; `--from <template>` with a shipped template (`gateway worlds schema templates`,
23
+ `GET /api/public/worlds/templates`). An unknown template is a 400 that names the list.
24
+ - No world, container or version is created at open. `open`/`status` say so:
25
+ `containerId: null`, `baseVersionId: null`, `baseContentHash: null`, `branch: "main"`,
26
+ `pendingSlug: "<slug>"`.
27
+ - Paths stay under `/workspace/env`; the staged `gateway` CLI and `sqlite3` run on the tree.
28
+
29
+ The first `commit`:
30
+
31
+ - runs the same push gate as `check` (nothing is written to the versions tables when it fails);
32
+ - creates the world through the door `gateway worlds create --from <dir>` uses — slug, kind
33
+ detected from the tree (a retired kind is refused the same way), first READY version on
34
+ `main`, attributed to the key;
35
+ - flips the sandbox to a normal one in the same transaction: it now has a container, a base
36
+ version and a base hash, and every later `commit` behaves like today's (parent check, dedup,
37
+ no-change).
38
+
39
+ Two new-world sandboxes racing for one slug: exactly one first commit wins; the other gets a
40
+ 409 `world_exists` and keeps its tree intact. To keep that work, open a new sandbox with another
41
+ slug (`sandbox open --new <other> --from custom`), copy the files across with `read`/`write`,
42
+ then `sandbox close <id> --force` the loser. A never-committed `--new` sandbox counts as
43
+ uncommitted (its base is empty), so a plain `close` exits 1; a closed sandbox cannot be reopened.
@@ -0,0 +1,90 @@
1
+ # From an OpenAPI spec: `schema init --from-openapi`
2
+
3
+ `gateway worlds schema init <dir> --from-openapi <source>` turns a Swagger 2.0 or OpenAPI 3.0.x /
4
+ 3.1 document (JSON or YAML) into a world: `schema/world.json` (entities), `connector.toml` (the
5
+ served routes) and `schema/provenance.json` (where it came from). The importer is the Python
6
+ package's `OpenApiImport` → `OpenApiWorldPlan`; the plan is handed to the same scaffold writer
7
+ `schema init` always uses, so the tree it writes is a plain schema world you keep editing with
8
+ `schema entity add` and `connector route add`.
9
+
10
+ ```bash
11
+ gateway worlds schema init ./x --from-openapi petstore.yaml # local file: plan printed, tree written
12
+ gateway worlds schema init ./x --from-openapi drive:specs/petstore.json # a file on the project drive (read platform-side, never downloaded)
13
+ gateway worlds schema init ./x --from-openapi https://vendor.test/openapi.json # fetched from where the command runs
14
+ gateway worlds schema init ./x --from-openapi github.json --plan-only # print the plan, write nothing
15
+ gateway worlds schema init ./x --from-openapi github.json --include '/repos/{owner}/{repo}/issues*' --exclude reactions
16
+ ```
17
+
18
+ ## Sources
19
+
20
+ | `<source>` | Read by | Notes |
21
+ | --- | --- | --- |
22
+ | a local path | the CLI process | must be a file under 64 MiB |
23
+ | `drive:<path>` | the platform, with your `GATEWAY_*` keys | the same reader as `worlds data import drive:…`; bytes stay in memory, nothing lands on disk |
24
+ | `http(s)://…` | the process running the command | the TS CLI fetches it like `files fetch`; the Python `gateway` fetches behind its private-address guard (loopback, RFC 1918, link-local and metadata addresses are refused, redirects re-checked). Other schemes (`file:`, `ftp:`) are refused. |
25
+
26
+ Inside a world sandbox (`run_gateway_cli`, `sandbox exec`) only a workspace path is accepted:
27
+ write the document into the workspace first (`sandbox write --from spec.yaml`), then import.
28
+
29
+ ## What the plan says
30
+
31
+ `--from-openapi` always prints the plan first (JSON, one object):
32
+
33
+ ```json
34
+ {
35
+ "status": "ok", "written": true,
36
+ "plan": {
37
+ "source": "petstore.yaml", "document": {"version": "openapi 3.0.3", "title": "Petstore", "sha256": "…"},
38
+ "connector": "petstore",
39
+ "entities": [{"name": "pets", "key": "id", "source": "Pet", "pointer": "/components/schemas/Pet"}],
40
+ "operations": [{"name": "list_pets", "method": "GET", "path": "/pets", "entity": "pets", "action": "read",
41
+ "params": ["limit", "status"], "filter": {"status": "status"}, "pointer": "/paths/~1pets/get"}],
42
+ "skipped": [{"method": "TRACE", "path": "/pets", "pointer": "/paths/~1pets/trace", "skipped_reason": "method TRACE is not one a connector serves"}],
43
+ "excluded": 0, "warnings": ["/paths/~1pets/post: operation name add_pet is taken; using add_pet_2"]
44
+ },
45
+ "domain": "petstore", "next": ["gateway worlds schema compile ./x # …", "…"]
46
+ }
47
+ ```
48
+
49
+ With `--plan-only` the same object carries `"written": false` and no `domain`/`next`.
50
+
51
+ ## Conversion rules (decided; the importer documents them in `schema/provenance.json`)
52
+
53
+ - **Entities.** Every object schema under `definitions` / `components.schemas` that some selected
54
+ operation returns and that has an id-like key (`id`, `<name>Id`, `<name>_id`, a `readOnly`
55
+ field the vendor marks `x-unique`/`x-primary-key`, else the first `required` string/integer field) becomes a `$defs` entry plus
56
+ `x-gateway.entities.<snake_plural>` with `primary_key` (snake_case, at most 64 characters —
57
+ a longer vendor name is truncated, the original kept in provenance). Keyless objects stay `$defs`,
58
+ referenced inline. `allOf` is merged; `oneOf`/`anyOf` become a union the world validator
59
+ accepts. Entity roots close (`additionalProperties: false`); the vendor's field names are kept
60
+ as spelled (so a rows file shaped like the vendor's response imports as it is); the vendor's
61
+ schema name stays the `$defs` key and `schema/provenance.json` maps every entity and operation
62
+ back to its source name and JSON pointer.
63
+ - **Routes.** Every path+method in `get|post|put|patch|delete` becomes an `[[operations]]` entry:
64
+ `name` = `operationId` snake_cased, at most 64 characters, deduped with `_2`, `_3` and a
65
+ warning; `entity` = the response schema's entity when it resolves to one (an array → a list
66
+ route, an object → `read|create|update|delete` by method); path parameters and declared query
67
+ parameters become `params`; a `{data: [...]}` wrapper becomes `results`; on a list route a
68
+ declared query parameter that names a top-level entity field becomes a `filter` (paging names
69
+ such as `page`, `limit`, `offset`, `cursor` never do). A path that repeats a placeholder
70
+ (`/a/{id}/{id}`) is skipped with its reason. An operation whose response is not an
71
+ entity (login, upload, HTML) stays a **passthrough** route with no entity — it is served, and
72
+ answers `501 {"error": "not_modelled"}` until you give it a handler.
73
+ - **Skipped, with a reason:** `HEAD`/`OPTIONS`/`TRACE`; a path argument that is not an
74
+ identifier; a second operation on the same method+path shape. **Refused, with a JSON pointer
75
+ into the document, nothing written:** no `paths`; an unknown or external `$ref`; an entity root
76
+ that is (transitively) cyclic — model the recursion as a relationship field (`parent_id`)
77
+ instead; a path parameter nothing declares (`--param <name>` on a hand-written route); a
78
+ document with no keyed schema at all.
79
+ - **Big documents.** `--include GLOB|TAG` / `--exclude GLOB|TAG` (repeatable) select operations
80
+ by path glob or tag before anything is resolved; only the schemas the selected operations reach
81
+ are converted, so the 9.9 MB GitHub document imports as an issues subset in seconds. A
82
+ document over 64 MiB is refused before it is read.
83
+
84
+ ## After import
85
+
86
+ The printed `next` steps are the loop, in order: `schema compile`, `schema check`, `data import
87
+ <rows.json> --entity <first list entity>` (rows shaped like the vendor's response), `worlds serve`
88
+ then `worlds call http://127.0.0.1:<port> <list_route> --args '{}'`, and `sandbox commit` when the
89
+ tree lives in a sandbox. `connector conform ./x --openapi <the same document>` then checks the
90
+ served world back against the spec.