@spatius/avatarkit 1.3.1-beta.7 → 1.3.2

package/dist/internal-telemetry.d.ts

@@ -1,23 +1,4 @@
-/**
- * Internal telemetry surface for the companion RTC SDK.
- *
- * `@spatius/avatarkit-rtc` reports into the same OpenObserve backend and shares
- * this SDK's OTel providers, so its spans must sit on the same calibrated
- * timeline. Without that, a client whose wall clock is off puts RTC spans at a
- * time that does not line up with the server-side records they need to be read
- * against.
- *
- * Deliberately NOT re-exported from the package root: this is a bridge between
- * two first-party packages, not API for integrators. It exposes conversion only
- * — nothing here can alter the clock baseline.
- *
- * NOTE: nothing in this file may be tagged `@internal`. The dts plugin runs with
- * `stripInternal: true`, which erases such declarations from the emitted `.d.ts`
- * — the entry would still export both functions at runtime while shipping an
- * empty `export {}` type file, leaving the RTC package with no types.
- *
- * @packageDocumentation
- */
+import { Attributes } from '@opentelemetry/api';
 /**
  * Convert a `performance.now()` reading taken earlier into a timeline
  * timestamp (epoch ms), preferring the server-calibrated baseline and falling
@@ -35,3 +16,47 @@ export declare function resolveMonoTimestamp(mono: number): number;
  * resolve either way; this only reports whether they are server-aligned yet.
  */
 export declare function isClockCalibrated(): boolean;
+/**
+ * Handle for one round's trace.
+ *
+ * Declared here rather than re-exported from `utils/otel-trace`: the dts build
+ * excludes `utils/**`, so a type imported from there resolves to a file absent
+ * from the published package — which fails the whole module's type resolution,
+ * not just that one name.
+ *
+ * Structurally identical to the internal `PlaybackTrace`; the compiler checks
+ * the two match at `startPlaybackTrace`'s return below.
+ */
+export interface PlaybackTrace {
+    /** Add one interval span under the round's root. */
+    span(name: string, startMs: number, endMs: number, attrs?: Attributes, isError?: boolean): void;
+    /** Open a container span; spans added to the returned handle nest under it. */
+    group(name: string, startMs: number, attrs?: Attributes): SpanGroup;
+    /** Close the round's root span. */
+    end(ok?: boolean, endTimeMs?: number, attrs?: Attributes): void;
+}
+/** Sub-handle returned by {@link PlaybackTrace.group}. */
+export interface SpanGroup {
+    span(name: string, startMs: number, endMs: number, attrs?: Attributes, isError?: boolean): void;
+    end(endTimeMs?: number, attrs?: Attributes): void;
+}
+/**
+ * Open one round's trace: `driven.request` → `playback` → the caller's spans.
+ *
+ * Shared with the RTC SDK rather than reimplemented there, so both packages
+ * emit the same tree. The root's ids derive from the conversation id, which is
+ * what lets the backend's spans join a round without threading state through;
+ * reproducing that separately would mean two definitions of one wire contract.
+ */
+export declare function startPlaybackTrace(conversationId: string, startTimeMs?: number, attrs?: Attributes): PlaybackTrace;
+/**
+ * Record one measurement onto avatarkit's metric pipeline.
+ *
+ * Must go through here rather than the RTC SDK reaching for the global meter
+ * itself: a metrics export is skipped entirely unless that round carried real
+ * business data, and the flag saying so lives in this module. A histogram
+ * written directly through the global provider lands in the same instrument but
+ * leaves the flag clear, so the whole batch — RTC's readings included — is
+ * dropped before it is sent.
+ */
+export declare function recordMetric(name: string, value: number, attributes?: Attributes): void;

package/dist/internal-telemetry.js

@@ -1,4 +1,5 @@
-import { h as clockSync } from "./logger-DdmfSEn-.js";
+import { C as recordMetric$1, g as clockSync } from "./logger-gpv4NaPj.js";
+import { o as startPlaybackTrace$1 } from "./otel-trace-M2fi3yoE.js";
 //#region internal-telemetry.ts
 /**
 * Internal telemetry surface for the companion RTC SDK.
@@ -41,5 +42,29 @@ function resolveMonoTimestamp(mono) {
 function isClockCalibrated() {
 	return clockSync.isReady();
 }
+/**
+* Open one round's trace: `driven.request` → `playback` → the caller's spans.
+*
+* Shared with the RTC SDK rather than reimplemented there, so both packages
+* emit the same tree. The root's ids derive from the conversation id, which is
+* what lets the backend's spans join a round without threading state through;
+* reproducing that separately would mean two definitions of one wire contract.
+*/
+function startPlaybackTrace(conversationId, startTimeMs, attrs = {}) {
+	return startPlaybackTrace$1(conversationId, startTimeMs, attrs);
+}
+/**
+* Record one measurement onto avatarkit's metric pipeline.
+*
+* Must go through here rather than the RTC SDK reaching for the global meter
+* itself: a metrics export is skipped entirely unless that round carried real
+* business data, and the flag saying so lives in this module. A histogram
+* written directly through the global provider lands in the same instrument but
+* leaves the flag clear, so the whole batch — RTC's readings included — is
+* dropped before it is sent.
+*/
+function recordMetric(name, value, attributes = {}) {
+	recordMetric$1(name, value, attributes);
+}
 //#endregion
-export { isClockCalibrated, resolveMonoTimestamp };
+export { isClockCalibrated, recordMetric, resolveMonoTimestamp, startPlaybackTrace };