@gram-ai/elements 1.26.0 → 1.27.0

package/src/components/ui/tool-ui.tsx

@@ -47,6 +47,20 @@ type ContentItem =
   | { type: 'text'; text: string; _meta?: { 'getgram.ai/mime-type'?: string } }
   | { type: 'image'; data: string; _meta?: { 'getgram.ai/mime-type'?: string } }
 
+/** MCP tool annotations providing hints about tool behavior */
+interface ToolAnnotations {
+  /** Human-readable display name for the tool */
+  title?: string
+  /** If true, the tool does not modify its environment */
+  readOnlyHint?: boolean
+  /** If true, the tool may perform destructive updates */
+  destructiveHint?: boolean
+  /** If true, repeated calls with same args have no additional effect */
+  idempotentHint?: boolean
+  /** If true, tool interacts with external entities */
+  openWorldHint?: boolean
+}
+
 interface ToolUIProps {
   /** Display name of the tool */
   name: string
@@ -64,6 +78,8 @@ interface ToolUIProps {
   defaultExpanded?: boolean
   /** Additional class names */
   className?: string
+  /** MCP tool annotations */
+  annotations?: ToolAnnotations
   /** Approval callbacks */
   onApproveOnce?: () => void
   onApproveForSession?: () => void
@@ -410,10 +426,13 @@ function ToolUI({
   result,
   defaultExpanded = false,
   className,
+  annotations,
   onApproveOnce,
   onApproveForSession,
   onDeny,
 }: ToolUIProps) {
+  // Use annotation title if available, otherwise fall back to name
+  const displayName = annotations?.title || name
   const isApprovalPending =
     status === 'approval' && onApproveOnce !== undefined && onDeny !== undefined
   // Auto-expand when approval is pending, collapse when approved
@@ -486,7 +505,7 @@ function ToolUI({
             !provider && isApprovalPending && 'shimmer'
           )}
         >
-          {name}
+          {displayName}
         </span>
         {hasContent && (
           <ChevronDownIcon
@@ -528,10 +547,20 @@ function ToolUI({
           data-slot="tool-ui-approval-actions"
           className="border-border flex flex-col gap-2 border-t px-4 py-3 @[320px]:flex-row @[320px]:items-center @[320px]:justify-end"
         >
-          <div className="@[320px]:mr-auto">
+          <div className="flex items-center gap-2 @[320px]:mr-auto">
             <span className="text-muted-foreground text-sm">
               This tool requires approval
             </span>
+            {annotations?.readOnlyHint && (
+              <span className="bg-muted text-muted-foreground rounded px-1.5 py-0.5 text-xs">
+                Read-only
+              </span>
+            )}
+            {annotations?.destructiveHint && !annotations?.readOnlyHint && (
+              <span className="rounded bg-amber-500/10 px-1.5 py-0.5 text-xs text-amber-600 dark:text-amber-400">
+                Destructive
+              </span>
+            )}
           </div>
           <div className="flex items-center gap-2 self-end">
             <Button

package/src/hooks/useAuth.ts

@@ -1,9 +1,17 @@
 import { useReplayContext } from '@/contexts/ReplayContext'
-import { hasExplicitSessionAuth, isStaticSessionAuth } from '@/lib/auth'
+import {
+  hasExplicitSessionAuth,
+  isDangerousApiKeyAuth,
+  isStaticSessionAuth,
+  isUnifiedFunctionSession,
+  isUnifiedStaticSession,
+} from '@/lib/auth'
 import { useMemo } from 'react'
-import { ApiConfig } from '../types'
+import { ApiConfig, GetSessionFn } from '../types'
 import { useSession } from './useSession'
 
+declare const __GRAM_API_URL__: string | undefined
+
 export type Auth =
   | {
       headers: Record<string, string>
@@ -30,6 +38,28 @@ async function defaultGetSession(init: {
   return data.client_token
 }
 
+function createDangerousApiKeySessionFn(
+  apiKey: string,
+  apiUrl: string
+): GetSessionFn {
+  return async ({ projectSlug }) => {
+    const response = await fetch(`${apiUrl}/rpc/chatSessions.create`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Gram-Key': apiKey,
+        'Gram-Project': projectSlug,
+      },
+      body: JSON.stringify({
+        embed_origin: window.location.origin,
+        user_identifier: 'elements-dev',
+      }),
+    })
+    const data = await response.json()
+    return data.client_token
+  }
+}
+
 /**
  * Hook to fetch or retrieve the session token for the chat.
  * @returns The session token string or null
@@ -44,20 +74,42 @@ export const useAuth = ({
   const replayCtx = useReplayContext()
   const isReplay = replayCtx?.isReplay ?? false
 
+  const apiUrl = useMemo(() => {
+    const envUrl =
+      typeof __GRAM_API_URL__ !== 'undefined' ? __GRAM_API_URL__ : undefined
+    const url = auth?.url || envUrl || 'https://app.getgram.ai'
+    return url.replace(/\/+$/, '')
+  }, [auth?.url])
+
   const getSession = useMemo(() => {
     // In replay mode, skip session fetching entirely
     if (isReplay) {
       return null
     }
+    // dangerousApiKey — exchange key for session via API
+    if (isDangerousApiKeyAuth(auth)) {
+      return createDangerousApiKeySessionFn(auth.dangerousApiKey, apiUrl)
+    }
+    // Unified session: static string
+    if (isUnifiedStaticSession(auth)) {
+      return () => Promise.resolve(auth.session)
+    }
+    // Unified session: function
+    if (isUnifiedFunctionSession(auth)) {
+      return auth.session
+    }
+    // Legacy: static sessionToken (deprecated)
     if (isStaticSessionAuth(auth)) {
       return () => Promise.resolve(auth.sessionToken)
     }
-    return !isStaticSessionAuth(auth) && hasExplicitSessionAuth(auth)
-      ? auth.sessionFn
-      : defaultGetSession
-  }, [auth, isReplay])
+    // Legacy: explicit sessionFn (deprecated)
+    if (hasExplicitSessionAuth(auth)) {
+      return auth.sessionFn
+    }
+    return defaultGetSession
+  }, [auth, isReplay, apiUrl])
 
-  // The session request is only neccessary if we are not using static session auth
+  // The session request is only necessary if we are not using static session auth
   // configuration. If a custom session fetcher is provided, we use it,
   // otherwise we fallback to the default session fetcher
   const session = useSession({

package/src/hooks/useFollowOnSuggestions.ts

@@ -1,12 +1,12 @@
 import { useReplayContext } from '@/contexts/ReplayContext'
-import { useAssistantState } from '@assistant-ui/react'
-import { useCallback, useEffect, useRef, useState } from 'react'
-import { useElements } from './useElements'
 import { getApiUrl } from '@/lib/api'
-import { useAuth } from './useAuth'
-import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+import { useAssistantState } from '@assistant-ui/react'
 import { generateObject } from 'ai'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import { z } from 'zod'
+import { useAuth } from './useAuth'
+import { useElements } from './useElements'
+import { useModel } from './useModel'
 
 export interface FollowOnSuggestion {
   id: string
@@ -46,6 +46,8 @@ export function useFollowOnSuggestions(): {
     projectSlug: config.projectSlug,
   })
 
+  const model = useModel(SUGGESTIONS_MODEL)
+
   // Check if follow-up suggestions are enabled (default: true)
   // Disable in replay mode since we don't need AI-generated suggestions
   const isEnabled = !isReplay && config.thread?.followUpSuggestions !== false
@@ -104,15 +106,6 @@ export function useFollowOnSuggestions(): {
     setIsLoading(true)
 
     try {
-      // Create OpenRouter client
-      const openRouter = createOpenRouter({
-        baseURL: apiUrl,
-        apiKey: 'unused, but must be set',
-        headers: auth.headers,
-      })
-
-      const model = openRouter.chat(SUGGESTIONS_MODEL)
-
       // Check if the assistant is asking a question
       if (lastAssistantMessage) {
         try {

package/src/hooks/useModel.ts

@@ -0,0 +1,30 @@
+import { getApiUrl } from '@/lib/api'
+import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+import { LanguageModel } from 'ai'
+import { useAuth } from './useAuth'
+import { useElements } from './useElements'
+
+// Creates an OpenRouter client to be used for "internal Gram" usage, such as follow-on suggestions
+export const useModel = (
+  model: string = 'openai/gpt-4o-mini'
+): LanguageModel => {
+  const { config } = useElements()
+
+  const auth = useAuth({
+    auth: config.api,
+    projectSlug: config.projectSlug,
+  })
+
+  const apiUrl = getApiUrl(config)
+
+  const openRouter = createOpenRouter({
+    baseURL: apiUrl,
+    apiKey: 'unused, but must be set',
+    headers: {
+      ...auth.headers,
+      'X-Gram-Source': 'gram',
+    },
+  })
+
+  return openRouter.chat(model)
+}

package/src/index.ts

@@ -43,6 +43,7 @@ export type {
   ColorScheme,
   ComponentOverrides,
   ComposerConfig,
+  DangerousApiKeyAuthConfig,
   DENSITIES,
   Density,
   Dimension,
@@ -62,6 +63,7 @@ export type {
   ThemeConfig,
   ToolMentionsConfig,
   ToolsConfig,
+  UnifiedSessionAuthConfig,
   Variant,
   VARIANTS,
   WelcomeConfig,
@@ -70,3 +72,18 @@ export type {
 export { MODELS } from './lib/models'
 
 export type { Plugin } from './types/plugins'
+
+// Time Range Picker
+export {
+  TimeRangePicker,
+  getPresetRange,
+  PRESETS,
+} from '@/components/ui/time-range-picker'
+export type {
+  TimeRange,
+  TimeRangePreset,
+  TimeRangePickerProps,
+  DateRangePreset,
+} from '@/components/ui/time-range-picker'
+export { Calendar } from '@/components/ui/calendar'
+export type { CalendarProps } from '@/components/ui/calendar'

package/src/lib/api.test.ts

@@ -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', sessionToken: 'test-key' },
+      api: { url: 'https://config.example.com', session: '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: { sessionToken: 'test-key' },
+      api: { session: '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: '', sessionToken: 'test-key' },
+      api: { url: '', session: '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///', sessionToken: 'test-key' },
+      api: { url: 'https://config.example.com///', session: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://config.example.com')

package/src/lib/auth.ts

@@ -1,17 +1,47 @@
-import { ApiConfig, SessionAuthConfig, StaticSessionAuthConfig } from '@/types'
+import {
+  ApiConfig,
+  BaseApiConfig,
+  DangerousApiKeyAuthConfig,
+  GetSessionFn,
+  SessionAuthConfig,
+  StaticSessionAuthConfig,
+  UnifiedSessionAuthConfig,
+} from '@/types'
 
-/**
- * Checks if the auth config is an API key auth config
- */
+export function isDangerousApiKeyAuth(
+  auth: ApiConfig | undefined
+): auth is DangerousApiKeyAuthConfig {
+  return !!auth && 'dangerousApiKey' in auth
+}
+
+export function isUnifiedStaticSession(
+  auth: ApiConfig | undefined
+): auth is UnifiedSessionAuthConfig & { session: string } {
+  return !!auth && 'session' in auth && typeof auth.session === 'string'
+}
+
+export function isUnifiedFunctionSession(
+  auth: ApiConfig | undefined
+): auth is BaseApiConfig & { session: GetSessionFn } {
+  return !!auth && 'session' in auth && typeof auth.session === 'function'
+}
+
+/** @deprecated Legacy check for `{ sessionToken }` configs. */
 export function isStaticSessionAuth(
   auth: ApiConfig | undefined
 ): auth is StaticSessionAuthConfig {
   return !!auth && 'sessionToken' in auth
 }
 
+/** @deprecated Legacy check for `{ sessionFn }` configs. */
 export function hasExplicitSessionAuth(
   auth: ApiConfig | undefined
 ): auth is SessionAuthConfig {
   if (!auth) return false
   return 'sessionFn' in auth
 }
+
+/** Returns true when either the legacy `sessionToken` or the unified static `session` string is used. */
+export function isAnyStaticSession(auth: ApiConfig | undefined): boolean {
+  return isStaticSessionAuth(auth) || isUnifiedStaticSession(auth)
+}

package/src/lib/models.ts

@@ -1,6 +1,7 @@
 // List of openrouter models available to the user
 // This list should be updated to match the model whitelist on the backend side.
 export const MODELS = [
+  'anthropic/claude-opus-4.6',
   'anthropic/claude-sonnet-4.5',
   'anthropic/claude-haiku-4.5',
   'anthropic/claude-sonnet-4',

package/src/server/bun.ts

@@ -0,0 +1,63 @@
+/**
+ * Bun adapter for Gram Elements server handlers.
+ *
+ * @example
+ * ```typescript
+ * import { createBunHandler } from '@gram-ai/elements/server/bun'
+ *
+ * const handler = createBunHandler({
+ *   embedOrigin: 'http://localhost:3000',
+ *   userIdentifier: 'user-123',
+ *   expiresAfter: 3600,
+ * })
+ *
+ * Bun.serve({
+ *   routes: {
+ *     '/chat/session': { POST: handler },
+ *   },
+ * })
+ * ```
+ */
+
+import { createChatSession, type SessionHandlerOptions } from './core'
+
+/**
+ * Create a Bun route handler for the chat session endpoint.
+ *
+ * @param options - Session configuration options
+ * @returns Bun route handler
+ */
+export function createBunHandler(
+  options:
+    | SessionHandlerOptions
+    | ((
+        request: Request
+      ) => SessionHandlerOptions | Promise<SessionHandlerOptions>)
+) {
+  return async (request: Request) => {
+    const projectSlug = request.headers.get('gram-project')
+
+    if (!projectSlug) {
+      return new Response(
+        JSON.stringify({ error: 'Missing Gram-Project header' }),
+        {
+          status: 400,
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+    }
+
+    const sessionOptions =
+      typeof options === 'function' ? await options(request) : options
+
+    const result = await createChatSession({
+      projectSlug,
+      options: sessionOptions,
+    })
+
+    return new Response(result.body, {
+      status: result.status,
+      headers: result.headers,
+    })
+  }
+}

package/src/server/core.ts

@@ -0,0 +1,84 @@
+/**
+ * Core session handler logic shared across all server adapters.
+ * This module contains the framework-agnostic business logic for creating chat sessions.
+ */
+
+export interface SessionHandlerOptions {
+  /**
+   * The origin from which the token will be used
+   */
+  embedOrigin: string
+
+  /**
+   * Free-form user identifier
+   */
+  userIdentifier: string
+
+  /**
+   * Token expiration in seconds (max / default 3600)
+   * @default 3600
+   */
+  expiresAfter?: number
+
+  /**
+   * Gram API key. If not provided, falls back to the `GRAM_API_KEY` environment variable.
+   */
+  apiKey?: string
+}
+
+export interface CreateSessionRequest {
+  projectSlug: string
+  options: SessionHandlerOptions
+}
+
+export interface CreateSessionResponse {
+  status: number
+  body: string
+  headers: Record<string, string>
+}
+
+/**
+ * Core function to create a chat session by calling Gram's API.
+ * This is framework-agnostic and can be used by any adapter.
+ */
+export async function createChatSession(
+  request: CreateSessionRequest
+): Promise<CreateSessionResponse> {
+  const base = process.env.GRAM_API_URL ?? 'https://app.getgram.ai'
+
+  try {
+    const response = await fetch(base + '/rpc/chatSessions.create', {
+      method: 'POST',
+      body: JSON.stringify({
+        embed_origin: request.options.embedOrigin,
+        user_identifier: request.options.userIdentifier,
+        expires_after: request.options.expiresAfter,
+      }),
+      headers: {
+        'Content-Type': 'application/json',
+        'Gram-Project': request.projectSlug,
+        'Gram-Key': request.options.apiKey ?? process.env.GRAM_API_KEY ?? '',
+      },
+    })
+
+    const body = await response.text()
+
+    return {
+      status: response.status,
+      body,
+      headers: { 'Content-Type': 'application/json' },
+    }
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error'
+    console.error('Failed to create chat session:', error)
+
+    return {
+      status: 500,
+      body: JSON.stringify({
+        error: 'Failed to create chat session: ' + errorMessage,
+      }),
+      headers: { 'Content-Type': 'application/json' },
+    }
+  }
+}

package/src/server/express.ts

@@ -0,0 +1,60 @@
+/**
+ * Express adapter for Gram Elements server handlers.
+ *
+ * @example
+ * ```typescript
+ * import { createExpressHandler } from '@gram-ai/elements/server/express'
+ * import express from 'express'
+ *
+ * const app = express()
+ * app.use(express.json())
+ *
+ * app.post('/chat/session', createExpressHandler({
+ *   embedOrigin: 'http://localhost:3000',
+ *   userIdentifier: 'user-123',
+ *   expiresAfter: 3600,
+ * }))
+ *
+ * app.listen(3000)
+ * ```
+ */
+
+import type { Request, Response } from 'express'
+import { createChatSession, type SessionHandlerOptions } from './core'
+
+/**
+ * Create an Express request handler for the chat session endpoint.
+ *
+ * @param options - Session configuration options
+ * @returns Express request handler
+ */
+export function createExpressHandler(
+  options:
+    | SessionHandlerOptions
+    | ((req: Request) => SessionHandlerOptions | Promise<SessionHandlerOptions>)
+) {
+  return async (req: Request, res: Response) => {
+    const projectSlug = Array.isArray(req.headers['gram-project'])
+      ? req.headers['gram-project'][0]
+      : req.headers['gram-project']
+
+    if (!projectSlug) {
+      res.status(400).json({ error: 'Missing Gram-Project header' })
+      return
+    }
+
+    const sessionOptions =
+      typeof options === 'function' ? await options(req) : options
+
+    const result = await createChatSession({
+      projectSlug,
+      options: sessionOptions,
+    })
+
+    res.status(result.status)
+    Object.entries(result.headers).forEach(([key, value]) => {
+      res.setHeader(key, value)
+    })
+    res.send(result.body)
+  }
+}

package/src/server/fastify.ts

@@ -0,0 +1,61 @@
+/**
+ * Fastify adapter for Gram Elements server handlers.
+ *
+ * @example
+ * ```typescript
+ * import { createFastifyHandler } from '@gram-ai/elements/server/fastify'
+ * import Fastify from 'fastify'
+ *
+ * const fastify = Fastify()
+ *
+ * fastify.post('/chat/session', createFastifyHandler({
+ *   embedOrigin: 'http://localhost:3000',
+ *   userIdentifier: 'user-123',
+ *   expiresAfter: 3600,
+ * }))
+ *
+ * fastify.listen({ port: 3000 })
+ * ```
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify'
+import { createChatSession, type SessionHandlerOptions } from './core'
+
+/**
+ * Create a Fastify route handler for the chat session endpoint.
+ *
+ * @param options - Session configuration options
+ * @returns Fastify route handler
+ */
+export function createFastifyHandler(
+  options:
+    | SessionHandlerOptions
+    | ((
+        request: FastifyRequest
+      ) => SessionHandlerOptions | Promise<SessionHandlerOptions>)
+) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const projectSlug = Array.isArray(request.headers['gram-project'])
+      ? request.headers['gram-project'][0]
+      : request.headers['gram-project']
+
+    if (!projectSlug) {
+      reply.code(400).send({ error: 'Missing Gram-Project header' })
+      return
+    }
+
+    const sessionOptions =
+      typeof options === 'function' ? await options(request) : options
+
+    const result = await createChatSession({
+      projectSlug,
+      options: sessionOptions,
+    })
+
+    reply
+      .code(result.status)
+      .headers(result.headers)
+      .type('application/json')
+      .send(result.body)
+  }
+}