@copilotkit/shared 1.72.0 → 1.73.0

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 (64) hide show
  1. package/LICENSE +21 -0
  2. package/dist/finalize-events.cjs +92 -71
  3. package/dist/finalize-events.cjs.map +1 -1
  4. package/dist/finalize-events.d.cts +20 -1
  5. package/dist/finalize-events.d.cts.map +1 -1
  6. package/dist/finalize-events.d.mts +20 -1
  7. package/dist/finalize-events.d.mts.map +1 -1
  8. package/dist/finalize-events.mjs +92 -72
  9. package/dist/finalize-events.mjs.map +1 -1
  10. package/dist/index.cjs +7 -0
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +4 -3
  13. package/dist/index.d.cts.map +1 -1
  14. package/dist/index.d.mts +4 -3
  15. package/dist/index.d.mts.map +1 -1
  16. package/dist/index.mjs +4 -3
  17. package/dist/index.mjs.map +1 -1
  18. package/dist/index.umd.js +218 -72
  19. package/dist/index.umd.js.map +1 -1
  20. package/dist/package.cjs +1 -1
  21. package/dist/package.mjs +1 -1
  22. package/dist/telemetry/events.d.cts +33 -0
  23. package/dist/telemetry/events.d.cts.map +1 -1
  24. package/dist/telemetry/events.d.mts +33 -0
  25. package/dist/telemetry/events.d.mts.map +1 -1
  26. package/dist/telemetry/index.cjs +3 -0
  27. package/dist/telemetry/index.d.cts +2 -2
  28. package/dist/telemetry/index.d.mts +2 -2
  29. package/dist/telemetry/index.mjs +2 -2
  30. package/dist/telemetry/model-host.cjs +104 -0
  31. package/dist/telemetry/model-host.cjs.map +1 -0
  32. package/dist/telemetry/model-host.d.cts +26 -0
  33. package/dist/telemetry/model-host.d.cts.map +1 -0
  34. package/dist/telemetry/model-host.d.mts +26 -0
  35. package/dist/telemetry/model-host.d.mts.map +1 -0
  36. package/dist/telemetry/model-host.mjs +102 -0
  37. package/dist/telemetry/model-host.mjs.map +1 -0
  38. package/dist/telemetry/sampling.cjs +22 -0
  39. package/dist/telemetry/sampling.cjs.map +1 -1
  40. package/dist/telemetry/sampling.d.cts +22 -2
  41. package/dist/telemetry/sampling.d.cts.map +1 -1
  42. package/dist/telemetry/sampling.d.mts +22 -2
  43. package/dist/telemetry/sampling.d.mts.map +1 -1
  44. package/dist/telemetry/sampling.mjs +20 -1
  45. package/dist/telemetry/sampling.mjs.map +1 -1
  46. package/dist/telemetry/telemetry-client.cjs +18 -11
  47. package/dist/telemetry/telemetry-client.cjs.map +1 -1
  48. package/dist/telemetry/telemetry-client.d.cts +3 -3
  49. package/dist/telemetry/telemetry-client.d.cts.map +1 -1
  50. package/dist/telemetry/telemetry-client.d.mts +3 -3
  51. package/dist/telemetry/telemetry-client.d.mts.map +1 -1
  52. package/dist/telemetry/telemetry-client.mjs +19 -12
  53. package/dist/telemetry/telemetry-client.mjs.map +1 -1
  54. package/package.json +1 -1
  55. package/src/finalize-events.test.ts +146 -0
  56. package/src/finalize-events.ts +124 -124
  57. package/src/index.ts +9 -1
  58. package/src/telemetry/events.ts +33 -0
  59. package/src/telemetry/model-host.test.ts +145 -0
  60. package/src/telemetry/model-host.ts +155 -0
  61. package/src/telemetry/sampling.ts +39 -6
  62. package/src/telemetry/telemetry-blank-license-identity.test.ts +11 -4
  63. package/src/telemetry/telemetry-client.test.ts +107 -39
  64. package/src/telemetry/telemetry-client.ts +48 -27
