Add internal attributes definition helper (#1534)

.prettierignore

@@ -4,5 +4,6 @@ docs/
 node_modules/
 protocol/
 src/proto/
+src/room/attributes/
 yarn.lock
 pnpm-lock.yaml

src/index.ts

@@ -4,6 +4,7 @@ import { LogLevel, LoggerNames, getLogger, setLogExtension, setLogLevel } from '
 import DefaultReconnectPolicy from './room/DefaultReconnectPolicy';
 import type { ReconnectContext, ReconnectPolicy } from './room/ReconnectPolicy';
 import Room, { ConnectionState } from './room/Room';
+import * as attributes from './room/attribute-typings';
 import LocalParticipant from './room/participant/LocalParticipant';
 import Participant, { ConnectionQuality, ParticipantKind } from './room/participant/Participant';
 import type { ParticipantTrackPermission } from './room/participant/ParticipantTrackPermission';
@@ -72,6 +73,8 @@ export type {
 } from './room/types';
 export * from './version';
 export {
+  /** @internal */
+  attributes,
   ConnectionQuality,
   ConnectionState,
   CriticalTimers,

src/room/attribute-typings.ts

@@ -0,0 +1,61 @@
+// This file was generated from JSON Schema using quicktype, do not modify it directly.
+// The code generation lives at https://github.com/livekit/attribute-definitions
+//
+// To parse this data:
+//
+//   import { Convert, AgentAttributes, TranscriptionAttributes } from "./file";
+//
+//   const agentAttributes = Convert.toAgentAttributes(json);
+//   const transcriptionAttributes = Convert.toTranscriptionAttributes(json);
+
+export interface AgentAttributes {
+  'lk.agent.inputs'?: AgentInput[];
+  'lk.agent.outputs'?: AgentOutput[];
+  'lk.agent.state'?: AgentState;
+  'lk.publish_on_behalf'?: string;
+  [property: string]: any;
+}
+
+export type AgentInput = 'audio' | 'video' | 'text';
+
+export type AgentOutput = 'transcription' | 'audio';
+
+export type AgentState = 'idle' | 'initializing' | 'listening' | 'thinking' | 'speaking';
+
+/**
+ * Schema for transcription-related attributes
+ */
+export interface TranscriptionAttributes {
+  /**
+   * The segment id of the transcription
+   */
+  'lk.segment_id'?: string;
+  /**
+   * The associated track id of the transcription
+   */
+  'lk.transcribed_track_id'?: string;
+  /**
+   * Whether the transcription is final
+   */
+  'lk.transcription_final'?: boolean;
+  [property: string]: any;
+}
+
+// Converts JSON strings to/from your types
+export class Convert {
+  public static toAgentAttributes(json: string): AgentAttributes {
+    return JSON.parse(json);
+  }
+
+  public static agentAttributesToJson(value: AgentAttributes): string {
+    return JSON.stringify(value);
+  }
+
+  public static toTranscriptionAttributes(json: string): TranscriptionAttributes {
+    return JSON.parse(json);
+  }
+
+  public static transcriptionAttributesToJson(value: TranscriptionAttributes): string {
+    return JSON.stringify(value);
+  }
+}

src/utils/cloneDeep.ts

@@ -4,6 +4,10 @@ export function cloneDeep<T>(value: T): T {
   }
 
   if (typeof structuredClone === 'function') {
+    if (typeof value === 'object' && value !== null) {
+      // ensure that the value is not a proxy by spreading it
+      return structuredClone({ ...value });
+    }
     return structuredClone(value);
   } else {
     return JSON.parse(JSON.stringify(value)) as T;