@gram-ai/elements 1.26.0 → 1.27.0

package/README.md

@@ -43,36 +43,104 @@ pnpm add @gram-ai/elements
 
 ## Setting up your backend
 
-At the moment, we provide a set of handlers via the `@gram-ai/elements/server` package that you can use to automatically setup your backend for usage with Gram Elements. The example below demonstrates the setup for Express:
+We provide framework-specific adapters to make it easy to set up a backend endpoint for Gram Elements. These adapters handle the session token creation securely on your server without exposing your `GRAM_API_KEY` to the browser.
+
+### Express
 
 ```typescript
-import { createElementsServerHandlers } from '@gram-ai/elements/server'
+import { createExpressHandler } from '@gram-ai/elements/server/express'
 import express from 'express'
 
-const handlers = createElementsServerHandlers()
 const app = express()
-
 app.use(express.json())
 
-app.post('/chat/session', (req, res) =>
-  handlers.session(req, res, {
-    // The origin from which the token will be used
-    embedOrigin: 'http://localhost:3000',
-    // A free-form user identifier
-    userIdentifier: 'user-123',
-    // Token expiration in seconds (max / default 3600)
+app.post('/chat/session', createExpressHandler({
+  embedOrigin: 'http://localhost:3000',
+  userIdentifier: 'user-123',
+  expiresAfter: 3600, // optional, max 3600 seconds
+}))
+
+app.listen(3000)
+```
+
+For dynamic options based on the request:
+
+```typescript
+app.post('/chat/session', createExpressHandler((req) => ({
+  embedOrigin: req.headers.origin || 'http://localhost:3000',
+  userIdentifier: req.user?.id || 'anonymous',
+  expiresAfter: 3600,
+})))
+```
+
+### Next.js App Router
+
+```typescript
+// app/chat/session/route.ts
+import { createNextHandler } from '@gram-ai/elements/server/nextjs'
+
+export const POST = createNextHandler({
+  embedOrigin: 'http://localhost:3000',
+  userIdentifier: 'user-123',
+  expiresAfter: 3600,
+})
+import { cookies } from 'next/headers'
+
+export const POST = createNextHandler(async (request) => {
+  const cookieStore = await cookies()
+  const userId = cookieStore.get('userId')?.value || 'anonymous'
+
+  return {
+    embedOrigin: request.headers.get('origin') || 'http://localhost:3000',
+    userIdentifier: userId,
     expiresAfter: 3600,
-  })
-)
+  }
+})
+```
+
+### Fastify
+
+```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 })
 ```
 
-You will need to add an environment variable to your backend and make it available to the process:
+### Hono
 
+```typescript
+import { createHonoHandler } from '@gram-ai/elements/server/hono'
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app.post('/chat/session', createHonoHandler({
+  embedOrigin: 'http://localhost:3000',
+  userIdentifier: 'user-123',
+  expiresAfter: 3600,
+}))
+
+export default app
 ```
+
+### Environment Variables
+
+All adapters require the `GRAM_API_KEY` environment variable to be set:
+
+```bash
 GRAM_API_KEY=xxx
 ```
 
-This will enable your backend chat endpoint to talk to our servers securely.
+This key is kept on your server and never exposed to the browser, ensuring secure communication with Gram's API.
 
 ## Setting up your frontend
 

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

@@ -6,5 +6,5 @@ type Story = StoryFn<typeof Chat>;
 export declare const SystemPrompt: Story;
 export declare const WithImplicitSessionAuth: Story;
 export declare const WithExplicitSessionAuth: Story;
-export declare const WithStaticSessionAuth: Story;
+export declare const WithDangerousApiKey: Story;
 export declare const LanguageModel: Story;

package/dist/components/ui/calendar.d.ts

@@ -0,0 +1,25 @@
+export interface CalendarProps {
+    /** Selected date range */
+    selected?: {
+        start: Date | null;
+        end: Date | null;
+    };
+    /** Called when a date or range is selected */
+    onSelect?: (range: {
+        start: Date;
+        end: Date | null;
+    }) => void;
+    /** Whether range selection is enabled */
+    mode?: 'single' | 'range';
+    /** Disable dates before this */
+    minDate?: Date;
+    /** Disable dates after this */
+    maxDate?: Date;
+    /** Additional className */
+    className?: string;
+}
+declare function Calendar({ selected, onSelect, mode, minDate, maxDate, className, }: CalendarProps): import("react/jsx-runtime").JSX.Element;
+declare namespace Calendar {
+    var displayName: string;
+}
+export { Calendar };

