@gram-ai/elements 1.20.2 → 1.21.2

package/src/hooks/useSession.ts

@@ -8,11 +8,9 @@ import { useQuery, useQueryClient } from '@tanstack/react-query'
 export const useSession = ({
   getSession,
   projectSlug,
-  enabled,
 }: {
   getSession: GetSessionFn | null
   projectSlug: string
-  enabled: boolean
 }): string | null => {
   const queryClient = useQueryClient()
   const queryKey = ['chatSession', projectSlug]
@@ -29,7 +27,7 @@ export const useSession = ({
   const { data: fetchedSessionToken } = useQuery({
     queryKey,
     queryFn: () => getSession!({ projectSlug }),
-    enabled: enabled && shouldFetch && getSession !== null,
+    enabled: shouldFetch && getSession !== null,
     staleTime: Infinity, // Session tokens don't need to be refetched
     gcTime: Infinity, // Keep in cache indefinitely
   })

package/src/index.ts

@@ -15,6 +15,10 @@ export { ThreadList as ChatHistory } from '@/components/assistant-ui/thread-list
 export { defineFrontendTool } from './lib/tools'
 export type { FrontendTool } from './lib/tools'
 
+// Error Tracking
+export { trackError } from './lib/errorTracking'
+export type { ErrorContext } from './lib/errorTracking'
+
 // Types
 export type {
   AttachmentsConfig,
@@ -27,6 +31,7 @@ export type {
   Dimension,
   Dimensions,
   ElementsConfig,
+  ErrorTrackingConfigOption,
   GetSessionFn,
   HistoryConfig,
   ModalConfig,

package/src/lib/api.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
 import type { ElementsConfig } from '@/types'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 describe('getApiUrl', () => {
   beforeEach(() => {
@@ -16,7 +16,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('https://env.example.com')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { url: 'https://config.example.com', UNSAFE_apiKey: 'test-key' },
+      api: { url: 'https://config.example.com', sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://config.example.com')
@@ -26,7 +26,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('https://env.example.com')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { UNSAFE_apiKey: 'test-key' },
+      api: { sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://env.example.com')
@@ -63,7 +63,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('https://env.example.com')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { url: '', UNSAFE_apiKey: 'test-key' },
+      api: { url: '', sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://env.example.com')
@@ -73,7 +73,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { url: 'https://config.example.com///', UNSAFE_apiKey: 'test-key' },
+      api: { url: 'https://config.example.com///', sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://config.example.com')

package/src/lib/auth.ts

@@ -1,12 +1,12 @@
-import { ApiKeyAuthConfig, ApiConfig, SessionAuthConfig } from '@/types'
+import { ApiConfig, SessionAuthConfig, StaticSessionAuthConfig } from '@/types'
 
 /**
  * Checks if the auth config is an API key auth config
  */
-export function isApiKeyAuth(
+export function isStaticSessionAuth(
   auth: ApiConfig | undefined
-): auth is ApiKeyAuthConfig {
-  return !!auth && 'UNSAFE_apiKey' in auth
+): auth is StaticSessionAuthConfig {
+  return !!auth && 'sessionToken' in auth
 }
 
 export function hasExplicitSessionAuth(

package/src/lib/errorTracking.config.ts

@@ -0,0 +1,16 @@
+/**
+ * Datadog RUM configuration for Gram Elements.
+ * Values are injected at build time via environment variables.
+ * These client tokens are designed to be client-side safe.
+ *
+ * Required env vars for build:
+ * - VITE_DATADOG_APPLICATION_ID
+ * - VITE_DATADOG_CLIENT_TOKEN
+ * - VITE_DATADOG_SITE (optional, defaults to datadoghq.com)
+ */
+export const DATADOG_CONFIG = {
+  applicationId: import.meta.env.VITE_DATADOG_APPLICATION_ID ?? '',
+  clientToken: import.meta.env.VITE_DATADOG_CLIENT_TOKEN ?? '',
+  site: import.meta.env.VITE_DATADOG_SITE ?? 'datadoghq.com',
+  service: 'gram-elements',
+} as const

package/src/lib/errorTracking.ts

@@ -0,0 +1,104 @@
+import { datadogRum } from '@datadog/browser-rum'
+import { DATADOG_CONFIG } from './errorTracking.config'
+
+let initialized = false
+let enabled = true
+
+export interface ErrorTrackingConfig {
+  enabled?: boolean
+  projectSlug?: string
+  variant?: string
+}
+
+export interface ErrorContext {
+  source: 'error-boundary' | 'streaming' | 'stream-creation' | 'custom'
+  componentStack?: string
+  [key: string]: unknown
+}
+
+/**
+ * Initialize Datadog RUM for error tracking.
+ * Should be called once when the ElementsProvider mounts.
+ */
+export function initErrorTracking(config: ErrorTrackingConfig = {}): void {
+  // Check if explicitly disabled
+  if (config.enabled === false) {
+    enabled = false
+    return
+  }
+
+  // Prevent double initialization
+  if (initialized) {
+    return
+  }
+
+  // Skip if credentials not configured (e.g., local dev without env vars)
+  if (!DATADOG_CONFIG.applicationId || !DATADOG_CONFIG.clientToken) {
+    enabled = false
+    return
+  }
+
+  try {
+    datadogRum.init({
+      applicationId: DATADOG_CONFIG.applicationId,
+      clientToken: DATADOG_CONFIG.clientToken,
+      site: DATADOG_CONFIG.site,
+      service: DATADOG_CONFIG.service,
+      env: process.env.NODE_ENV || 'production',
+      sessionSampleRate: 100,
+      sessionReplaySampleRate: 100,
+      trackUserInteractions: true,
+      trackResources: true,
+      trackLongTasks: true,
+
+      // Note: we need to mask everything, not just user input, as sensitive data may be echo-ed
+      // back in the LLM messages or the user messages in the chat window
+      defaultPrivacyLevel: 'mask',
+    })
+
+    // Set global context
+    if (config.projectSlug) {
+      datadogRum.setGlobalContextProperty('projectSlug', config.projectSlug)
+    }
+    if (config.variant) {
+      datadogRum.setGlobalContextProperty('variant', config.variant)
+    }
+
+    initialized = true
+  } catch (error) {
+    console.warn('[Elements] Failed to initialize Datadog RUM:', error)
+    enabled = false
+  }
+}
+
+/**
+ * Track an error to Datadog RUM.
+ * Includes context about where the error originated.
+ */
+export function trackError(
+  error: Error | unknown,
+  context: ErrorContext
+): void {
+  if (!enabled || !initialized) {
+    return
+  }
+
+  const errorObj = error instanceof Error ? error : new Error(String(error))
+
+  try {
+    datadogRum.addError(errorObj, {
+      ...context,
+      timestamp: new Date().toISOString(),
+    })
+  } catch (e) {
+    // Silently fail - we don't want error tracking to cause more errors
+    console.warn('[Elements] Failed to track error:', e)
+  }
+}
+
+/**
+ * Check if error tracking is currently enabled.
+ */
+export function isErrorTrackingEnabled(): boolean {
+  return enabled && initialized
+}

package/src/lib/tools.ts

@@ -6,6 +6,7 @@ import {
 } from '@assistant-ui/react'
 import z from 'zod'
 import { FC } from 'react'
+import type { ToolsRequiringApproval } from '@/types'
 
 /**
  * Converts from assistant-ui tool format to the AI SDK tool shape
@@ -50,7 +51,7 @@ export type FrontendTool<TArgs extends Record<string, unknown>, TResult> = FC<
  */
 let approvalConfig: {
   helpers: ApprovalHelpers
-  toolsRequiringApproval: Set<string>
+  requiresApproval: (toolName: string) => boolean
 } | null = null
 
 /**
@@ -58,11 +59,12 @@ let approvalConfig: {
  */
 export function setFrontendToolApprovalConfig(
   helpers: ApprovalHelpers,
-  toolsRequiringApproval: string[]
+  toolsRequiringApproval: ToolsRequiringApproval
 ): void {
+  const requiresApproval = createRequiresApprovalFn(toolsRequiringApproval)
   approvalConfig = {
     helpers,
-    toolsRequiringApproval: new Set(toolsRequiringApproval),
+    requiresApproval,
   }
 }
 
@@ -73,6 +75,25 @@ export function clearFrontendToolApprovalConfig(): void {
   approvalConfig = null
 }
 
+/**
+ * Creates a function that checks if a tool requires approval.
+ * Handles both array and function-based configurations.
+ */
+function createRequiresApprovalFn(
+  toolsRequiringApproval: ToolsRequiringApproval | undefined
+): (toolName: string) => boolean {
+  if (!toolsRequiringApproval) {
+    return () => false
+  }
+
+  if (typeof toolsRequiringApproval === 'function') {
+    return (toolName: string) => toolsRequiringApproval({ toolName })
+  }
+
+  const approvalSet = new Set(toolsRequiringApproval)
+  return (toolName: string) => approvalSet.has(toolName)
+}
+
 /**
  * Make a frontend tool
  */
@@ -90,7 +111,7 @@ export const defineFrontendTool = <
     ...tool,
     execute: async (args: TArgs, context: ToolExecutionContext) => {
       // Check if this tool requires approval at runtime
-      if (approvalConfig?.toolsRequiringApproval.has(name)) {
+      if (approvalConfig?.requiresApproval(name)) {
         const { helpers } = approvalConfig
         const toolCallId = context.toolCallId ?? ''
 
@@ -136,18 +157,26 @@ export interface ApprovalHelpers {
  */
 export function wrapToolsWithApproval(
   tools: ToolSet,
-  toolsRequiringApproval: string[] | undefined,
+  toolsRequiringApproval: ToolsRequiringApproval | undefined,
   approvalHelpers: ApprovalHelpers
 ): ToolSet {
-  if (!toolsRequiringApproval || toolsRequiringApproval.length === 0) {
+  if (!toolsRequiringApproval) {
     return tools
   }
 
-  const approvalSet = new Set(toolsRequiringApproval)
+  // Handle empty array case
+  if (
+    Array.isArray(toolsRequiringApproval) &&
+    toolsRequiringApproval.length === 0
+  ) {
+    return tools
+  }
+
+  const requiresApproval = createRequiresApprovalFn(toolsRequiringApproval)
 
   return Object.fromEntries(
     Object.entries(tools).map(([name, tool]) => {
-      if (!approvalSet.has(name)) {
+      if (!requiresApproval(name)) {
         return [name, tool]
       }
 

package/src/types/index.ts

@@ -288,6 +288,30 @@ export interface ElementsConfig {
    * }
    */
   api?: ApiConfig
+
+  /**
+   * Error tracking configuration.
+   * By default, errors are reported to help improve the Elements library.
+   *
+   * @example
+   * const config: ElementsConfig = {
+   *   errorTracking: {
+   *     enabled: false, // Opt out of error reporting
+   *   },
+   * }
+   */
+  errorTracking?: ErrorTrackingConfigOption
+}
+
+/**
+ * Configuration for error tracking.
+ */
+export interface ErrorTrackingConfigOption {
+  /**
+   * Set to false to disable error reporting.
+   * @default true
+   */
+  enabled?: boolean
 }
 
 /**
@@ -325,32 +349,27 @@ export type SessionAuthConfig = {
 }
 
 /**
- * The API key auth config is used to authenticate the Elements library using an API key only.
- *
- * NOTE: This is not recommended for production use, and a warning
- * will be displayed in the chat interface if you use this config.
- * Define a session endpoint instead to avoid this warning.
+ * The static session auth config is used to authenticate the Elements library using a static session token only.
  *
  * @example
  * const config: ElementsConfig = {
  *   api: {
- *     UNSAFE_apiKey: 'your-api-key',
+ *     sessionToken: 'your-session-token',
  *   },
  * }
  */
-export type ApiKeyAuthConfig = {
+export type StaticSessionAuthConfig = {
   /**
-   * The API key to use if you haven't yet configured a session endpoint.
-   * Do not use this in production.
+   * A static session token to use if you haven't yet configured a session endpoint.
    *
    * @example
    * const config: ElementsConfig = {
    *   api: {
-   *     UNSAFE_apiKey: 'your-api-key',
+   *     sessionToken: 'your-session-token',
    *   },
    * }
    */
-  UNSAFE_apiKey: string
+  sessionToken: string
 }
 
 /**
@@ -359,7 +378,7 @@ export type ApiKeyAuthConfig = {
 export type ApiConfig =
   | BaseApiConfig
   | (BaseApiConfig & SessionAuthConfig)
-  | (BaseApiConfig & ApiKeyAuthConfig)
+  | (BaseApiConfig & StaticSessionAuthConfig)
 
 /**
  * The LLM model to use for the Elements library.
@@ -490,6 +509,10 @@ export interface ComponentOverrides {
   >
 }
 
+export type ToolsRequiringApproval =
+  | string[]
+  | (({ toolName }: { toolName: string }) => boolean)
+
 /**
  * ToolsConfig is used to configure tool support in the Elements library.
  * At the moment, you can override the default React components used by
@@ -504,7 +527,6 @@ export interface ComponentOverrides {
  *   },
  * }
  */
-
 export interface ToolsConfig {
   /**
    * Whether individual tool calls within a group should be expanded by default.
@@ -584,17 +606,27 @@ export interface ToolsConfig {
 
   /**
    * List of tool names that require confirmation from the end user before
-   * being executed. The user can choose to approve once or approve for the
+   * being executed. A function can also be provided to dynamically determine if a tool requires approval.
+   * The user can choose to approve once or approve for the
    * entire session via the UI.
    *
-   * @example
+   * @example Using an array of tool names
    * ```ts
    * tools: {
    *   toolsRequiringApproval: ['delete_file', 'send_email'],
    * }
    * ```
+   *
+   * @example Using a function to dynamically determine if a tool requires approval
+   * ```ts
+   * tools: {
+   *   toolsRequiringApproval: (toolName) => {
+   *     return toolName.startsWith('protected_')
+   *   },
+   * }
+   * ```
    */
-  toolsRequiringApproval?: string[]
+  toolsRequiringApproval?: ToolsRequiringApproval
 }
 
 export interface WelcomeConfig {

package/src/vite-env.d.ts

@@ -5,6 +5,9 @@ declare const __GRAM_GIT_SHA__: string | undefined
 interface ImportMetaEnv {
   readonly VITE_GRAM_ELEMENTS_STORYBOOK_PROJECT_SLUG?: string | undefined
   readonly VITE_GRAM_ELEMENTS_STORYBOOK_MCP_URL?: string | undefined
+  readonly VITE_DATADOG_APPLICATION_ID?: string | undefined
+  readonly VITE_DATADOG_CLIENT_TOKEN?: string | undefined
+  readonly VITE_DATADOG_SITE?: string | undefined
 }
 
 interface ImportMeta {

package/dist/components/Chat/stories/ColorScheme.stories.d.ts

@@ -1,8 +0,0 @@
-import { Chat } from '..';
-import { Meta, StoryFn } from '@storybook/react-vite';
-declare const meta: Meta<typeof Chat>;
-export default meta;
-type Story = StoryFn<typeof Chat>;
-export declare const Light: Story;
-export declare const Dark: Story;
-export declare const System: Story;

package/src/components/Chat/stories/ColorScheme.stories.tsx

@@ -1,52 +0,0 @@
-import React from 'react'
-import { Chat } from '..'
-import type { Meta, StoryFn } from '@storybook/react-vite'
-
-const meta: Meta<typeof Chat> = {
-  title: 'Chat/Color Scheme',
-  component: Chat,
-  parameters: {
-    layout: 'fullscreen',
-  },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
-} satisfies Meta<typeof Chat>
-
-export default meta
-
-type Story = StoryFn<typeof Chat>
-
-export const Light: Story = () => <Chat />
-Light.parameters = {
-  elements: {
-    config: {
-      variant: 'standalone',
-      theme: { colorScheme: 'light' },
-    },
-  },
-}
-
-export const Dark: Story = () => <Chat />
-Dark.parameters = {
-  elements: {
-    config: {
-      variant: 'standalone',
-      theme: { colorScheme: 'dark' },
-    },
-  },
-}
-
-export const System: Story = () => <Chat />
-System.parameters = {
-  elements: {
-    config: {
-      variant: 'standalone',
-      theme: { colorScheme: 'system' },
-    },
-  },
-}