@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
@@ -20,7 +20,7 @@ var require_package = __commonJS({
20
20
  "package.json"(exports, module) {
21
21
  module.exports = {
22
22
  name: "@withgateway/sdk",
23
- version: "0.3.1",
23
+ version: "0.4.0",
24
24
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
25
25
  main: "./dist/index.js",
26
26
  module: "./dist/index.mjs",
@@ -1165,15 +1165,18 @@ var GATEWAY_ENV = {
1165
1165
  HOST: "GATEWAY_HOST",
1166
1166
  PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
1167
1167
  SECRET_KEY: "GATEWAY_SECRET_KEY",
1168
+ API_KEY: "GATEWAY_API_KEY",
1168
1169
  ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
1169
1170
  };
1170
- var OPENTELEMETRY_PEERS = [
1171
- "@opentelemetry/api",
1172
- "@opentelemetry/exporter-trace-otlp-http",
1173
- "@opentelemetry/resources",
1174
- "@opentelemetry/sdk-trace-base",
1175
- "@opentelemetry/sdk-trace-node"
1176
- ];
1171
+ var OTLP_TRACES_PATH = "/api/public/otel/v1/traces";
1172
+ var OPENTELEMETRY_PEERS = {
1173
+ "@opentelemetry/api": "1.9.0",
1174
+ "@opentelemetry/exporter-trace-otlp-http": "0.222.0",
1175
+ "@opentelemetry/resources": "2.11.0",
1176
+ "@opentelemetry/sdk-trace-base": "2.11.0",
1177
+ "@opentelemetry/sdk-trace-node": "2.11.0"
1178
+ };
1179
+ var PINNED_PEERS = Object.entries(OPENTELEMETRY_PEERS).map(([name, version]) => `${name}@${version}`).join(" ");
1177
1180
  var MODULE_NOT_FOUND = /* @__PURE__ */ new Set(["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
1178
1181
  function getEnv(key) {
1179
1182
  const value = process.env[key];
@@ -1185,8 +1188,9 @@ function isGatewayConfigured() {
1185
1188
  var OpenTelemetryMissing = class _OpenTelemetryMissing extends Error {
1186
1189
  constructor() {
1187
1190
  super(
1188
- `OpenTelemetry packages not found. Install them with:
1189
- npm install ${OPENTELEMETRY_PEERS.join(" ")}`
1191
+ `OpenTelemetry packages not found. Install them next to @withgateway/sdk, at the versions it is tested with:
1192
+ npm install ${PINNED_PEERS}
1193
+ npm install -g ${PINNED_PEERS} (the gateway CLI, when it was installed with npm install -g)`
1190
1194
  );
1191
1195
  this.name = "OpenTelemetryMissing";
1192
1196
  }
@@ -1198,7 +1202,6 @@ npm install ${OPENTELEMETRY_PEERS.join(" ")}`
1198
1202
  };
1199
1203
 
1200
1204
  // src/tracing/init.ts
1201
- var DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces";
1202
1205
  var state = {
1203
1206
  initialized: false,
1204
1207
  provider: null
@@ -1215,7 +1218,7 @@ function buildProvider(config, logFn) {
1215
1218
  const host = config.host ?? getEnv(GATEWAY_ENV.HOST);
1216
1219
  const publicKey = config.publicKey ?? getEnv(GATEWAY_ENV.PUBLIC_KEY);
1217
1220
  const secretKey = config.secretKey ?? getEnv(GATEWAY_ENV.SECRET_KEY);
1218
- const endpoint = config.endpoint ?? getEnv(GATEWAY_ENV.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
1221
+ const endpoint = config.endpoint ?? getEnv(GATEWAY_ENV.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${OTLP_TRACES_PATH}` : void 0);
1219
1222
  const missing = [];
1220
1223
  if (!host) missing.push("host (or GATEWAY_HOST env var)");
1221
1224
  if (!publicKey) missing.push("publicKey (or GATEWAY_PUBLIC_KEY env var)");
@@ -1735,7 +1738,13 @@ function platformTimeoutMs(env = process.env) {
1735
1738
  }
1736
1739
  var CHECK_HOST = "Check GATEWAY_HOST (or --host) points at a running platform, then retry.";
1737
1740
  var RETRY = "Retry; if it repeats, check the network between here and the platform.";
1741
+ var FETCH_LIMIT = {
1742
+ reason: "Node's fetch stopped waiting after 300 s",
1743
+ next: "The platform may still be running it: check what it changed before you retry."
1744
+ };
1738
1745
  var CAUSES = {
1746
+ UND_ERR_HEADERS_TIMEOUT: FETCH_LIMIT,
1747
+ UND_ERR_BODY_TIMEOUT: FETCH_LIMIT,
1739
1748
  ECONNREFUSED: { reason: "connection refused", next: CHECK_HOST },
1740
1749
  ENOTFOUND: { reason: "DNS lookup failed", next: CHECK_HOST },
1741
1750
  EAI_AGAIN: { reason: "DNS lookup failed", next: CHECK_HOST },
@@ -1789,6 +1798,56 @@ var UnreachableError = class extends Error {
1789
1798
  route;
1790
1799
  failure;
1791
1800
  };
1801
+ var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
1802
+ var RetryPolicy = class _RetryPolicy {
1803
+ constructor(delaysMs, wait = sleep, budgetMs = Number.POSITIVE_INFINITY, now = Date.now) {
1804
+ this.delaysMs = delaysMs;
1805
+ this.wait = wait;
1806
+ this.budgetMs = budgetMs;
1807
+ this.now = now;
1808
+ }
1809
+ delaysMs;
1810
+ wait;
1811
+ budgetMs;
1812
+ now;
1813
+ static NONE = new _RetryPolicy([]);
1814
+ /** A platform restart or a short edge outage: no wait starts that would end past five minutes, so a step ends
1815
+ * within the budget plus one request timeout. */
1816
+ static FILING = new _RetryPolicy([250, 500, 1e3, 2e3, 4e3, 8e3, 16e3, 3e4], sleep, 3e5);
1817
+ static TRANSIENT_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
1818
+ async run(attempt) {
1819
+ const started = this.now();
1820
+ for (let tries = 0; ; tries += 1) {
1821
+ const outcome = await Attempt.of(attempt);
1822
+ const delayMs = this.delaysMs[tries];
1823
+ const spent = delayMs === void 0 || this.now() - started + delayMs >= this.budgetMs;
1824
+ if (!outcome.transient || spent) return outcome.settle();
1825
+ await this.wait(delayMs);
1826
+ }
1827
+ }
1828
+ };
1829
+ var Attempt = class _Attempt {
1830
+ constructor(reply, error, transient) {
1831
+ this.reply = reply;
1832
+ this.error = error;
1833
+ this.transient = transient;
1834
+ }
1835
+ reply;
1836
+ error;
1837
+ transient;
1838
+ static async of(attempt) {
1839
+ try {
1840
+ const reply = await attempt();
1841
+ return new _Attempt(reply, null, RetryPolicy.TRANSIENT_STATUSES.has(reply.status));
1842
+ } catch (error) {
1843
+ return new _Attempt(null, error, error instanceof UnreachableError);
1844
+ }
1845
+ }
1846
+ settle() {
1847
+ if (this.reply) return this.reply;
1848
+ throw this.error;
1849
+ }
1850
+ };
1792
1851
  var PlatformTransport = class {
1793
1852
  constructor(endpoint, timeoutMs = platformTimeoutMs()) {
1794
1853
  this.endpoint = endpoint;
@@ -1802,6 +1861,9 @@ var PlatformTransport = class {
1802
1861
  }
1803
1862
  async send(method, route, body, opts = {}) {
1804
1863
  const timeoutMs = this.budget(opts.timeoutMs);
1864
+ return (opts.retry ?? RetryPolicy.NONE).run(() => this.once(method, route, body, timeoutMs));
1865
+ }
1866
+ async once(method, route, body, timeoutMs) {
1805
1867
  const payload = body === void 0 ? {} : { body: JSON.stringify(body) };
1806
1868
  const controller = new AbortController();
1807
1869
  const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -1884,7 +1946,7 @@ var MediaUploader = class _MediaUploader {
1884
1946
  put;
1885
1947
  maxBytes;
1886
1948
  /** The uploader for `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` /
1887
- * `GATEWAY_SECRET_KEY` (the keys tracing exports with); null when any is unset. */
1949
+ * `GATEWAY_SECRET_KEY` only; null when any is unset, so a run traced with a saved login uploads none. */
1888
1950
  static fromEnv(env = process.env) {
1889
1951
  const host = env.GATEWAY_HOST;
1890
1952
  const publicKey = env.GATEWAY_PUBLIC_KEY;