@withgateway/sdk 0.1.12 → 0.1.14

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.
@@ -16,7 +16,7 @@ var require_package = __commonJS({
16
16
  "package.json"(exports, module) {
17
17
  module.exports = {
18
18
  name: "@withgateway/sdk",
19
- version: "0.1.12",
19
+ version: "0.1.14",
20
20
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
21
21
  main: "./dist/index.js",
22
22
  module: "./dist/index.mjs",
@@ -71,6 +71,16 @@ var require_package = __commonJS({
71
71
  types: "./dist/users/index.d.ts",
72
72
  import: "./dist/users/index.mjs",
73
73
  require: "./dist/users/index.js"
74
+ },
75
+ "./scores": {
76
+ types: "./dist/scores/index.d.ts",
77
+ import: "./dist/scores/index.mjs",
78
+ require: "./dist/scores/index.js"
79
+ },
80
+ "./worlds": {
81
+ types: "./dist/worlds/index.d.ts",
82
+ import: "./dist/worlds/index.mjs",
83
+ require: "./dist/worlds/index.js"
74
84
  }
75
85
  },
76
86
  files: [
@@ -84,6 +94,7 @@ var require_package = __commonJS({
84
94
  build: "tsup",
85
95
  dev: "tsup --watch",
86
96
  typecheck: "tsc --noEmit",
97
+ "typecheck:examples": "tsc -p tsconfig.examples.json --noEmit",
87
98
  test: "vitest",
88
99
  "test:run": "vitest run",
89
100
  lint: "eslint src --ext .ts",
@@ -144,10 +155,29 @@ var require_package = __commonJS({
144
155
  "@opentelemetry/sdk-trace-node": "^2.6.0",
145
156
  "@opentelemetry/semantic-conventions": "^1.40.0",
146
157
  "@types/node": "^20.0.0",
158
+ openai: "^4.70.0",
147
159
  tsup: "^8.0.0",
148
160
  tsx: "^4.0.0",
149
161
  typescript: "^5.0.0",
150
- vitest: "^2.0.0"
162
+ vitest: "^3.2.6"
163
+ },
164
+ overrides: {
165
+ protobufjs: "^8.4.1",
166
+ "vite@6": "^6.4.3",
167
+ postcss: "^8.5.18",
168
+ "picomatch@4": "^4.0.4"
169
+ },
170
+ pnpm: {
171
+ overrides: {
172
+ protobufjs: "^8.4.1",
173
+ vitest: "^3.2.6",
174
+ "vite@6": "^6.4.3",
175
+ postcss: "^8.5.18",
176
+ "picomatch@4": "^4.0.4"
177
+ }
178
+ },
179
+ bin: {
180
+ gateway: "./dist/cli.js"
151
181
  }
152
182
  };
153
183
  }
@@ -420,6 +450,216 @@ function debugLog(message, ...args) {
420
450
  }
421
451
  }
422
452
 
453
+ // src/scores/index.ts
454
+ import { isSpanContextValid as isSpanContextValid2, trace as trace2 } from "@opentelemetry/api";
455
+ var SUCCESS_SIGNAL_KEY = "gateway.success.signal";
456
+ var SUCCESS_METRIC_NAME_KEY = "gateway.success.metricName";
457
+ var AGENT_ID_KEY = "gateway.agent.id";
458
+ var ScoreError = class extends Error {
459
+ constructor(message, options) {
460
+ super(message);
461
+ this.name = "ScoreError";
462
+ this.cause = options?.cause;
463
+ }
464
+ };
465
+ function currentTraceId() {
466
+ try {
467
+ const span = trace2.getActiveSpan();
468
+ if (!span) return void 0;
469
+ const ctx = span.spanContext();
470
+ if (!ctx || !isSpanContextValid2(ctx)) return void 0;
471
+ return ctx.traceId;
472
+ } catch {
473
+ return void 0;
474
+ }
475
+ }
476
+ var ScoresClient = class _ScoresClient {
477
+ host;
478
+ publicKey;
479
+ secretKey;
480
+ timeoutSeconds;
481
+ debug;
482
+ constructor(config) {
483
+ this.host = config.host.replace(/\/$/, "");
484
+ this.publicKey = config.publicKey;
485
+ this.secretKey = config.secretKey;
486
+ this.timeoutSeconds = config.timeoutSeconds ?? 15;
487
+ this.debug = config.debug ?? false;
488
+ }
489
+ /** Create a client from GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY. */
490
+ static fromEnv(config = {}) {
491
+ const host = config.host ?? process.env.GATEWAY_HOST;
492
+ const publicKey = config.publicKey ?? process.env.GATEWAY_PUBLIC_KEY;
493
+ const secretKey = config.secretKey ?? process.env.GATEWAY_SECRET_KEY;
494
+ const missing = [
495
+ ["host", host],
496
+ ["publicKey", publicKey],
497
+ ["secretKey", secretKey]
498
+ ].filter(([, value]) => !value).map(([name]) => name);
499
+ if (missing.length > 0) {
500
+ throw new ScoreError(
501
+ `Missing Gateway scores configuration: ${missing.join(", ")}`
502
+ );
503
+ }
504
+ return new _ScoresClient({
505
+ ...config,
506
+ host,
507
+ publicKey,
508
+ secretKey
509
+ });
510
+ }
511
+ /**
512
+ * Post a score, throwing {@link ScoreError} on any failure. Builds the exact
513
+ * `POST /api/public/scores` body the Python SDK sends: exactly one of
514
+ * `sessionId` / `traceId` (+ optional `observationId`) / `datasetRunId`.
515
+ * When no target is provided, the active OTel trace id is used; if none is
516
+ * available the call is a no-op (returns without posting), matching Python.
517
+ */
518
+ async postScore(name, value, options = {}) {
519
+ const body = this.buildScoreBody(name, value, options);
520
+ if (!body) {
521
+ this.log(
522
+ "score '%s' dropped: no sessionId, traceId or datasetRunId available",
523
+ name
524
+ );
525
+ return;
526
+ }
527
+ await this.request("POST", "/api/public/scores", body);
528
+ }
529
+ /**
530
+ * Build the score request body, or null when no target can be resolved.
531
+ * Split out so it is unit-testable and shared by score()/success().
532
+ */
533
+ buildScoreBody(name, value, options = {}) {
534
+ const traceId = options.traceId ?? currentTraceId();
535
+ const target = {};
536
+ if (options.sessionId) {
537
+ target.sessionId = options.sessionId;
538
+ } else if (options.datasetRunId) {
539
+ target.datasetRunId = options.datasetRunId;
540
+ } else if (traceId) {
541
+ target.traceId = traceId;
542
+ if (options.observationId) target.observationId = options.observationId;
543
+ } else {
544
+ return null;
545
+ }
546
+ const metadata = {
547
+ source: "gatewaysdk",
548
+ ...options.metadata ?? {}
549
+ };
550
+ return {
551
+ name,
552
+ value,
553
+ dataType: options.dataType ?? "NUMERIC",
554
+ environment: options.environment ?? "default",
555
+ ...options.comment ? { comment: options.comment } : {},
556
+ metadata,
557
+ ...target
558
+ };
559
+ }
560
+ /**
561
+ * Post a score, FAIL-SOFT: warns and resolves on any failure so a broken
562
+ * transport never throws into (or rejects out of) the caller.
563
+ */
564
+ async score(name, value, options = {}) {
565
+ try {
566
+ await this.postScore(name, value, options);
567
+ } catch (error) {
568
+ this.warn(`score '${name}' failed`, error);
569
+ }
570
+ }
571
+ /**
572
+ * Emit a SUCCESS SIGNAL that feeds a Gateway Success Metric — a score tagged
573
+ * with `gateway.success.signal` + `gateway.success.metricName` (and the agent
574
+ * identity when `agentId` is set). A boolean `value` records a 1/0 BOOLEAN
575
+ * score (pass/fail); a number records a NUMERIC score. FAIL-SOFT.
576
+ *
577
+ * The metadata shape matches the Python SDK's `Run.success()` exactly, so the
578
+ * platform's Success Metrics aggregation counts signals from either SDK
579
+ * without change.
580
+ *
581
+ * @example
582
+ * ```ts
583
+ * await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
584
+ * await scores.success("handle_time_s", 42, { agentId: "support-triage", sessionId });
585
+ * ```
586
+ */
587
+ async success(name, value = true, options = {}) {
588
+ const { numericValue, inferredType } = coerceSignalValue(value);
589
+ const { agentId, metricName, metadata, dataType, ...rest } = options;
590
+ const signalMetadata = {
591
+ ...metadata ?? {},
592
+ [SUCCESS_SIGNAL_KEY]: true,
593
+ [SUCCESS_METRIC_NAME_KEY]: metricName ?? name,
594
+ ...agentId ? { [AGENT_ID_KEY]: agentId } : {}
595
+ };
596
+ await this.score(name, numericValue, {
597
+ ...rest,
598
+ dataType: dataType ?? inferredType,
599
+ metadata: signalMetadata
600
+ });
601
+ }
602
+ async request(method, path, payload) {
603
+ let response;
604
+ try {
605
+ response = await fetch(`${this.host}${path}`, {
606
+ method,
607
+ headers: {
608
+ Authorization: this.authHeader(),
609
+ "Content-Type": "application/json"
610
+ },
611
+ body: JSON.stringify(payload),
612
+ signal: AbortSignal.timeout(this.timeoutSeconds * 1e3)
613
+ });
614
+ } catch (error) {
615
+ throw new ScoreError(
616
+ `${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
617
+ { cause: error }
618
+ );
619
+ }
620
+ const text = await response.text();
621
+ if (!response.ok) {
622
+ throw new ScoreError(
623
+ `${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`
624
+ );
625
+ }
626
+ this.log("%s %s -> %s", method, path, response.status);
627
+ }
628
+ authHeader() {
629
+ return `Basic ${Buffer.from(`${this.publicKey}:${this.secretKey}`).toString(
630
+ "base64"
631
+ )}`;
632
+ }
633
+ log(message, ...args) {
634
+ if (this.debug) {
635
+ console.log(`[gateway.scores] ${message}`, ...args);
636
+ }
637
+ }
638
+ warn(message, ...args) {
639
+ console.warn(`[gateway.scores] ${message}`, ...args);
640
+ }
641
+ };
642
+ function coerceSignalValue(value) {
643
+ if (typeof value === "boolean") {
644
+ return { numericValue: value ? 1 : 0, inferredType: "BOOLEAN" };
645
+ }
646
+ return { numericValue: value, inferredType: "NUMERIC" };
647
+ }
648
+ async function success(name, value = true, options = {}) {
649
+ let client;
650
+ try {
651
+ client = ScoresClient.fromEnv();
652
+ } catch (error) {
653
+ console.warn(`[gateway.scores] success '${name}' skipped`, error);
654
+ return;
655
+ }
656
+ await client.success(name, value, options);
657
+ }
658
+ var scores = {
659
+ fromEnv: ScoresClient.fromEnv,
660
+ success
661
+ };
662
+
423
663
  // src/build/index.ts
424
664
  import { createHash } from "crypto";
425
665
  function canonicalJson(value) {
@@ -824,12 +1064,19 @@ function initIsolated(config = {}) {
824
1064
  const provider = built.provider;
825
1065
  scheduleBuildRegistration(config, built);
826
1066
  const tracer = provider.getTracer("@withgateway/sdk");
1067
+ const scores2 = new ScoresClient({
1068
+ host: built.connection.host,
1069
+ publicKey: built.connection.publicKey,
1070
+ secretKey: built.connection.secretKey,
1071
+ debug: config.debug ?? false
1072
+ });
827
1073
  debugLog2(
828
1074
  "Isolated tracing provider created (service=%s)",
829
1075
  config.serviceName ?? "gatewaysdk-tracing"
830
1076
  );
831
1077
  return {
832
1078
  tracer,
1079
+ scores: scores2,
833
1080
  async flush() {
834
1081
  try {
835
1082
  await provider.forceFlush();
@@ -883,12 +1130,12 @@ function isGatewayConfigured() {
883
1130
  }
884
1131
 
885
1132
  // src/tracing/observe.ts
886
- import { trace as trace2, context, SpanStatusCode } from "@opentelemetry/api";
1133
+ import { trace as trace3, context, SpanStatusCode } from "@opentelemetry/api";
887
1134
  function asAttr(value) {
888
1135
  return typeof value === "string" ? value : JSON.stringify(value);
889
1136
  }
890
1137
  async function observe(name, fn, options = {}) {
891
- const tracer = options.tracer ?? trace2.getTracer("@withgateway/sdk");
1138
+ const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
892
1139
  const span = tracer.startSpan(name, {
893
1140
  attributes: {
894
1141
  "openinference.span.kind": options.kind ?? "AGENT",
@@ -898,7 +1145,7 @@ async function observe(name, fn, options = {}) {
898
1145
  });
899
1146
  try {
900
1147
  const result = await context.with(
901
- trace2.setSpan(context.active(), span),
1148
+ trace3.setSpan(context.active(), span),
902
1149
  fn
903
1150
  );
904
1151
  if (options.captureOutput !== false && result !== void 0) {
@@ -956,7 +1203,7 @@ function observeAnthropic(client) {
956
1203
 
957
1204
  // src/tracing/claude.ts
958
1205
  import {
959
- trace as trace3,
1206
+ trace as trace4,
960
1207
  context as context2,
961
1208
  SpanStatusCode as SpanStatusCode2
962
1209
  } from "@opentelemetry/api";
@@ -973,7 +1220,7 @@ function toolResultText(content) {
973
1220
  }
974
1221
  var TURN_INPUT_MAX = 4e3;
975
1222
  async function* observeClaude(stream, options) {
976
- const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
1223
+ const tracer = options.tracer ?? trace4.getTracer("@withgateway/sdk");
977
1224
  const model = options.model ?? "claude";
978
1225
  const openTools = /* @__PURE__ */ new Map();
979
1226
  let root = null;
@@ -986,7 +1233,7 @@ async function* observeClaude(stream, options) {
986
1233
  ...options.attributes ?? {}
987
1234
  }
988
1235
  });
989
- rootCtx = trace3.setSpan(context2.active(), root);
1236
+ rootCtx = trace4.setSpan(context2.active(), root);
990
1237
  }
991
1238
  let turnRoot = null;
992
1239
  let turnCtx = null;
@@ -1019,7 +1266,7 @@ async function* observeClaude(stream, options) {
1019
1266
  ...options.attributes ?? {}
1020
1267
  }
1021
1268
  });
1022
- turnCtx = trace3.setSpan(context2.active(), turnRoot);
1269
+ turnCtx = trace4.setSpan(context2.active(), turnRoot);
1023
1270
  pendingTurnInput = "";
1024
1271
  }
1025
1272
  const childCtx = options.perTurn ? turnCtx : rootCtx;