@withgateway/sdk 0.1.12 → 0.1.13

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.13",
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,11 @@ 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"
74
79
  }
75
80
  },
76
81
  files: [
@@ -420,6 +425,216 @@ function debugLog(message, ...args) {
420
425
  }
421
426
  }
422
427
 
428
+ // src/scores/index.ts
429
+ import { isSpanContextValid as isSpanContextValid2, trace as trace2 } from "@opentelemetry/api";
430
+ var SUCCESS_SIGNAL_KEY = "gateway.success.signal";
431
+ var SUCCESS_METRIC_NAME_KEY = "gateway.success.metricName";
432
+ var AGENT_ID_KEY = "gateway.agent.id";
433
+ var ScoreError = class extends Error {
434
+ constructor(message, options) {
435
+ super(message);
436
+ this.name = "ScoreError";
437
+ this.cause = options?.cause;
438
+ }
439
+ };
440
+ function currentTraceId() {
441
+ try {
442
+ const span = trace2.getActiveSpan();
443
+ if (!span) return void 0;
444
+ const ctx = span.spanContext();
445
+ if (!ctx || !isSpanContextValid2(ctx)) return void 0;
446
+ return ctx.traceId;
447
+ } catch {
448
+ return void 0;
449
+ }
450
+ }
451
+ var ScoresClient = class _ScoresClient {
452
+ host;
453
+ publicKey;
454
+ secretKey;
455
+ timeoutSeconds;
456
+ debug;
457
+ constructor(config) {
458
+ this.host = config.host.replace(/\/$/, "");
459
+ this.publicKey = config.publicKey;
460
+ this.secretKey = config.secretKey;
461
+ this.timeoutSeconds = config.timeoutSeconds ?? 15;
462
+ this.debug = config.debug ?? false;
463
+ }
464
+ /** Create a client from GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY. */
465
+ static fromEnv(config = {}) {
466
+ const host = config.host ?? process.env.GATEWAY_HOST;
467
+ const publicKey = config.publicKey ?? process.env.GATEWAY_PUBLIC_KEY;
468
+ const secretKey = config.secretKey ?? process.env.GATEWAY_SECRET_KEY;
469
+ const missing = [
470
+ ["host", host],
471
+ ["publicKey", publicKey],
472
+ ["secretKey", secretKey]
473
+ ].filter(([, value]) => !value).map(([name]) => name);
474
+ if (missing.length > 0) {
475
+ throw new ScoreError(
476
+ `Missing Gateway scores configuration: ${missing.join(", ")}`
477
+ );
478
+ }
479
+ return new _ScoresClient({
480
+ ...config,
481
+ host,
482
+ publicKey,
483
+ secretKey
484
+ });
485
+ }
486
+ /**
487
+ * Post a score, throwing {@link ScoreError} on any failure. Builds the exact
488
+ * `POST /api/public/scores` body the Python SDK sends: exactly one of
489
+ * `sessionId` / `traceId` (+ optional `observationId`) / `datasetRunId`.
490
+ * When no target is provided, the active OTel trace id is used; if none is
491
+ * available the call is a no-op (returns without posting), matching Python.
492
+ */
493
+ async postScore(name, value, options = {}) {
494
+ const body = this.buildScoreBody(name, value, options);
495
+ if (!body) {
496
+ this.log(
497
+ "score '%s' dropped: no sessionId, traceId or datasetRunId available",
498
+ name
499
+ );
500
+ return;
501
+ }
502
+ await this.request("POST", "/api/public/scores", body);
503
+ }
504
+ /**
505
+ * Build the score request body, or null when no target can be resolved.
506
+ * Split out so it is unit-testable and shared by score()/success().
507
+ */
508
+ buildScoreBody(name, value, options = {}) {
509
+ const traceId = options.traceId ?? currentTraceId();
510
+ const target = {};
511
+ if (options.sessionId) {
512
+ target.sessionId = options.sessionId;
513
+ } else if (options.datasetRunId) {
514
+ target.datasetRunId = options.datasetRunId;
515
+ } else if (traceId) {
516
+ target.traceId = traceId;
517
+ if (options.observationId) target.observationId = options.observationId;
518
+ } else {
519
+ return null;
520
+ }
521
+ const metadata = {
522
+ source: "gatewaysdk",
523
+ ...options.metadata ?? {}
524
+ };
525
+ return {
526
+ name,
527
+ value,
528
+ dataType: options.dataType ?? "NUMERIC",
529
+ environment: options.environment ?? "default",
530
+ ...options.comment ? { comment: options.comment } : {},
531
+ metadata,
532
+ ...target
533
+ };
534
+ }
535
+ /**
536
+ * Post a score, FAIL-SOFT: warns and resolves on any failure so a broken
537
+ * transport never throws into (or rejects out of) the caller.
538
+ */
539
+ async score(name, value, options = {}) {
540
+ try {
541
+ await this.postScore(name, value, options);
542
+ } catch (error) {
543
+ this.warn(`score '${name}' failed`, error);
544
+ }
545
+ }
546
+ /**
547
+ * Emit a SUCCESS SIGNAL that feeds a Gateway Success Metric — a score tagged
548
+ * with `gateway.success.signal` + `gateway.success.metricName` (and the agent
549
+ * identity when `agentId` is set). A boolean `value` records a 1/0 BOOLEAN
550
+ * score (pass/fail); a number records a NUMERIC score. FAIL-SOFT.
551
+ *
552
+ * The metadata shape matches the Python SDK's `Run.success()` exactly, so the
553
+ * platform's Success Metrics aggregation counts signals from either SDK
554
+ * without change.
555
+ *
556
+ * @example
557
+ * ```ts
558
+ * await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
559
+ * await scores.success("handle_time_s", 42, { agentId: "support-triage", sessionId });
560
+ * ```
561
+ */
562
+ async success(name, value = true, options = {}) {
563
+ const { numericValue, inferredType } = coerceSignalValue(value);
564
+ const { agentId, metricName, metadata, dataType, ...rest } = options;
565
+ const signalMetadata = {
566
+ ...metadata ?? {},
567
+ [SUCCESS_SIGNAL_KEY]: true,
568
+ [SUCCESS_METRIC_NAME_KEY]: metricName ?? name,
569
+ ...agentId ? { [AGENT_ID_KEY]: agentId } : {}
570
+ };
571
+ await this.score(name, numericValue, {
572
+ ...rest,
573
+ dataType: dataType ?? inferredType,
574
+ metadata: signalMetadata
575
+ });
576
+ }
577
+ async request(method, path, payload) {
578
+ let response;
579
+ try {
580
+ response = await fetch(`${this.host}${path}`, {
581
+ method,
582
+ headers: {
583
+ Authorization: this.authHeader(),
584
+ "Content-Type": "application/json"
585
+ },
586
+ body: JSON.stringify(payload),
587
+ signal: AbortSignal.timeout(this.timeoutSeconds * 1e3)
588
+ });
589
+ } catch (error) {
590
+ throw new ScoreError(
591
+ `${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
592
+ { cause: error }
593
+ );
594
+ }
595
+ const text = await response.text();
596
+ if (!response.ok) {
597
+ throw new ScoreError(
598
+ `${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`
599
+ );
600
+ }
601
+ this.log("%s %s -> %s", method, path, response.status);
602
+ }
603
+ authHeader() {
604
+ return `Basic ${Buffer.from(`${this.publicKey}:${this.secretKey}`).toString(
605
+ "base64"
606
+ )}`;
607
+ }
608
+ log(message, ...args) {
609
+ if (this.debug) {
610
+ console.log(`[gateway.scores] ${message}`, ...args);
611
+ }
612
+ }
613
+ warn(message, ...args) {
614
+ console.warn(`[gateway.scores] ${message}`, ...args);
615
+ }
616
+ };
617
+ function coerceSignalValue(value) {
618
+ if (typeof value === "boolean") {
619
+ return { numericValue: value ? 1 : 0, inferredType: "BOOLEAN" };
620
+ }
621
+ return { numericValue: value, inferredType: "NUMERIC" };
622
+ }
623
+ async function success(name, value = true, options = {}) {
624
+ let client;
625
+ try {
626
+ client = ScoresClient.fromEnv();
627
+ } catch (error) {
628
+ console.warn(`[gateway.scores] success '${name}' skipped`, error);
629
+ return;
630
+ }
631
+ await client.success(name, value, options);
632
+ }
633
+ var scores = {
634
+ fromEnv: ScoresClient.fromEnv,
635
+ success
636
+ };
637
+
423
638
  // src/build/index.ts
424
639
  import { createHash } from "crypto";
425
640
  function canonicalJson(value) {
@@ -824,12 +1039,19 @@ function initIsolated(config = {}) {
824
1039
  const provider = built.provider;
825
1040
  scheduleBuildRegistration(config, built);
826
1041
  const tracer = provider.getTracer("@withgateway/sdk");
1042
+ const scores2 = new ScoresClient({
1043
+ host: built.connection.host,
1044
+ publicKey: built.connection.publicKey,
1045
+ secretKey: built.connection.secretKey,
1046
+ debug: config.debug ?? false
1047
+ });
827
1048
  debugLog2(
828
1049
  "Isolated tracing provider created (service=%s)",
829
1050
  config.serviceName ?? "gatewaysdk-tracing"
830
1051
  );
831
1052
  return {
832
1053
  tracer,
1054
+ scores: scores2,
833
1055
  async flush() {
834
1056
  try {
835
1057
  await provider.forceFlush();
@@ -883,12 +1105,12 @@ function isGatewayConfigured() {
883
1105
  }
884
1106
 
885
1107
  // src/tracing/observe.ts
886
- import { trace as trace2, context, SpanStatusCode } from "@opentelemetry/api";
1108
+ import { trace as trace3, context, SpanStatusCode } from "@opentelemetry/api";
887
1109
  function asAttr(value) {
888
1110
  return typeof value === "string" ? value : JSON.stringify(value);
889
1111
  }
890
1112
  async function observe(name, fn, options = {}) {
891
- const tracer = options.tracer ?? trace2.getTracer("@withgateway/sdk");
1113
+ const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
892
1114
  const span = tracer.startSpan(name, {
893
1115
  attributes: {
894
1116
  "openinference.span.kind": options.kind ?? "AGENT",
@@ -898,7 +1120,7 @@ async function observe(name, fn, options = {}) {
898
1120
  });
899
1121
  try {
900
1122
  const result = await context.with(
901
- trace2.setSpan(context.active(), span),
1123
+ trace3.setSpan(context.active(), span),
902
1124
  fn
903
1125
  );
904
1126
  if (options.captureOutput !== false && result !== void 0) {
@@ -956,7 +1178,7 @@ function observeAnthropic(client) {
956
1178
 
957
1179
  // src/tracing/claude.ts
958
1180
  import {
959
- trace as trace3,
1181
+ trace as trace4,
960
1182
  context as context2,
961
1183
  SpanStatusCode as SpanStatusCode2
962
1184
  } from "@opentelemetry/api";
@@ -973,7 +1195,7 @@ function toolResultText(content) {
973
1195
  }
974
1196
  var TURN_INPUT_MAX = 4e3;
975
1197
  async function* observeClaude(stream, options) {
976
- const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
1198
+ const tracer = options.tracer ?? trace4.getTracer("@withgateway/sdk");
977
1199
  const model = options.model ?? "claude";
978
1200
  const openTools = /* @__PURE__ */ new Map();
979
1201
  let root = null;
@@ -986,7 +1208,7 @@ async function* observeClaude(stream, options) {
986
1208
  ...options.attributes ?? {}
987
1209
  }
988
1210
  });
989
- rootCtx = trace3.setSpan(context2.active(), root);
1211
+ rootCtx = trace4.setSpan(context2.active(), root);
990
1212
  }
991
1213
  let turnRoot = null;
992
1214
  let turnCtx = null;
@@ -1019,7 +1241,7 @@ async function* observeClaude(stream, options) {
1019
1241
  ...options.attributes ?? {}
1020
1242
  }
1021
1243
  });
1022
- turnCtx = trace3.setSpan(context2.active(), turnRoot);
1244
+ turnCtx = trace4.setSpan(context2.active(), turnRoot);
1023
1245
  pendingTurnInput = "";
1024
1246
  }
1025
1247
  const childCtx = options.perTurn ? turnCtx : rootCtx;