@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.
package/dist/index.mjs CHANGED
@@ -21,7 +21,7 @@ var require_package = __commonJS({
21
21
  "package.json"(exports, module) {
22
22
  module.exports = {
23
23
  name: "@withgateway/sdk",
24
- version: "0.1.12",
24
+ version: "0.1.13",
25
25
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
26
26
  main: "./dist/index.js",
27
27
  module: "./dist/index.mjs",
@@ -76,6 +76,11 @@ var require_package = __commonJS({
76
76
  types: "./dist/users/index.d.ts",
77
77
  import: "./dist/users/index.mjs",
78
78
  require: "./dist/users/index.js"
79
+ },
80
+ "./scores": {
81
+ types: "./dist/scores/index.d.ts",
82
+ import: "./dist/scores/index.mjs",
83
+ require: "./dist/scores/index.js"
79
84
  }
80
85
  },
81
86
  files: [
@@ -1388,7 +1393,7 @@ var SessionRecording = class _SessionRecording {
1388
1393
  * to re-drive the recorded conversation.
1389
1394
  */
1390
1395
  userMessages() {
1391
- return this.turns().map((trace4) => trace4.userMessage());
1396
+ return this.turns().map((trace5) => trace5.userMessage());
1392
1397
  }
1393
1398
  /** Output of the last chronological turn (null when empty). */
1394
1399
  finalOutput() {
@@ -1406,8 +1411,8 @@ var SessionRecording = class _SessionRecording {
1406
1411
  /** Filter observations across all turns (chronological order). */
1407
1412
  select(filter = {}) {
1408
1413
  const selected = [];
1409
- for (const trace4 of this.turns()) {
1410
- for (const observation of trace4.observations) {
1414
+ for (const trace5 of this.turns()) {
1415
+ for (const observation of trace5.observations) {
1411
1416
  if (filter.type && (observation.type ?? "").toUpperCase() !== filter.type.toUpperCase()) {
1412
1417
  continue;
1413
1418
  }
@@ -1427,15 +1432,15 @@ var SessionRecording = class _SessionRecording {
1427
1432
  sessionId: this.sessionId,
1428
1433
  projectId: this.projectId,
1429
1434
  environment: this.environment,
1430
- traces: this.turns().map((trace4) => ({
1431
- id: trace4.id,
1432
- name: trace4.name,
1433
- timestamp: trace4.timestamp,
1434
- input: trace4.input,
1435
- output: trace4.output,
1436
- metadata: trace4.metadata,
1437
- tags: trace4.tags,
1438
- observations: trace4.observations.map((o) => ({ ...o }))
1435
+ traces: this.turns().map((trace5) => ({
1436
+ id: trace5.id,
1437
+ name: trace5.name,
1438
+ timestamp: trace5.timestamp,
1439
+ input: trace5.input,
1440
+ output: trace5.output,
1441
+ metadata: trace5.metadata,
1442
+ tags: trace5.tags,
1443
+ observations: trace5.observations.map((o) => ({ ...o }))
1439
1444
  }))
1440
1445
  };
1441
1446
  }
@@ -2746,6 +2751,216 @@ var users = {
2746
2751
  fromEnv: UsersClient.fromEnv
2747
2752
  };
2748
2753
 
2754
+ // src/scores/index.ts
2755
+ import { isSpanContextValid, trace } from "@opentelemetry/api";
2756
+ var SUCCESS_SIGNAL_KEY = "gateway.success.signal";
2757
+ var SUCCESS_METRIC_NAME_KEY = "gateway.success.metricName";
2758
+ var AGENT_ID_KEY = "gateway.agent.id";
2759
+ var ScoreError = class extends Error {
2760
+ constructor(message, options) {
2761
+ super(message);
2762
+ this.name = "ScoreError";
2763
+ this.cause = options?.cause;
2764
+ }
2765
+ };
2766
+ function currentTraceId() {
2767
+ try {
2768
+ const span = trace.getActiveSpan();
2769
+ if (!span) return void 0;
2770
+ const ctx = span.spanContext();
2771
+ if (!ctx || !isSpanContextValid(ctx)) return void 0;
2772
+ return ctx.traceId;
2773
+ } catch {
2774
+ return void 0;
2775
+ }
2776
+ }
2777
+ var ScoresClient = class _ScoresClient {
2778
+ host;
2779
+ publicKey;
2780
+ secretKey;
2781
+ timeoutSeconds;
2782
+ debug;
2783
+ constructor(config) {
2784
+ this.host = config.host.replace(/\/$/, "");
2785
+ this.publicKey = config.publicKey;
2786
+ this.secretKey = config.secretKey;
2787
+ this.timeoutSeconds = config.timeoutSeconds ?? 15;
2788
+ this.debug = config.debug ?? false;
2789
+ }
2790
+ /** Create a client from GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY. */
2791
+ static fromEnv(config = {}) {
2792
+ const host = config.host ?? process.env.GATEWAY_HOST;
2793
+ const publicKey = config.publicKey ?? process.env.GATEWAY_PUBLIC_KEY;
2794
+ const secretKey = config.secretKey ?? process.env.GATEWAY_SECRET_KEY;
2795
+ const missing = [
2796
+ ["host", host],
2797
+ ["publicKey", publicKey],
2798
+ ["secretKey", secretKey]
2799
+ ].filter(([, value]) => !value).map(([name]) => name);
2800
+ if (missing.length > 0) {
2801
+ throw new ScoreError(
2802
+ `Missing Gateway scores configuration: ${missing.join(", ")}`
2803
+ );
2804
+ }
2805
+ return new _ScoresClient({
2806
+ ...config,
2807
+ host,
2808
+ publicKey,
2809
+ secretKey
2810
+ });
2811
+ }
2812
+ /**
2813
+ * Post a score, throwing {@link ScoreError} on any failure. Builds the exact
2814
+ * `POST /api/public/scores` body the Python SDK sends: exactly one of
2815
+ * `sessionId` / `traceId` (+ optional `observationId`) / `datasetRunId`.
2816
+ * When no target is provided, the active OTel trace id is used; if none is
2817
+ * available the call is a no-op (returns without posting), matching Python.
2818
+ */
2819
+ async postScore(name, value, options = {}) {
2820
+ const body = this.buildScoreBody(name, value, options);
2821
+ if (!body) {
2822
+ this.log(
2823
+ "score '%s' dropped: no sessionId, traceId or datasetRunId available",
2824
+ name
2825
+ );
2826
+ return;
2827
+ }
2828
+ await this.request("POST", "/api/public/scores", body);
2829
+ }
2830
+ /**
2831
+ * Build the score request body, or null when no target can be resolved.
2832
+ * Split out so it is unit-testable and shared by score()/success().
2833
+ */
2834
+ buildScoreBody(name, value, options = {}) {
2835
+ const traceId = options.traceId ?? currentTraceId();
2836
+ const target = {};
2837
+ if (options.sessionId) {
2838
+ target.sessionId = options.sessionId;
2839
+ } else if (options.datasetRunId) {
2840
+ target.datasetRunId = options.datasetRunId;
2841
+ } else if (traceId) {
2842
+ target.traceId = traceId;
2843
+ if (options.observationId) target.observationId = options.observationId;
2844
+ } else {
2845
+ return null;
2846
+ }
2847
+ const metadata = {
2848
+ source: "gatewaysdk",
2849
+ ...options.metadata ?? {}
2850
+ };
2851
+ return {
2852
+ name,
2853
+ value,
2854
+ dataType: options.dataType ?? "NUMERIC",
2855
+ environment: options.environment ?? "default",
2856
+ ...options.comment ? { comment: options.comment } : {},
2857
+ metadata,
2858
+ ...target
2859
+ };
2860
+ }
2861
+ /**
2862
+ * Post a score, FAIL-SOFT: warns and resolves on any failure so a broken
2863
+ * transport never throws into (or rejects out of) the caller.
2864
+ */
2865
+ async score(name, value, options = {}) {
2866
+ try {
2867
+ await this.postScore(name, value, options);
2868
+ } catch (error) {
2869
+ this.warn(`score '${name}' failed`, error);
2870
+ }
2871
+ }
2872
+ /**
2873
+ * Emit a SUCCESS SIGNAL that feeds a Gateway Success Metric — a score tagged
2874
+ * with `gateway.success.signal` + `gateway.success.metricName` (and the agent
2875
+ * identity when `agentId` is set). A boolean `value` records a 1/0 BOOLEAN
2876
+ * score (pass/fail); a number records a NUMERIC score. FAIL-SOFT.
2877
+ *
2878
+ * The metadata shape matches the Python SDK's `Run.success()` exactly, so the
2879
+ * platform's Success Metrics aggregation counts signals from either SDK
2880
+ * without change.
2881
+ *
2882
+ * @example
2883
+ * ```ts
2884
+ * await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
2885
+ * await scores.success("handle_time_s", 42, { agentId: "support-triage", sessionId });
2886
+ * ```
2887
+ */
2888
+ async success(name, value = true, options = {}) {
2889
+ const { numericValue, inferredType } = coerceSignalValue(value);
2890
+ const { agentId, metricName, metadata, dataType, ...rest } = options;
2891
+ const signalMetadata = {
2892
+ ...metadata ?? {},
2893
+ [SUCCESS_SIGNAL_KEY]: true,
2894
+ [SUCCESS_METRIC_NAME_KEY]: metricName ?? name,
2895
+ ...agentId ? { [AGENT_ID_KEY]: agentId } : {}
2896
+ };
2897
+ await this.score(name, numericValue, {
2898
+ ...rest,
2899
+ dataType: dataType ?? inferredType,
2900
+ metadata: signalMetadata
2901
+ });
2902
+ }
2903
+ async request(method, path, payload) {
2904
+ let response;
2905
+ try {
2906
+ response = await fetch(`${this.host}${path}`, {
2907
+ method,
2908
+ headers: {
2909
+ Authorization: this.authHeader(),
2910
+ "Content-Type": "application/json"
2911
+ },
2912
+ body: JSON.stringify(payload),
2913
+ signal: AbortSignal.timeout(this.timeoutSeconds * 1e3)
2914
+ });
2915
+ } catch (error) {
2916
+ throw new ScoreError(
2917
+ `${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
2918
+ { cause: error }
2919
+ );
2920
+ }
2921
+ const text = await response.text();
2922
+ if (!response.ok) {
2923
+ throw new ScoreError(
2924
+ `${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`
2925
+ );
2926
+ }
2927
+ this.log("%s %s -> %s", method, path, response.status);
2928
+ }
2929
+ authHeader() {
2930
+ return `Basic ${Buffer.from(`${this.publicKey}:${this.secretKey}`).toString(
2931
+ "base64"
2932
+ )}`;
2933
+ }
2934
+ log(message, ...args) {
2935
+ if (this.debug) {
2936
+ console.log(`[gateway.scores] ${message}`, ...args);
2937
+ }
2938
+ }
2939
+ warn(message, ...args) {
2940
+ console.warn(`[gateway.scores] ${message}`, ...args);
2941
+ }
2942
+ };
2943
+ function coerceSignalValue(value) {
2944
+ if (typeof value === "boolean") {
2945
+ return { numericValue: value ? 1 : 0, inferredType: "BOOLEAN" };
2946
+ }
2947
+ return { numericValue: value, inferredType: "NUMERIC" };
2948
+ }
2949
+ async function success(name, value = true, options = {}) {
2950
+ let client2;
2951
+ try {
2952
+ client2 = ScoresClient.fromEnv();
2953
+ } catch (error) {
2954
+ console.warn(`[gateway.scores] success '${name}' skipped`, error);
2955
+ return;
2956
+ }
2957
+ await client2.success(name, value, options);
2958
+ }
2959
+ var scores = {
2960
+ fromEnv: ScoresClient.fromEnv,
2961
+ success
2962
+ };
2963
+
2749
2964
  // src/build/index.ts
2750
2965
  import { createHash as createHash2 } from "crypto";
2751
2966
  function canonicalJson(value) {
@@ -3029,7 +3244,7 @@ async function registerBuild(params) {
3029
3244
 
3030
3245
  // src/tracing/identity.ts
3031
3246
  import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
3032
- import { isSpanContextValid, trace } from "@opentelemetry/api";
3247
+ import { isSpanContextValid as isSpanContextValid2, trace as trace2 } from "@opentelemetry/api";
3033
3248
  var USER_ID_ATTRIBUTE = "gateway.user.id";
3034
3249
  var currentUserStorage = new AsyncLocalStorage2();
3035
3250
  function resolveUserId() {
@@ -3043,8 +3258,8 @@ function identify(userId, options = {}) {
3043
3258
  if (!cleaned) return;
3044
3259
  currentUserStorage.enterWith(cleaned);
3045
3260
  try {
3046
- const span = trace.getActiveSpan();
3047
- if (span && isSpanContextValid(span.spanContext())) {
3261
+ const span = trace2.getActiveSpan();
3262
+ if (span && isSpanContextValid2(span.spanContext())) {
3048
3263
  span.setAttribute(USER_ID_ATTRIBUTE, cleaned);
3049
3264
  }
3050
3265
  } catch (error) {
@@ -3322,12 +3537,19 @@ function initIsolated(config = {}) {
3322
3537
  const provider = built.provider;
3323
3538
  scheduleBuildRegistration(config, built);
3324
3539
  const tracer = provider.getTracer("@withgateway/sdk");
3540
+ const scores2 = new ScoresClient({
3541
+ host: built.connection.host,
3542
+ publicKey: built.connection.publicKey,
3543
+ secretKey: built.connection.secretKey,
3544
+ debug: config.debug ?? false
3545
+ });
3325
3546
  debugLog2(
3326
3547
  "Isolated tracing provider created (service=%s)",
3327
3548
  config.serviceName ?? "gatewaysdk-tracing"
3328
3549
  );
3329
3550
  return {
3330
3551
  tracer,
3552
+ scores: scores2,
3331
3553
  async flush() {
3332
3554
  try {
3333
3555
  await provider.forceFlush();
@@ -3381,12 +3603,12 @@ function isGatewayConfigured() {
3381
3603
  }
3382
3604
 
3383
3605
  // src/tracing/observe.ts
3384
- import { trace as trace2, context as context2, SpanStatusCode } from "@opentelemetry/api";
3606
+ import { trace as trace3, context as context2, SpanStatusCode } from "@opentelemetry/api";
3385
3607
  function asAttr(value) {
3386
3608
  return typeof value === "string" ? value : JSON.stringify(value);
3387
3609
  }
3388
3610
  async function observe(name, fn, options = {}) {
3389
- const tracer = options.tracer ?? trace2.getTracer("@withgateway/sdk");
3611
+ const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
3390
3612
  const span = tracer.startSpan(name, {
3391
3613
  attributes: {
3392
3614
  "openinference.span.kind": options.kind ?? "AGENT",
@@ -3396,7 +3618,7 @@ async function observe(name, fn, options = {}) {
3396
3618
  });
3397
3619
  try {
3398
3620
  const result = await context2.with(
3399
- trace2.setSpan(context2.active(), span),
3621
+ trace3.setSpan(context2.active(), span),
3400
3622
  fn
3401
3623
  );
3402
3624
  if (options.captureOutput !== false && result !== void 0) {
@@ -3454,7 +3676,7 @@ function observeAnthropic(client2) {
3454
3676
 
3455
3677
  // src/tracing/claude.ts
3456
3678
  import {
3457
- trace as trace3,
3679
+ trace as trace4,
3458
3680
  context as context3,
3459
3681
  SpanStatusCode as SpanStatusCode2
3460
3682
  } from "@opentelemetry/api";
@@ -3471,7 +3693,7 @@ function toolResultText(content) {
3471
3693
  }
3472
3694
  var TURN_INPUT_MAX = 4e3;
3473
3695
  async function* observeClaude(stream, options) {
3474
- const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
3696
+ const tracer = options.tracer ?? trace4.getTracer("@withgateway/sdk");
3475
3697
  const model = options.model ?? "claude";
3476
3698
  const openTools = /* @__PURE__ */ new Map();
3477
3699
  let root = null;
@@ -3484,7 +3706,7 @@ async function* observeClaude(stream, options) {
3484
3706
  ...options.attributes ?? {}
3485
3707
  }
3486
3708
  });
3487
- rootCtx = trace3.setSpan(context3.active(), root);
3709
+ rootCtx = trace4.setSpan(context3.active(), root);
3488
3710
  }
3489
3711
  let turnRoot = null;
3490
3712
  let turnCtx = null;
@@ -3517,7 +3739,7 @@ async function* observeClaude(stream, options) {
3517
3739
  ...options.attributes ?? {}
3518
3740
  }
3519
3741
  });
3520
- turnCtx = trace3.setSpan(context3.active(), turnRoot);
3742
+ turnCtx = trace4.setSpan(context3.active(), turnRoot);
3521
3743
  pendingTurnInput = "";
3522
3744
  }
3523
3745
  const childCtx = options.perTurn ? turnCtx : rootCtx;
@@ -3623,6 +3845,7 @@ var tracing = {
3623
3845
  }
3624
3846
  };
3625
3847
  export {
3848
+ AGENT_ID_KEY,
3626
3849
  DEFAULT_TIMEOUT_SECONDS,
3627
3850
  DriftError,
3628
3851
  ENV_GATEWAY_HOST,
@@ -3652,6 +3875,10 @@ export {
3652
3875
  ReplayReport,
3653
3876
  ReplaySuite,
3654
3877
  ReplayTask,
3878
+ SUCCESS_METRIC_NAME_KEY,
3879
+ SUCCESS_SIGNAL_KEY,
3880
+ ScoreError,
3881
+ ScoresClient,
3655
3882
  SessionLoadError,
3656
3883
  SessionRecording,
3657
3884
  SessionTrace,
@@ -3669,6 +3896,7 @@ export {
3669
3896
  computeBuildHash,
3670
3897
  computeHash,
3671
3898
  context,
3899
+ currentTraceId,
3672
3900
  defineTool,
3673
3901
  experimentContextStorage,
3674
3902
  singleton_exports as experiments,
@@ -3691,9 +3919,11 @@ export {
3691
3919
  resolveUserId,
3692
3920
  runSuite,
3693
3921
  runWithExperimentContext,
3922
+ scores,
3694
3923
  sessionObservationFromApi,
3695
3924
  sessions,
3696
3925
  setExperimentContext,
3926
+ success,
3697
3927
  suite,
3698
3928
  tracing,
3699
3929
  users