@@ -7,7 +7,12 @@ import {
7
7
  lambdaClient,
8
8
  parseAndWarnTelemetryId,
9
9
  } from "./lambda-client";
10
- import { computeSamplingMeta, TELEMETRY_EMITTER_V1 } from "./sampling";
10
+ import {
11
+ computeSamplingMeta,
12
+ TELEMETRY_EMITTER_V1,
13
+ TELEMETRY_SURFACE_V1,
14
+ UNSAMPLED_RATE,
15
+ } from "./sampling";
11
16
  import { isTelemetryDisabled } from "./telemetry-disabled";
12
17
 
13
18
  export { isTelemetryDisabled };
@@ -45,16 +50,18 @@ export class TelemetryClient {
45
50
  // the Lambda transport.
46
51
  private telemetryId: string | null = null;
47
52
  // License-derived identity used only as sampling authority. A standalone
48
- // telemetry id remains a transport claim and does not bypass sampleRate.
53
+ // telemetry id remains a transport claim and does not bypass the
54
+ // Segment gate.
49
55
  private licenseTelemetryId: string | null = null;
50
56
  packageName: string;
51
57
  packageVersion: string;
52
58
  private telemetryDisabled: boolean = false;
53
- // Client-side sampling rate for anonymous events. Identified events
54
- // (those whose license token yielded a telemetry_id) bypass the gate
55
- // entirely. Applied uniformly to both the lambda sink and Segment —
56
- // one dice roll per capture, both sinks see the same decision.
57
- private sampleRate: number = 0.05;
59
+ // Client-side sampling rate for anonymous events on the Segment wire
60
+ // only. The lambda sink is ours and takes every event; Segment is
61
+ // billed per event, so the anonymous population stays capped there.
62
+ // Identified events (those whose license token yielded a telemetry_id)
63
+ // bypass the gate on both wires.
64
+ private segmentSampleRate: number = 0.05;
58
65
  private anonymousId = `anon_${uuidv4()}`;
59
66
 
60
67
  constructor({
@@ -68,6 +75,8 @@ export class TelemetryClient {
68
75
  packageVersion: string;
69
76
  telemetryDisabled?: boolean;
70
77
  telemetryBaseUrl?: string;
78
+ // Anonymous sampling rate for the Segment wire. Named without the
79
+ // prefix for backward compatibility; the lambda sink ignores it.
71
80
  sampleRate?: number;
72
81
  }) {
73
82
  this.packageName = packageName;
@@ -95,9 +104,9 @@ export class TelemetryClient {
95
104
  });
96
105
  }
97
106
 
98
- private shouldSendEvent() {
107
+ private shouldSendToSegment() {
99
108
  const randomNumber = Math.random();
100
- return randomNumber < this.sampleRate;
109
+ return randomNumber < this.segmentSampleRate;
101
110
  }
102
111
 
103
112
  async capture<K extends keyof AnalyticsEvents>(
@@ -120,19 +129,29 @@ export class TelemetryClient {
120
129
  return;
121
130
  }
122
131
 
123
- // Callers without license-derived sampling authority are gated by
124
- // sampleRate. Legacy license tokens with telemetry_id always send —
125
- // the volume is bounded by paying-customer count and full fidelity
126
- // per identified customer is worth the marginal cost.
127
- if (!identity.licenseTelemetryId && !this.shouldSendEvent()) {
128
- return;
129
- }
132
+ // The two wires are gated separately. The lambda sink takes every
133
+ // event: it is CopilotKit-owned, so anonymous volume costs nothing
134
+ // per event there and a real count beats one extrapolated from 5% of
135
+ // the population. Segment is billed per event, so it keeps the gate —
136
+ // callers without license-derived sampling authority are dropped from
137
+ // that copy at segmentSampleRate. Legacy license tokens with a
138
+ // telemetry_id send on both wires: the volume is bounded by
139
+ // paying-customer count and full fidelity per identified customer is
140
+ // worth the marginal cost.
141
+ const sendToSegment =
142
+ Boolean(identity.licenseTelemetryId) || this.shouldSendToSegment();
130
143
 
131
144
  // Sampling metadata is computed in ./sampling so this client and the
132
145
  // v2 runtime client can't drift apart again — see the note there.
133
- const samplingMeta = computeSamplingMeta({
146
+ // One call per wire, because the two wires were gated differently and
147
+ // a shared block would overweight the lambda copy by 1/sampleRate.
148
+ const lambdaSamplingMeta = computeSamplingMeta({
149
+ telemetryId: identity.licenseTelemetryId,
150
+ sampleRate: UNSAMPLED_RATE,
151
+ });
152
+ const segmentSamplingMeta = computeSamplingMeta({
134
153
  telemetryId: identity.licenseTelemetryId,
135
- sampleRate: this.sampleRate,
154
+ sampleRate: this.segmentSampleRate,
136
155
  });
137
156
 
138
157
  // Everything below travels identically on both copies of this event.
@@ -142,8 +161,8 @@ export class TelemetryClient {
142
161
  // duplication from $lib or from which fields happen to be present
143
162
  // (OSS-1019).
144
163
  const eventMeta = {
145
- ...samplingMeta,
146
164
  telemetry_emitter: TELEMETRY_EMITTER_V1,
165
+ telemetry_surface: TELEMETRY_SURFACE_V1,
147
166
  telemetry_event_id: uuidv4(),
148
167
  };
149
168
 
@@ -151,6 +170,7 @@ export class TelemetryClient {
151
170
  const propertiesWithGlobal: Record<string, any> = {
152
171
  ...this.globalProperties,
153
172
  ...eventMeta,
173
+ ...segmentSamplingMeta,
154
174
  telemetry_transport: "segment",
155
175
  ...flattenedProperties,
156
176
  };
@@ -170,6 +190,7 @@ export class TelemetryClient {
170
190
  globalProperties: {
171
191
  ...this.globalProperties,
172
192
  ...eventMeta,
193
+ ...lambdaSamplingMeta,
173
194
  telemetry_transport: "lambda",
174
195
  },
175
196
  packageName: this.packageName,
@@ -178,7 +199,7 @@ export class TelemetryClient {
178
199
  licenseToken: identity.licenseToken ?? undefined,
179
200
  });
180
201
 
181
- if (this.segment) {
202
+ if (this.segment && sendToSegment) {
182
203
  this.segment.track({
183
204
  anonymousId: this.anonymousId,
184
205
  event,
@@ -238,7 +259,7 @@ export class TelemetryClient {
238
259
  * Create an immutable capture scope for one runtime.
239
260
  *
240
261
  * The scope shares this client's sinks, process-wide opt-out, global
241
- * properties, and sampling settings, but snapshots transport identity and
262
+ * properties, and Segment sampling rate, but snapshots transport identity and
242
263
  * license-derived sampling authority. Constructing another runtime cannot
243
264
  * rewrite an existing scope.
244
265
  *
@@ -290,16 +311,16 @@ export class TelemetryClient {
290
311
 
291
312
  // Number.isNaN guards against parseFloat("nonsense") slipping past the
292
313
  // range check (all NaN comparisons are false), which would silently
293
- // drop every anonymous event with no signal — especially important
294
- // since the default is now 0.05, making env-var overrides more common.
314
+ // drop every anonymous Segment event with no signal.
295
315
  if (Number.isNaN(_sampleRate) || _sampleRate < 0 || _sampleRate > 1) {
296
316
  throw new Error("Sample rate must be between 0 and 1");
297
317
  }
298
318
 
299
- this.sampleRate = _sampleRate;
319
+ this.segmentSampleRate = _sampleRate;
300
320
  // Per-event sampling metadata (sampleRate/sampleRateAdjustmentFactor/
301
- // sampleWeight) is computed per capture() in ./sampling. Only license-
302
- // authorized events get effectiveSampleRate=1; standalone transport
303
- // identity stays in the sampled population.
321
+ // sampleWeight) is computed per capture() in ./sampling, once per
322
+ // wire. Only license-authorized events get effectiveSampleRate=1 on
323
+ // the Segment copy; standalone transport identity stays in the
324
+ // sampled population there. The lambda copy is always unsampled.
304
325
  }
305
326
  }