@withgateway/sdk 0.1.11 → 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.11",
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) {
@@ -438,11 +653,17 @@ function sha256(text) {
438
653
  var registeredTools = /* @__PURE__ */ new Map();
439
654
  var registeredPrompts = /* @__PURE__ */ new Map();
440
655
  var registeredSkills = /* @__PURE__ */ new Map();
656
+ var registeredArtifacts = /* @__PURE__ */ new Map();
441
657
  function getRegisteredTools() {
442
658
  return [...registeredTools.values()].sort(
443
659
  (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
444
660
  );
445
661
  }
662
+ function getRegisteredArtifacts() {
663
+ return [...registeredArtifacts.values()].sort(
664
+ (a, b) => `${a.kind}:${a.name}` < `${b.kind}:${b.name}` ? -1 : 1
665
+ );
666
+ }
446
667
  function getRegisteredSkills() {
447
668
  return Object.fromEntries(
448
669
  [...registeredSkills.entries()].sort(
@@ -465,11 +686,62 @@ function sdkVersion() {
465
686
  return "@withgateway/sdk";
466
687
  }
467
688
  }
689
+ function paasGitContext() {
690
+ const env = process.env;
691
+ if (env.VERCEL_GIT_COMMIT_SHA) {
692
+ const isGithub = (env.VERCEL_GIT_PROVIDER ?? "github") === "github";
693
+ return {
694
+ provider: "vercel",
695
+ sha: env.VERCEL_GIT_COMMIT_SHA,
696
+ repo: isGithub && env.VERCEL_GIT_REPO_OWNER && env.VERCEL_GIT_REPO_SLUG ? `${env.VERCEL_GIT_REPO_OWNER}/${env.VERCEL_GIT_REPO_SLUG}` : void 0,
697
+ branch: env.VERCEL_GIT_COMMIT_REF,
698
+ login: env.VERCEL_GIT_COMMIT_AUTHOR_LOGIN
699
+ };
700
+ }
701
+ if (env.RENDER_GIT_COMMIT) {
702
+ return {
703
+ provider: "render",
704
+ sha: env.RENDER_GIT_COMMIT,
705
+ repo: env.RENDER_GIT_REPO_SLUG,
706
+ // already "owner/repo"
707
+ branch: env.RENDER_GIT_BRANCH
708
+ };
709
+ }
710
+ if (env.RAILWAY_GIT_COMMIT_SHA) {
711
+ return {
712
+ provider: "railway",
713
+ sha: env.RAILWAY_GIT_COMMIT_SHA,
714
+ repo: env.RAILWAY_GIT_REPO_OWNER && env.RAILWAY_GIT_REPO_NAME ? `${env.RAILWAY_GIT_REPO_OWNER}/${env.RAILWAY_GIT_REPO_NAME}` : void 0,
715
+ branch: env.RAILWAY_GIT_BRANCH,
716
+ login: env.RAILWAY_GIT_AUTHOR
717
+ };
718
+ }
719
+ if (env.NETLIFY && env.COMMIT_REF) {
720
+ const repoMatch = /github\.com[/:]([^/]+\/[^/.]+)/.exec(
721
+ env.REPOSITORY_URL ?? ""
722
+ );
723
+ return {
724
+ provider: "netlify",
725
+ sha: env.COMMIT_REF,
726
+ repo: repoMatch?.[1],
727
+ branch: env.BRANCH
728
+ };
729
+ }
730
+ const bareSha = env.HEROKU_SLUG_COMMIT ?? env.SOURCE_VERSION ?? env.GIT_COMMIT ?? env.COMMIT_SHA;
731
+ if (bareSha) {
732
+ return {
733
+ provider: env.HEROKU_SLUG_COMMIT || env.SOURCE_VERSION ? "heroku" : "generic",
734
+ sha: bareSha
735
+ };
736
+ }
737
+ return null;
738
+ }
468
739
  function codeRef() {
740
+ const paas = paasGitContext();
469
741
  const sha = process.env.GATEWAY_COMMIT ?? process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? // GitLab
470
- process.env.CIRCLE_SHA1;
742
+ process.env.CIRCLE_SHA1 ?? paas?.sha;
471
743
  if (!sha) return void 0;
472
- const repo = process.env.GITHUB_REPOSITORY ?? process.env.CI_PROJECT_PATH;
744
+ const repo = process.env.GITHUB_REPOSITORY ?? process.env.CI_PROJECT_PATH ?? paas?.repo;
473
745
  return repo ? `git:${repo}@${sha}` : `git:${sha}`;
474
746
  }
475
747
  function assembleManifest(agentId) {
@@ -479,13 +751,17 @@ function assembleManifest(agentId) {
479
751
  sdk: sdkVersion(),
480
752
  tools: getRegisteredTools(),
481
753
  prompts: getRegisteredPrompts(),
482
- skills: getRegisteredSkills()
754
+ skills: getRegisteredSkills(),
755
+ artifacts: getRegisteredArtifacts()
483
756
  };
484
757
  }
485
758
  function computeBuildHash(manifest) {
486
759
  const identity = {
487
760
  ...manifest,
488
- tools: manifest.tools.map(({ source: _source, ...tool }) => tool)
761
+ tools: manifest.tools.map(({ source: _source, ...tool }) => tool),
762
+ artifacts: manifest.artifacts.map(
763
+ ({ source: _source, ...artifact }) => artifact
764
+ )
489
765
  };
490
766
  return sha256(canonicalJson(identity));
491
767
  }
@@ -498,6 +774,14 @@ function attributionFromEnv() {
498
774
  if (process.env.GITHUB_REPOSITORY) attribution.repo = process.env.GITHUB_REPOSITORY;
499
775
  const branch = process.env.GITHUB_HEAD_REF ?? process.env.GITHUB_REF_NAME;
500
776
  if (branch) attribution.branch = branch;
777
+ const paas = paasGitContext();
778
+ if (paas) {
779
+ if (attribution.source === "runtime") attribution.source = `paas:${paas.provider}`;
780
+ if (!attribution.commitSha && paas.sha) attribution.commitSha = paas.sha;
781
+ if (!attribution.repo && paas.repo) attribution.repo = paas.repo;
782
+ if (!attribution.branch && paas.branch) attribution.branch = paas.branch;
783
+ if (!attribution.githubLogin && paas.login) attribution.githubLogin = paas.login;
784
+ }
501
785
  const ref = process.env.GITHUB_REF ?? "";
502
786
  const prMatch = /refs\/pull\/(\d+)\//.exec(ref);
503
787
  if (prMatch) attribution.prNumber = Number(prMatch[1]);
@@ -755,12 +1039,19 @@ function initIsolated(config = {}) {
755
1039
  const provider = built.provider;
756
1040
  scheduleBuildRegistration(config, built);
757
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
+ });
758
1048
  debugLog2(
759
1049
  "Isolated tracing provider created (service=%s)",
760
1050
  config.serviceName ?? "gatewaysdk-tracing"
761
1051
  );
762
1052
  return {
763
1053
  tracer,
1054
+ scores: scores2,
764
1055
  async flush() {
765
1056
  try {
766
1057
  await provider.forceFlush();
@@ -814,12 +1105,12 @@ function isGatewayConfigured() {
814
1105
  }
815
1106
 
816
1107
  // src/tracing/observe.ts
817
- import { trace as trace2, context, SpanStatusCode } from "@opentelemetry/api";
1108
+ import { trace as trace3, context, SpanStatusCode } from "@opentelemetry/api";
818
1109
  function asAttr(value) {
819
1110
  return typeof value === "string" ? value : JSON.stringify(value);
820
1111
  }
821
1112
  async function observe(name, fn, options = {}) {
822
- const tracer = options.tracer ?? trace2.getTracer("@withgateway/sdk");
1113
+ const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
823
1114
  const span = tracer.startSpan(name, {
824
1115
  attributes: {
825
1116
  "openinference.span.kind": options.kind ?? "AGENT",
@@ -829,7 +1120,7 @@ async function observe(name, fn, options = {}) {
829
1120
  });
830
1121
  try {
831
1122
  const result = await context.with(
832
- trace2.setSpan(context.active(), span),
1123
+ trace3.setSpan(context.active(), span),
833
1124
  fn
834
1125
  );
835
1126
  if (options.captureOutput !== false && result !== void 0) {
@@ -887,7 +1178,7 @@ function observeAnthropic(client) {
887
1178
 
888
1179
  // src/tracing/claude.ts
889
1180
  import {
890
- trace as trace3,
1181
+ trace as trace4,
891
1182
  context as context2,
892
1183
  SpanStatusCode as SpanStatusCode2
893
1184
  } from "@opentelemetry/api";
@@ -904,7 +1195,7 @@ function toolResultText(content) {
904
1195
  }
905
1196
  var TURN_INPUT_MAX = 4e3;
906
1197
  async function* observeClaude(stream, options) {
907
- const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
1198
+ const tracer = options.tracer ?? trace4.getTracer("@withgateway/sdk");
908
1199
  const model = options.model ?? "claude";
909
1200
  const openTools = /* @__PURE__ */ new Map();
910
1201
  let root = null;
@@ -917,7 +1208,7 @@ async function* observeClaude(stream, options) {
917
1208
  ...options.attributes ?? {}
918
1209
  }
919
1210
  });
920
- rootCtx = trace3.setSpan(context2.active(), root);
1211
+ rootCtx = trace4.setSpan(context2.active(), root);
921
1212
  }
922
1213
  let turnRoot = null;
923
1214
  let turnCtx = null;
@@ -950,7 +1241,7 @@ async function* observeClaude(stream, options) {
950
1241
  ...options.attributes ?? {}
951
1242
  }
952
1243
  });
953
- turnCtx = trace3.setSpan(context2.active(), turnRoot);
1244
+ turnCtx = trace4.setSpan(context2.active(), turnRoot);
954
1245
  pendingTurnInput = "";
955
1246
  }
956
1247
  const childCtx = options.perTurn ? turnCtx : rootCtx;