package/dist/components/ui/time-range-picker.d.ts

@@ -0,0 +1,46 @@
+export interface TimeRange {
+    from: Date;
+    to: Date;
+}
+export type DateRangePreset = '15m' | '1h' | '4h' | '1d' | '2d' | '3d' | '7d' | '15d' | '30d' | '90d';
+export interface TimeRangePreset {
+    label: string;
+    shortLabel: string;
+    value: DateRangePreset;
+    getRange: () => TimeRange;
+}
+export declare const PRESETS: TimeRangePreset[];
+export declare function getPresetRange(preset: DateRangePreset): TimeRange;
+export interface TimeRangePickerProps {
+    /** Current preset value */
+    preset?: DateRangePreset | null;
+    /** Current custom range */
+    customRange?: TimeRange | null;
+    /** Called when a preset is selected */
+    onPresetChange?: (preset: DateRangePreset) => void;
+    /** Called when a custom range is selected */
+    onCustomRangeChange?: (from: Date, to: Date, label?: string) => void;
+    /** Called to clear custom range */
+    onClearCustomRange?: () => void;
+    /** Initial label for custom range (from URL params) */
+    customRangeLabel?: string | null;
+    /** Show LIVE mode option */
+    showLive?: boolean;
+    /** Is LIVE mode active */
+    isLive?: boolean;
+    /** Called when LIVE mode changes */
+    onLiveChange?: (isLive: boolean) => void;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Timezone display (e.g., "UTC-08:00") */
+    timezone?: string;
+    /** API URL for AI parsing (defaults to window.location.origin) */
+    apiUrl?: string;
+    /** Project slug for API authentication */
+    projectSlug?: string;
+}
+declare function TimeRangePicker({ preset, customRange, onPresetChange, onCustomRangeChange, onClearCustomRange, customRangeLabel: initialCustomLabel, showLive, isLive, onLiveChange, disabled, timezone, apiUrl, projectSlug, }: TimeRangePickerProps): import("react/jsx-runtime").JSX.Element;
+declare namespace TimeRangePicker {
+    var displayName: string;
+}
+export { TimeRangePicker };

package/dist/components/ui/time-range-picker.stories.d.ts

@@ -0,0 +1,37 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { TimeRangePicker } from './time-range-picker';
+declare const meta: Meta<typeof TimeRangePicker>;
+export default meta;
+type Story = StoryObj<typeof TimeRangePicker>;
+/**
+ * Default time range picker with preset badges and calendar.
+ * Supports natural language input with AI parsing.
+ */
+export declare const Default: Story;
+/**
+ * Time range picker with timezone indicator.
+ */
+export declare const WithTimezone: Story;
+/**
+ * With LIVE mode toggle enabled.
+ */
+export declare const WithLiveMode: Story;
+/**
+ * Disabled state.
+ */
+export declare const Disabled: Story;
+/**
+ * Full Datadog-style configuration with all features.
+ * Type natural language like "3 days ago", "last Wednesday", "past 2 weeks".
+ */
+export declare const DatadogStyle: Story;
+/**
+ * Natural language parsing demo.
+ * Type things like:
+ * - "yesterday"
+ * - "3 days ago"
+ * - "last Wednesday"
+ * - "past 2 weeks"
+ * - "January 2024"
+ */
+export declare const NaturalLanguageParsing: Story;

package/dist/components/ui/tool-ui.d.ts

