feat: add telemetry and license key support to SuperDocESign component [esign]

apps/docs/solutions/esign/api-reference.mdx

@@ -140,6 +140,23 @@ Complete eSign component API
   ```
 </ParamField>
 
+<ParamField path="telemetry" type="object">
+  Telemetry configuration. Enabled by default with `source: 'esign'` metadata. See [Telemetry](/resources/telemetry) for details.
+
+  <Expandable title="properties">
+    <ParamField path="enabled" type="boolean" default="true">
+      Enable or disable telemetry
+    </ParamField>
+    <ParamField path="metadata" type="Record<string, any>">
+      Custom metadata merged with the default `{ source: 'esign' }`
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField path="licenseKey" type="string">
+  License key for SuperDoc. Passed directly to the underlying SuperDoc instance.
+</ParamField>
+
 <ParamField path="isDisabled" type="boolean">
   Disable all interactions
 </ParamField>

apps/docs/solutions/esign/configuration.mdx

@@ -346,6 +346,35 @@ Style the component to match your brand.
 />
 ```
 
+## Telemetry
+
+Telemetry is enabled by default with `source: 'esign'` metadata. You can override or extend the defaults:
+
+```jsx
+<SuperDocESign
+  telemetry={{ enabled: true, metadata: { source: "my-app", environment: "production" } }}
+  // ... other props
+/>
+```
+
+To disable telemetry:
+
+```jsx
+<SuperDocESign telemetry={{ enabled: false }} />
+```
+
+For more details on how telemetry works, see the [Telemetry](/resources/telemetry) page.
+
+## License key
+
+Pass your license key to activate commercial features:
+
+```jsx
+<SuperDocESign licenseKey="your-license-key" />
+```
+
+The key is forwarded to the underlying SuperDoc instance.
+
 ## Complete example
 
 ```jsx

packages/esign/demo/src/App.tsx

@@ -327,6 +327,7 @@ export function App() {
               <SuperDocESign
                 ref={esignRef}
                 eventId={eventId}
+                telemetry={{ enabled: true, metadata: { source: 'esign-demo' } }}
                 document={{
                   source: documentSource,
                   mode: 'full',

packages/esign/src/index.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState, useEffect, useCallback, forwardRef, useImperativeHandle } from 'react';
+import { useRef, useState, useEffect, useCallback, useMemo, forwardRef, useImperativeHandle } from 'react';
 import type { SuperDoc } from 'superdoc';
 import type * as Types from './types';
 import { textToImageDataUrl } from './utils/signature';
@@ -22,6 +22,8 @@
     onStateChange,
     onFieldChange,
     onFieldsDiscovered,
+    telemetry,
+    licenseKey,
     isDisabled = false,
     className,
     style,
@@ -57,7 +59,7 @@
 
     // Handle table fields
     if (field.type === 'table' && Array.isArray(field.value)) {
       const helpers = (editor.helpers as any)?.structuredContentCommands;
       const tables = helpers?.getStructuredContentTablesById?.(field.id, editor.state) || [];
 
       if (tables.length) {
@@ -86,7 +88,7 @@
         }
 
         // Append new rows after row 0 (copies style from row 0)
         (editor.commands as any)?.appendRowsToStructuredContentTable?.({
           id: field.id,
           rows: field.value,
           copyRowStyle: true,
@@ -138,7 +140,7 @@
       });
 
       const discovered: Types.FieldInfo[] = tags
         .map(({ node }: any) => ({
           id: node.attrs.id,
           label: node.attrs.label,
           value: configValues.get(node.attrs.id) ?? node.textContent ?? '',
@@ -178,7 +180,7 @@
       ...event,
       timestamp: new Date().toISOString(),
     };
     const auditMock = (globalThis as any)?.__SUPERDOC_AUDIT_MOCK__;
     if (auditMock) {
       auditMock(auditEvent);
     }
@@ -188,6 +190,14 @@
     return nextTrail;
   };
 
+  const stableTelemetry = useMemo(
+    () => ({
+      enabled: telemetry?.enabled ?? true,
+      metadata: { source: 'esign', ...telemetry?.metadata },
+    }),
+    [telemetry?.enabled, JSON.stringify(telemetry?.metadata)],
+  );
+
   // Initialize SuperDoc - uses abort pattern to handle React 18 Strict Mode
   // which intentionally double-invokes effects to help identify cleanup issues
   useEffect(() => {
@@ -212,6 +222,8 @@
         viewOptions: {
           layout: document.viewOptions?.layout ?? (document.layoutMode === 'responsive' ? 'web' : 'print'),
         },
+        telemetry: stableTelemetry,
+        ...(licenseKey && { licenseKey }),
         onReady: () => {
           // Guard callback execution if cleanup already ran
           if (aborted) return;
@@ -238,7 +250,15 @@
       superdocRef.current = null;
     };
     // Use primitives to avoid re-init on every render when object references change
-  }, [document.source, document.mode, document.layoutMode, document.viewOptions?.layout, discoverAndApplyFields]);
+  }, [
+    document.source,
+    document.mode,
+    document.layoutMode,
+    document.viewOptions?.layout,
+    discoverAndApplyFields,
+    stableTelemetry,
+    licenseKey,
+  ]);
 
   useEffect(() => {
     if (!document.validation?.scroll?.required || !isReady) return;

packages/esign/src/types.ts

@@ -112,6 +112,12 @@ export interface SuperDocESignProps {
   onFieldChange?: (field: FieldChange) => void;
   onFieldsDiscovered?: (fields: FieldInfo[]) => void;
 
+  /** Telemetry configuration for SuperDoc */
+  telemetry?: { enabled: boolean; metadata?: Record<string, any> };
+
+  /** License key for SuperDoc */
+  licenseKey?: string;
+
   isDisabled?: boolean;
   className?: string;
   style?: React.CSSProperties;