@gram-ai/elements 1.26.1 → 1.27.0

package/src/server/tanstack-start.ts

@@ -0,0 +1,110 @@
+/**
+ * TanStack Start adapter for Gram Elements server handlers.
+ *
+ * Provides two approaches for session creation:
+ *
+ * 1. **Server Function (RPC)** — use `createTanStackStartSessionFn` to create
+ *    a `createServerFn` that can be called directly from client code and passed
+ *    to `session` in the Elements config.
+ *
+ * 2. **API Route** — use `createTanStackStartHandler` to create a handler for
+ *    TanStack Start server routes (similar to the Next.js adapter).
+ *
+ * @example Server Function approach
+ * ```typescript
+ * // session.functions.ts
+ * import { createTanStackStartSessionFn } from '@gram-ai/elements/server/tanstack-start'
+ *
+ * export const getSession = createTanStackStartSessionFn({
+ *   embedOrigin: 'http://localhost:3000',
+ *   userIdentifier: 'user-123',
+ *   expiresAfter: 3600,
+ * })
+ * ```
+ *
+ * @example API Route approach
+ * ```typescript
+ * // routes/api/chat.session.ts
+ * import { createTanStackStartHandler } from '@gram-ai/elements/server/tanstack-start'
+ *
+ * const handler = createTanStackStartHandler({
+ *   embedOrigin: 'http://localhost:3000',
+ *   userIdentifier: 'user-123',
+ *   expiresAfter: 3600,
+ * })
+ * ```
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+import { createChatSession, type SessionHandlerOptions } from './core'
+
+/**
+ * Create a TanStack Start server function for session creation.
+ *
+ * The returned function can be called from client code (RPC-style) and passed
+ * to `session` in the Gram Elements config.
+ *
+ * @param options - Session configuration options
+ * @returns A `createServerFn` instance callable from the client
+ */
+export function createTanStackStartSessionFn(options: SessionHandlerOptions) {
+  return createServerFn({ method: 'POST' })
+    .inputValidator((data: { projectSlug: string }) => data)
+    .handler(async ({ data }) => {
+      const result = await createChatSession({
+        projectSlug: data.projectSlug,
+        options,
+      })
+
+      if (result.status !== 200) {
+        throw new Error(`Failed to create chat session: ${result.body}`)
+      }
+
+      const parsed = JSON.parse(result.body) as { client_token: string }
+      return parsed.client_token
+    })
+}
+
+/**
+ * Create a TanStack Start server route handler for the chat session endpoint.
+ *
+ * Returns a function compatible with TanStack Start server route handlers
+ * that accepts a Web API `Request` and returns a `Response`.
+ *
+ * @param options - Session configuration options
+ * @returns Handler function `(request: Request) => Promise<Response>`
+ */
+export function createTanStackStartHandler(
+  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.ts

@@ -1,4 +1,5 @@
 import { IncomingMessage, ServerResponse } from 'node:http'
+import { createChatSession, type SessionHandlerOptions } from './server/core'
 
 type ServerHandler<T> = (
   req: IncomingMessage,
@@ -23,67 +24,54 @@ interface ServerHandlers {
   session: ServerHandler<SessionHandlerOptions>
 }
 
+/**
+ * @deprecated Use framework-specific adapters instead:
+ * - `@gram-ai/elements/server/express` for Express
+ * - `@gram-ai/elements/server/nextjs` for Next.js App Router
+ * - `@gram-ai/elements/server/fastify` for Fastify
+ * - `@gram-ai/elements/server/hono` for Hono
+ * - `@gram-ai/elements/server/bun` for Bun
+ */
 export const createElementsServerHandlers = (): ServerHandlers => {
   return {
     session: sessionHandler,
   }
 }
 
-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
-}
+export type { SessionHandlerOptions }
 
 const sessionHandler: ServerHandler<SessionHandlerOptions> = async (
   req,
   res,
   options
 ) => {
-  const base = process.env.GRAM_API_URL ?? 'https://app.getgram.ai'
-  if (req.method === 'POST') {
-    const projectSlug = Array.isArray(req.headers['gram-project'])
-      ? req.headers['gram-project'][0]
-      : req.headers['gram-project']
+  if (req.method !== 'POST') {
+    res.writeHead(405, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Method not allowed' }))
+    return
+  }
 
-    fetch(base + '/rpc/chatSessions.create', {
-      method: 'POST',
-      body: JSON.stringify({
-        embed_origin: options?.embedOrigin,
-        user_identifier: options?.userIdentifier,
-        expires_after: options?.expiresAfter,
-      }),
-      headers: {
-        'Content-Type': 'application/json',
-        'Gram-Project': typeof projectSlug === 'string' ? projectSlug : '',
-        'Gram-Key': process.env.GRAM_API_KEY ?? '',
-      },
-    })
-      .then(async (response) => {
-        const body = await response.text()
-        res.writeHead(response.status, { 'Content-Type': 'application/json' })
-        res.end(body)
-      })
-      .catch((error) => {
-        console.error('Failed to create chat session:', error)
-        res.writeHead(500, { 'Content-Type': 'application/json' })
-        res.end(
-          JSON.stringify({
-            error: 'Failed to create chat session: ' + error.message,
-          })
-        )
-      })
+  const projectSlug = Array.isArray(req.headers['gram-project'])
+    ? req.headers['gram-project'][0]
+    : req.headers['gram-project']
+
+  if (!projectSlug || typeof projectSlug !== 'string') {
+    res.writeHead(400, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Missing Gram-Project header' }))
+    return
   }
+
+  if (!options) {
+    res.writeHead(400, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Missing session options' }))
+    return
+  }
+
+  const result = await createChatSession({
+    projectSlug,
+    options,
+  })
+
+  res.writeHead(result.status, result.headers)
+  res.end(result.body)
 }

package/src/types/index.ts

@@ -363,11 +363,16 @@ export type BaseApiConfig = {
   headers?: Record<string, string>
 }
 
+/**
+ * @deprecated Use `{ session: mySessionFn }` instead. Will be removed in a future major version.
+ */
 export type SessionAuthConfig = {
   /**
    * The function to use to retrieve the session token from the backend endpoint.
    * By default, this will attempt to fetch the session token from `/chat/session`.
    *
+   * @deprecated Use `session` instead: `{ session: mySessionFn }`.
+   *
    * @example
    * const config: ElementsConfig = {
    *   api: {
@@ -381,19 +386,14 @@ export type SessionAuthConfig = {
 }
 
 /**
- * The static session auth config is used to authenticate the Elements library using a static session token only.
- *
- * @example
- * const config: ElementsConfig = {
- *   api: {
- *     sessionToken: 'your-session-token',
- *   },
- * }
+ * @deprecated Use `{ session: 'your-token' }` instead. Will be removed in a future major version.
  */
 export type StaticSessionAuthConfig = {
   /**
    * A static session token to use if you haven't yet configured a session endpoint.
    *
+   * @deprecated Use `session` instead: `{ session: 'your-token' }`.
+   *
    * @example
    * const config: ElementsConfig = {
    *   api: {
@@ -404,11 +404,27 @@ export type StaticSessionAuthConfig = {
   sessionToken: string
 }
 
+export type DangerousApiKeyAuthConfig = {
+  /** WARNING: Exposes API key in browser. Dev/testing only. */
+  dangerousApiKey: string
+}
+
+export type UnifiedSessionAuthConfig = {
+  /** String = static token (shows expiry warning). Function = dynamic fetcher. */
+  session: string | GetSessionFn
+}
+
 /**
- * API configuration - can be just the URL, or URL with session auth, or URL with API key auth.
+ * API configuration - base URL, session auth (static token or fetcher function),
+ * or dangerousApiKey for quick dev/testing without a backend session endpoint.
+ *
+ * The legacy `sessionFn` / `sessionToken` fields still work but are deprecated
+ * in favour of the unified `session` field.
  */
 export type ApiConfig =
   | BaseApiConfig
+  | (BaseApiConfig & UnifiedSessionAuthConfig)
+  | (BaseApiConfig & DangerousApiKeyAuthConfig)
   | (BaseApiConfig & SessionAuthConfig)
   | (BaseApiConfig & StaticSessionAuthConfig)