@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
@@ -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.0",
23
+ version: "0.3.3",
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",
@@ -1160,22 +1160,52 @@ async function registerBuild(params) {
1160
1160
  }
1161
1161
  }
1162
1162
 
1163
- // src/tracing/init.ts
1164
- var ENV_VARS = {
1163
+ // src/tracing/prerequisites.ts
1164
+ 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 DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces";
1171
- var state = {
1172
- initialized: false,
1173
- provider: null
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"
1174
1178
  };
1179
+ var PINNED_PEERS = Object.entries(OPENTELEMETRY_PEERS).map(([name, version]) => `${name}@${version}`).join(" ");
1180
+ var MODULE_NOT_FOUND = /* @__PURE__ */ new Set(["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
1175
1181
  function getEnv(key) {
1176
1182
  const value = process.env[key];
1177
1183
  return value ? value : void 0;
1178
1184
  }
1185
+ function isGatewayConfigured() {
1186
+ return !!(getEnv(GATEWAY_ENV.HOST) && getEnv(GATEWAY_ENV.PUBLIC_KEY) && getEnv(GATEWAY_ENV.SECRET_KEY));
1187
+ }
1188
+ var OpenTelemetryMissing = class _OpenTelemetryMissing extends Error {
1189
+ constructor() {
1190
+ super(
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)`
1194
+ );
1195
+ this.name = "OpenTelemetryMissing";
1196
+ }
1197
+ static explains(error) {
1198
+ if (error instanceof _OpenTelemetryMissing) return true;
1199
+ const { code, message } = error ?? {};
1200
+ return MODULE_NOT_FOUND.has(String(code)) && String(message).includes("@opentelemetry/");
1201
+ }
1202
+ };
1203
+
1204
+ // src/tracing/init.ts
1205
+ var state = {
1206
+ initialized: false,
1207
+ provider: null
1208
+ };
1179
1209
  function log(message, ...args) {
1180
1210
  if (state.debug) {
1181
1211
  console.log(`[gatewaysdk.tracing] ${message}`, ...args);
@@ -1185,10 +1215,10 @@ function warn(message, ...args) {
1185
1215
  console.warn(`[gatewaysdk.tracing] ${message}`, ...args);
1186
1216
  }
1187
1217
  function buildProvider(config, logFn) {
1188
- const host = config.host ?? getEnv(ENV_VARS.HOST);
1189
- const publicKey = config.publicKey ?? getEnv(ENV_VARS.PUBLIC_KEY);
1190
- const secretKey = config.secretKey ?? getEnv(ENV_VARS.SECRET_KEY);
1191
- const endpoint = config.endpoint ?? getEnv(ENV_VARS.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
1218
+ const host = config.host ?? getEnv(GATEWAY_ENV.HOST);
1219
+ const publicKey = config.publicKey ?? getEnv(GATEWAY_ENV.PUBLIC_KEY);
1220
+ const secretKey = config.secretKey ?? getEnv(GATEWAY_ENV.SECRET_KEY);
1221
+ const endpoint = config.endpoint ?? getEnv(GATEWAY_ENV.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${OTLP_TRACES_PATH}` : void 0);
1192
1222
  const missing = [];
1193
1223
  if (!host) missing.push("host (or GATEWAY_HOST env var)");
1194
1224
  if (!publicKey) missing.push("publicKey (or GATEWAY_PUBLIC_KEY env var)");
@@ -1225,9 +1255,7 @@ function buildProvider(config, logFn) {
1225
1255
  ATTR_SERVICE_NAME = "service.name";
1226
1256
  }
1227
1257
  } catch {
1228
- throw new Error(
1229
- "OpenTelemetry packages not found. Install them with:\nnpm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources"
1230
- );
1258
+ throw new OpenTelemetryMissing();
1231
1259
  }
1232
1260
  const resourceAttrs = {
1233
1261
  [ATTR_SERVICE_NAME]: config.serviceName ?? "gatewaysdk-tracing"
@@ -1433,12 +1461,6 @@ async function shutdown() {
1433
1461
  function isInitialized() {
1434
1462
  return state.initialized;
1435
1463
  }
1436
- function isGatewayConfigured() {
1437
- const host = getEnv(ENV_VARS.HOST);
1438
- const publicKey = getEnv(ENV_VARS.PUBLIC_KEY);
1439
- const secretKey = getEnv(ENV_VARS.SECRET_KEY);
1440
- return !!(host && publicKey && secretKey);
1441
- }
1442
1464
 
1443
1465
  // src/tracing/observe.ts
1444
1466
  import { trace as trace3, context, SpanStatusCode } from "@opentelemetry/api";
@@ -1770,6 +1792,56 @@ var UnreachableError = class extends Error {
1770
1792
  route;
1771
1793
  failure;
1772
1794
  };
1795
+ var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
1796
+ var RetryPolicy = class _RetryPolicy {
1797
+ constructor(delaysMs, wait = sleep, budgetMs = Number.POSITIVE_INFINITY, now = Date.now) {
1798
+ this.delaysMs = delaysMs;
1799
+ this.wait = wait;
1800
+ this.budgetMs = budgetMs;
1801
+ this.now = now;
1802
+ }
1803
+ delaysMs;
1804
+ wait;
1805
+ budgetMs;
1806
+ now;
1807
+ static NONE = new _RetryPolicy([]);
1808
+ /** A platform restart or a short edge outage: no wait starts that would end past five minutes, so a step ends
1809
+ * within the budget plus one request timeout. */
1810
+ static FILING = new _RetryPolicy([250, 500, 1e3, 2e3, 4e3, 8e3, 16e3, 3e4], sleep, 3e5);
1811
+ static TRANSIENT_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
1812
+ async run(attempt) {
1813
+ const started = this.now();
1814
+ for (let tries = 0; ; tries += 1) {
1815
+ const outcome = await Attempt.of(attempt);
1816
+ const delayMs = this.delaysMs[tries];
1817
+ const spent = delayMs === void 0 || this.now() - started + delayMs >= this.budgetMs;
1818
+ if (!outcome.transient || spent) return outcome.settle();
1819
+ await this.wait(delayMs);
1820
+ }
1821
+ }
1822
+ };
1823
+ var Attempt = class _Attempt {
1824
+ constructor(reply, error, transient) {
1825
+ this.reply = reply;
1826
+ this.error = error;
1827
+ this.transient = transient;
1828
+ }
1829
+ reply;
1830
+ error;
1831
+ transient;
1832
+ static async of(attempt) {
1833
+ try {
1834
+ const reply = await attempt();
1835
+ return new _Attempt(reply, null, RetryPolicy.TRANSIENT_STATUSES.has(reply.status));
1836
+ } catch (error) {
1837
+ return new _Attempt(null, error, error instanceof UnreachableError);
1838
+ }
1839
+ }
1840
+ settle() {
1841
+ if (this.reply) return this.reply;
1842
+ throw this.error;
1843
+ }
1844
+ };
1773
1845
  var PlatformTransport = class {
1774
1846
  constructor(endpoint, timeoutMs = platformTimeoutMs()) {
1775
1847
  this.endpoint = endpoint;
@@ -1783,6 +1855,9 @@ var PlatformTransport = class {
1783
1855
  }
1784
1856
  async send(method, route, body, opts = {}) {
1785
1857
  const timeoutMs = this.budget(opts.timeoutMs);
1858
+ return (opts.retry ?? RetryPolicy.NONE).run(() => this.once(method, route, body, timeoutMs));
1859
+ }
1860
+ async once(method, route, body, timeoutMs) {
1786
1861
  const payload = body === void 0 ? {} : { body: JSON.stringify(body) };
1787
1862
  const controller = new AbortController();
1788
1863
  const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -1865,7 +1940,7 @@ var MediaUploader = class _MediaUploader {
1865
1940
  put;
1866
1941
  maxBytes;
1867
1942
  /** The uploader for `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` /
1868
- * `GATEWAY_SECRET_KEY` (the keys tracing exports with); null when any is unset. */
1943
+ * `GATEWAY_SECRET_KEY` only; null when any is unset, so a run traced with a saved login uploads none. */
1869
1944
  static fromEnv(env = process.env) {
1870
1945
  const host = env.GATEWAY_HOST;
1871
1946
  const publicKey = env.GATEWAY_PUBLIC_KEY;