Add internal attributes definition helper

.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 attributesHelper from './room/attributes';
 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 */
+  attributesHelper,
   ConnectionQuality,
   ConnectionState,
   CriticalTimers,

src/room/attributes/agent_attr.ts

@@ -0,0 +1,73 @@
+// This file is auto-generated. Do not edit manually.
+
+const AgentStateAttribute = {
+  key: "lk.agent.state",
+  values: ["initializing", "idle", "listening", "thinking", "speaking"],
+  default: "idle",
+} as const;
+
+const PublishOnBehalfAttribute = {
+  key: "lk.publish_on_behalf",
+  values: [], // Any string value allowed
+  default: null,
+} as const;
+
+export const AgentAttributesRegistry = [
+  AgentStateAttribute,
+  PublishOnBehalfAttribute,
+] as const;
+
+/**
+ * Agent connection state
+ */
+export type AgentStateType = (typeof AgentStateAttribute.values)[number];
+/**
+ * The identity of the user that the agent is publishing on behalf of
+ */
+export type PublishOnBehalfType = string;
+
+export interface AgentAttributes {
+  /**
+   * Agent connection state
+   */
+  [AgentStateAttribute.key]?: AgentStateType;
+  /**
+   * The identity of the user that the agent is publishing on behalf of
+   */
+  [PublishOnBehalfAttribute.key]?: PublishOnBehalfType;
+}
+
+/**
+ * Parse a raw attribute map into a typed AgentAttributesRegistry
+ * @param attributes Raw attribute map (key-value pairs)
+ * @returns Typed AgentAttributes
+ */
+export function parseAgentAttributes(
+  attributes: Record<string, string>
+): AgentAttributes {
+  const result: AgentAttributes = {};
+
+  // First add default values from registry
+  for (const attribute of AgentAttributesRegistry) {
+    if (attribute.default !== null) {
+      result[attribute.key] = attribute.default as any;
+    }
+  }
+
+  // Then override with provided values
+  for (const [key, value] of Object.entries(attributes)) {
+    for (const attribute of AgentAttributesRegistry) {
+      if (key === attribute.key) {
+        // For attributes with allowed values (non-empty array), validate the value
+        if (attribute.values.length > 0 && !(attribute.values as readonly string[]).includes(value)) {
+          // Skip invalid values
+          continue;
+        }
+        result[key] = value as any;
+        break;
+      }
+    }
+  }
+
+  return result;
+}

src/room/attributes/index.ts

@@ -0,0 +1,4 @@
+import * as agent from './agent_attr';
+import * as transcription from './transcription_attr';
+
+export { agent, transcription };

src/room/attributes/transcription_attr.ts

@@ -0,0 +1,88 @@
+// This file is auto-generated. Do not edit manually.
+
+const SegmentIdAttribute = {
+  key: "lk.segment_id",
+  values: [], // Any string value allowed
+  default: null,
+} as const;
+
+const TranscribedTrackIdAttribute = {
+  key: "lk.transcribed_track_id",
+  values: [], // Any string value allowed
+  default: null,
+} as const;
+
+const TranscriptionFinalAttribute = {
+  key: "lk.transcription_final",
+  values: ["true", "false"],
+  default: null,
+} as const;
+
+export const TranscriptionAttributesRegistry = [
+  SegmentIdAttribute,
+  TranscribedTrackIdAttribute,
+  TranscriptionFinalAttribute,
+] as const;
+
+/**
+ * The segment id of the transcription
+ */
+export type SegmentIdType = string;
+/**
+ * The associated track id of the transcription
+ */
+export type TranscribedTrackIdType = string;
+/**
+ * Whether the transcription is final
+ */
+export type TranscriptionFinalType = (typeof TranscriptionFinalAttribute.values)[number];
+
+export interface TranscriptionAttributes {
+  /**
+   * The segment id of the transcription
+   */
+  [SegmentIdAttribute.key]?: SegmentIdType;
+  /**
+   * The associated track id of the transcription
+   */
+  [TranscribedTrackIdAttribute.key]?: TranscribedTrackIdType;
+  /**
+   * Whether the transcription is final
+   */
+  [TranscriptionFinalAttribute.key]?: TranscriptionFinalType;
+}
+
+/**
+ * Parse a raw attribute map into a typed TranscriptionAttributesRegistry
+ * @param attributes Raw attribute map (key-value pairs)
+ * @returns Typed TranscriptionAttributes
+ */
+export function parseTranscriptionAttributes(
+  attributes: Record<string, string>
+): TranscriptionAttributes {
+  const result: TranscriptionAttributes = {};
+
+  // First add default values from registry
+  for (const attribute of TranscriptionAttributesRegistry) {
+    if (attribute.default !== null) {
+      result[attribute.key] = attribute.default as any;
+    }
+  }
+
+  // Then override with provided values
+  for (const [key, value] of Object.entries(attributes)) {
+    for (const attribute of TranscriptionAttributesRegistry) {
+      if (key === attribute.key) {
+        // For attributes with allowed values (non-empty array), validate the value
+        if (attribute.values.length > 0 && !(attribute.values as readonly string[]).includes(value)) {
+          // Skip invalid values
+          continue;
+        }
+        result[key] = value as any;
+        break;
+      }
+    }
+  }
+
+  return result;
+}

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;