@@ -14,6 +14,19 @@ type ContentItem = {
         '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;
@@ -33,6 +46,8 @@ interface ToolUIProps {
     defaultExpanded?: boolean;
     /** Additional class names */
     className?: string;
+    /** MCP tool annotations */
+    annotations?: ToolAnnotations;
     /** Approval callbacks */
     onApproveOnce?: () => void;
     onApproveForSession?: () => void;
@@ -64,7 +79,7 @@ declare function SyntaxHighlightedCode({ text, language, className, }: {
     className?: string;
 }): import("react/jsx-runtime").JSX.Element;
 declare function ToolUISection({ title, content, defaultExpanded, highlightSyntax, language, }: ToolUISectionProps): import("react/jsx-runtime").JSX.Element;
-declare function ToolUI({ name, icon, provider, status, request, result, defaultExpanded, className, onApproveOnce, onApproveForSession, onDeny, }: ToolUIProps): import("react/jsx-runtime").JSX.Element;
+declare function ToolUI({ name, icon, provider, status, request, result, defaultExpanded, className, annotations, onApproveOnce, onApproveForSession, onDeny, }: ToolUIProps): import("react/jsx-runtime").JSX.Element;
 interface ToolUIGroupProps {
     /** Title for the group header */
     title: string;

package/dist/core-Cqad6-xW.js

@@ -0,0 +1,36 @@
+async function r(t) {
+  const s = process.env.GRAM_API_URL ?? "https://app.getgram.ai";
+  try {
+    const e = await fetch(s + "/rpc/chatSessions.create", {
+      method: "POST",
+      body: JSON.stringify({
+        embed_origin: t.options.embedOrigin,
+        user_identifier: t.options.userIdentifier,
+        expires_after: t.options.expiresAfter
+      }),
+      headers: {
+        "Content-Type": "application/json",
+        "Gram-Project": t.projectSlug,
+        "Gram-Key": t.options.apiKey ?? process.env.GRAM_API_KEY ?? ""
+      }
+    }), o = await e.text();
+    return {
+      status: e.status,
+      body: o,
+      headers: { "Content-Type": "application/json" }
+    };
+  } catch (e) {
+    const o = e instanceof Error ? e.message : "Unknown error";
+    return console.error("Failed to create chat session:", e), {
+      status: 500,
+      body: JSON.stringify({
+        error: "Failed to create chat session: " + o
+      }),
+      headers: { "Content-Type": "application/json" }
+    };
+  }
+}
+export {
+  r as c
+};
+//# sourceMappingURL=core-Cqad6-xW.js.map

package/dist/core-Cqad6-xW.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-Cqad6-xW.js","sources":["../src/server/core.ts"],"sourcesContent":null,"names":["createChatSession","request","base","response","body","error","errorMessage"],"mappings":"AA2CA,eAAsBA,EACpBC,GACgC;AAChC,QAAMC,IAAO,QAAQ,IAAI,gBAAgB;AAEzC,MAAI;AACF,UAAMC,IAAW,MAAM,MAAMD,IAAO,4BAA4B;AAAA,MAC9D,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU;AAAA,QACnB,cAAcD,EAAQ,QAAQ;AAAA,QAC9B,iBAAiBA,EAAQ,QAAQ;AAAA,QACjC,eAAeA,EAAQ,QAAQ;AAAA,MAAA,CAChC;AAAA,MACD,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,gBAAgBA,EAAQ;AAAA,QACxB,YAAYA,EAAQ,QAAQ,UAAU,QAAQ,IAAI,gBAAgB;AAAA,MAAA;AAAA,IACpE,CACD,GAEKG,IAAO,MAAMD,EAAS,KAAA;AAE5B,WAAO;AAAA,MACL,QAAQA,EAAS;AAAA,MACjB,MAAAC;AAAA,MACA,SAAS,EAAE,gBAAgB,mBAAA;AAAA,IAAmB;AAAA,EAElD,SAASC,GAAO;AACd,UAAMC,IACJD,aAAiB,QAAQA,EAAM,UAAU;AAC3C,mBAAQ,MAAM,kCAAkCA,CAAK,GAE9C;AAAA,MACL,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU;AAAA,QACnB,OAAO,oCAAoCC;AAAA,MAAA,CAC5C;AAAA,MACD,SAAS,EAAE,gBAAgB,mBAAA;AAAA,IAAmB;AAAA,EAElD;AACF;"}

package/dist/core-DBxmxwCi.cjs

@@ -0,0 +1,2 @@
+"use strict";async function r(t){const o=process.env.GRAM_API_URL??"https://app.getgram.ai";try{const e=await fetch(o+"/rpc/chatSessions.create",{method:"POST",body:JSON.stringify({embed_origin:t.options.embedOrigin,user_identifier:t.options.userIdentifier,expires_after:t.options.expiresAfter}),headers:{"Content-Type":"application/json","Gram-Project":t.projectSlug,"Gram-Key":t.options.apiKey??process.env.GRAM_API_KEY??""}}),s=await e.text();return{status:e.status,body:s,headers:{"Content-Type":"application/json"}}}catch(e){const s=e instanceof Error?e.message:"Unknown error";return console.error("Failed to create chat session:",e),{status:500,body:JSON.stringify({error:"Failed to create chat session: "+s}),headers:{"Content-Type":"application/json"}}}}exports.createChatSession=r;
+//# sourceMappingURL=core-DBxmxwCi.cjs.map

package/dist/core-DBxmxwCi.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-DBxmxwCi.cjs","sources":["../src/server/core.ts"],"sourcesContent":null,"names":["createChatSession","request","base","response","body","error","errorMessage"],"mappings":"aA2CA,eAAsBA,EACpBC,EACgC,CAChC,MAAMC,EAAO,QAAQ,IAAI,cAAgB,yBAEzC,GAAI,CACF,MAAMC,EAAW,MAAM,MAAMD,EAAO,2BAA4B,CAC9D,OAAQ,OACR,KAAM,KAAK,UAAU,CACnB,aAAcD,EAAQ,QAAQ,YAC9B,gBAAiBA,EAAQ,QAAQ,eACjC,cAAeA,EAAQ,QAAQ,YAAA,CAChC,EACD,QAAS,CACP,eAAgB,mBAChB,eAAgBA,EAAQ,YACxB,WAAYA,EAAQ,QAAQ,QAAU,QAAQ,IAAI,cAAgB,EAAA,CACpE,CACD,EAEKG,EAAO,MAAMD,EAAS,KAAA,EAE5B,MAAO,CACL,OAAQA,EAAS,OACjB,KAAAC,EACA,QAAS,CAAE,eAAgB,kBAAA,CAAmB,CAElD,OAASC,EAAO,CACd,MAAMC,EACJD,aAAiB,MAAQA,EAAM,QAAU,gBAC3C,eAAQ,MAAM,iCAAkCA,CAAK,EAE9C,CACL,OAAQ,IACR,KAAM,KAAK,UAAU,CACnB,MAAO,kCAAoCC,CAAA,CAC5C,EACD,QAAS,CAAE,eAAgB,kBAAA,CAAmB,CAElD,CACF"}

package/dist/elements.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-ChW-CSuu.cjs"),t=require("./index-BpJstUh1.cjs");exports.Chat=e.Chat;exports.ChatHistory=e.ChatHistory;exports.ElementsProvider=e.ElementsProvider;exports.GramElementsProvider=e.ElementsProvider;exports.MODELS=e.MODELS;exports.Replay=e.Replay;exports.ShareButton=e.ShareButton;exports.defineFrontendTool=e.defineFrontendTool;exports.trackError=e.trackError;exports.useRecordCassette=e.useRecordCassette;exports.useThreadId=e.useThreadId;exports.useChatId=t.useChatId;exports.useElements=t.useElements;exports.useGramElements=t.useElements;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-CP-wWZCV.cjs"),r=require("./index-BpJstUh1.cjs");exports.Calendar=e.Calendar;exports.Chat=e.Chat;exports.ChatHistory=e.ChatHistory;exports.ElementsProvider=e.ElementsProvider;exports.GramElementsProvider=e.ElementsProvider;exports.MODELS=e.MODELS;exports.PRESETS=e.PRESETS;exports.Replay=e.Replay;exports.ShareButton=e.ShareButton;exports.TimeRangePicker=e.TimeRangePicker;exports.defineFrontendTool=e.defineFrontendTool;exports.getPresetRange=e.getPresetRange;exports.trackError=e.trackError;exports.useRecordCassette=e.useRecordCassette;exports.useThreadId=e.useThreadId;exports.useChatId=r.useChatId;exports.useElements=r.useElements;exports.useGramElements=r.useElements;
 //# sourceMappingURL=elements.cjs.map