@fayz-ai/sdk 0.9.0-next.1 → 0.10.0

package/src/agent.test.ts

@@ -1,114 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-import { createFayzAgentClient, FayzAgentError } from './agent'
-
-function jsonResponse(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { 'Content-Type': 'application/json' },
-  })
-}
-
-function client(fetcher: typeof fetch) {
-  return createFayzAgentClient({
-    baseUrl: 'http://localhost:5173/api',
-    projectId: 'project-1',
-    publishableKey: 'fayzpk_test',
-    fetcher,
-  })
-}
-
-describe('createFayzAgentClient', () => {
-  it('targets the public broker and presents the publishable key', async () => {
-    const fetcher = vi.fn<typeof fetch>().mockResolvedValue(
-      jsonResponse({ conversationId: 'conv-1', content: 'Hi', toolCalls: [] }),
-    )
-
-    await client(fetcher).chat({ message: 'Hello' })
-
-    const [url, init] = fetcher.mock.calls[0]
-    expect(url).toBe('http://localhost:5173/api/public/projects/project-1/agents/chat')
-    expect((init?.headers as Record<string, string>)['x-fayz-agent-key']).toBe('fayzpk_test')
-    expect(JSON.parse(init?.body as string)).toEqual({ message: 'Hello' })
-  })
-
-  it('forwards the tool catalog and returns the calls the model asked for', async () => {
-    const toolCall = { id: 'call-1', name: 'getTeamMembers', arguments: { role: 'staff' } }
-    const fetcher = vi.fn<typeof fetch>().mockResolvedValue(
-      jsonResponse({ conversationId: 'conv-1', content: '', toolCalls: [toolCall] }),
-    )
-
-    const response = await client(fetcher).chat({
-      message: "Who's on my team?",
-      tools: [
-        {
-          name: 'getTeamMembers',
-          description: 'Lists team members.',
-          parameters: { type: 'object', properties: { role: { type: 'string' } } },
-        },
-      ],
-    })
-
-    expect(response.toolCalls).toEqual([toolCall])
-    expect(JSON.parse(fetcher.mock.calls[0][1]?.body as string).tools).toHaveLength(1)
-  })
-
-  it('sends tool results with the conversation id and no new message', async () => {
-    const fetcher = vi.fn<typeof fetch>().mockResolvedValue(
-      jsonResponse({ conversationId: 'conv-1', content: 'Ana and Bruno.', toolCalls: [] }),
-    )
-
-    const response = await client(fetcher).chat({
-      conversationId: 'conv-1',
-      toolResults: [{ toolCallId: 'call-1', content: '{"total":2}' }],
-    })
-
-    const body = JSON.parse(fetcher.mock.calls[0][1]?.body as string)
-    expect(body).toEqual({
-      conversationId: 'conv-1',
-      toolResults: [{ toolCallId: 'call-1', content: '{"total":2}' }],
-    })
-    expect(response.content).toBe('Ana and Bruno.')
-    expect(response.toolCalls).toEqual([])
-  })
-
-  it('tolerates a response that omits toolCalls', async () => {
-    const fetcher = vi.fn<typeof fetch>().mockResolvedValue(
-      jsonResponse({ conversationId: 'conv-1', content: 'Hi' }),
-    )
-
-    const response = await client(fetcher).chat({ message: 'Hello' })
-
-    expect(response.toolCalls).toEqual([])
-  })
-
-  it('surfaces the broker error message and status', async () => {
-    const fetcher = vi
-      .fn<typeof fetch>()
-      .mockResolvedValue(jsonResponse({ error: 'Invalid agent key' }, 401))
-
-    await expect(client(fetcher).chat({ message: 'Hello' })).rejects.toMatchObject({
-      name: 'FayzAgentError',
-      status: 401,
-      message: 'Invalid agent key',
-    })
-  })
-
-  it('falls back to a generic message when the error body is not JSON', async () => {
-    const fetcher = vi
-      .fn<typeof fetch>()
-      .mockResolvedValue(new Response('gateway down', { status: 502 }))
-
-    await expect(client(fetcher).getInfo()).rejects.toThrow(FayzAgentError)
-  })
-
-  it('reads the agent identity from /config', async () => {
-    const agent = { id: 'a-1', name: 'Glow', description: null, icon: '💇' }
-    const fetcher = vi.fn<typeof fetch>().mockResolvedValue(jsonResponse({ agent }))
-
-    expect(await client(fetcher).getInfo()).toEqual(agent)
-    expect(fetcher.mock.calls[0][0]).toBe(
-      'http://localhost:5173/api/public/projects/project-1/agents/config',
-    )
-  })
-})

package/src/agent.ts

@@ -1,335 +0,0 @@
-/**
- * Client for the Fayz agent broker — the runtime surface a generated app uses
- * to reach the AI agent configured for its project in Fayz.
- *
- * Mirrors `createFayzShopProvider`: the app holds a publishable key, Fayz holds
- * the model credentials. The key ships in the bundle the same way a Supabase
- * anon key does; it only ever resolves to the one agent its web channel belongs
- * to, and the broker rate-limits per project.
- *
- * Tools are client-plane. The app declares what it can do (`tools`), the model
- * decides what to call, and the app executes the calls against its own session
- * before handing results back. Fayz never needs the app's data credentials.
- */
-
-export interface FayzAgentClientOptions {
-  /** Fayz API base, e.g. https://fayz.ai/api */
-  baseUrl: string
-  projectId: string
-  /** Publishable key of the project's WEB agent channel. */
-  publishableKey: string
-  fetcher?: typeof fetch
-}
-
-export interface FayzAgentTool {
-  name: string
-  description: string
-  /** JSON Schema for the tool's arguments. */
-  parameters?: Record<string, unknown>
-}
-
-export interface FayzAgentToolCall {
-  id: string
-  name: string
-  arguments: Record<string, unknown>
-}
-
-export interface FayzAgentToolResult {
-  toolCallId: string
-  content: string
-}
-
-/**
- * A file the user attached, described rather than uploaded.
- *
- * The bytes stay in the browser: a spreadsheet of clients or patients is
- * personal data, and handing it to a model provider so it can "take a look" is
- * a disclosure, not a convenience. What travels is the shape — sheets,
- * headers, how many rows, the inferred type per column and a handful of sample
- * rows. Enough to plan an import; never the data set itself.
- */
-export interface AgentAttachmentColumn {
-  name: string
-  type: 'text' | 'number' | 'date' | 'boolean' | 'email' | 'phone'
-  /** Literal shape when known ('dd/mm/yyyy', '1.234,56'). */
-  format?: string
-  /** Why the column is not the type it looks like (ambiguous dates, mixed values). */
-  note?: string
-}
-
-export interface AgentAttachmentSheet {
-  name: string
-  headers: string[]
-  rowCount?: number
-  sample: string[][]
-  columnTypes: AgentAttachmentColumn[]
-}
-
-export interface AgentAttachmentDigest {
-  id: string
-  name: string
-  mime: string
-  size: number
-  kind: 'spreadsheet' | 'csv' | 'text' | 'image' | 'pdf' | 'binary'
-  /** Multi-tab spreadsheets. Single-tab files use the flat fields below. */
-  sheets?: AgentAttachmentSheet[]
-  headers?: string[]
-  rowCount?: number
-  sample?: string[][]
-  columnTypes?: AgentAttachmentColumn[]
-  /** Head of a text/markdown file. */
-  preview?: string
-  /** What the reader had to guess at, truncate or give up on. */
-  warnings?: string[]
-}
-
-export interface FayzAgentChatInput {
-  /** New end-user message. Omit when replying with tool results. */
-  message?: string
-  conversationId?: string
-  /** Identity of the end user, required by channels with an INTERNAL audience. */
-  externalUserId?: string
-  /** Human label for that user, so the owner's dashboard shows a name. */
-  externalUserName?: string
-  tools?: FayzAgentTool[]
-  toolResults?: FayzAgentToolResult[]
-  /** Decision for a server-parked write (broker PENDING_CONFIRMATION step). */
-  confirmAction?: { id: string; approved: boolean }
-  /** Runtime context the agent should know about (page, locale, tenant). */
-  context?: Record<string, unknown>
-  /** Files the user attached this turn, as digests — never as bytes. */
-  attachments?: AgentAttachmentDigest[]
-  signal?: AbortSignal
-}
-
-/** A server-plane write the broker parked pending human confirmation. */
-export interface FayzAgentPendingAction {
-  id: string
-  toolName: string
-  title?: string
-  params?: Record<string, unknown>
-}
-
-export interface FayzAgentChatResponse {
-  conversationId: string
-  content: string
-  toolCalls: FayzAgentToolCall[]
-  /** Present when the broker is waiting on a confirmAction for this write. */
-  pendingAction?: FayzAgentPendingAction
-}
-
-export interface FayzAgentInfo {
-  id: string
-  name: string
-  description: string | null
-  icon: string | null
-}
-
-export class FayzAgentError extends Error {
-  constructor(
-    message: string,
-    readonly status: number,
-  ) {
-    super(message)
-    this.name = 'FayzAgentError'
-  }
-}
-
-export interface FayzAgentConversationSummary {
-  id: string
-  title: string | null
-  /** Last activity — the field the list is ordered by. */
-  updatedAt: string
-}
-
-export interface FayzAgentConversationMessage {
-  id: string
-  role: string
-  content: string
-  createdAt: string
-  /** Files the user attached to this turn, as the digest that was sent. Only
-   *  the description — the bytes never left the browser that produced them. */
-  attachments?: AgentAttachmentDigest[]
-  /** Tool calls this reply made, with their results — so a resumed thread shows
-   *  the same trace and record links it showed live. */
-  toolCalls?: Array<{
-    name: string
-    arguments?: Record<string, unknown>
-    result?: string
-  }>
-}
-
-export interface FayzAgentConversationDetail {
-  id: string
-  title: string | null
-  messages: FayzAgentConversationMessage[]
-}
-
-export interface FayzAgentStreamCallbacks {
-  /** Fired per text delta with the accumulated text so far (fill-in-place UIs). */
-  onDelta?: (accumulated: string, delta: string) => void
-}
-
-export interface FayzAgentClient {
-  /** Identity of the agent behind the key, for rendering its name/icon. */
-  getInfo(signal?: AbortSignal): Promise<FayzAgentInfo>
-  chat(input: FayzAgentChatInput): Promise<FayzAgentChatResponse>
-  /**
-   * Like `chat`, but asks the broker for an SSE stream (`Accept:
-   * text/event-stream`) and reports text deltas as they arrive. Falls back
-   * transparently to the JSON round-trip when the broker predates streaming —
-   * callers can always use this and treat `onDelta` as best-effort.
-   */
-  chatStream(input: FayzAgentChatInput, callbacks?: FayzAgentStreamCallbacks): Promise<FayzAgentChatResponse>
-  /** The signed-in user's own threads, most-recently-active first. */
-  listConversations(externalUserId?: string, signal?: AbortSignal): Promise<FayzAgentConversationSummary[]>
-  /** One thread with its transcript — 404s on another user's thread. */
-  getConversation(
-    conversationId: string,
-    externalUserId?: string,
-    signal?: AbortSignal,
-  ): Promise<FayzAgentConversationDetail>
-}
-
-function normalizeResponse(body: Partial<FayzAgentChatResponse>): FayzAgentChatResponse {
-  return {
-    conversationId: body.conversationId ?? '',
-    content: body.content ?? '',
-    toolCalls: body.toolCalls ?? [],
-    ...(body.pendingAction ? { pendingAction: body.pendingAction } : {}),
-  }
-}
-
-export function createFayzAgentClient(options: FayzAgentClientOptions): FayzAgentClient {
-  const fetcher = options.fetcher ?? globalThis.fetch
-  const base = `${options.baseUrl.replace(/\/+$/, '')}/public/projects/${options.projectId}/agents`
-  const headers = {
-    'Content-Type': 'application/json',
-    'x-fayz-agent-key': options.publishableKey,
-  }
-
-  async function request<T>(path: string, init: RequestInit): Promise<T> {
-    const response = await fetcher(`${base}${path}`, { ...init, headers })
-    if (!response.ok) {
-      const body = (await response.json().catch(() => null)) as { error?: string } | null
-      throw new FayzAgentError(body?.error ?? `Agent request failed (${response.status})`, response.status)
-    }
-    return (await response.json()) as T
-  }
-
-  return {
-    async getInfo(signal) {
-      const body = await request<{ agent: FayzAgentInfo }>('/config', { method: 'GET', signal })
-      return body.agent
-    },
-
-    async chat({ signal, ...input }) {
-      const body = await request<Partial<FayzAgentChatResponse>>('/chat', {
-        method: 'POST',
-        body: JSON.stringify(input),
-        signal,
-      })
-      return normalizeResponse(body)
-    },
-
-    async chatStream({ signal, ...input }, callbacks) {
-      const response = await fetcher(`${base}/chat`, {
-        method: 'POST',
-        body: JSON.stringify(input),
-        signal,
-        headers: { ...headers, Accept: 'text/event-stream' },
-      })
-      if (!response.ok) {
-        const body = (await response.json().catch(() => null)) as { error?: string } | null
-        throw new FayzAgentError(body?.error ?? `Agent request failed (${response.status})`, response.status)
-      }
-      // Broker predates streaming (or chose not to): plain JSON round-trip.
-      const contentType = response.headers.get('content-type') ?? ''
-      if (!contentType.includes('text/event-stream') || !response.body) {
-        return normalizeResponse((await response.json()) as Partial<FayzAgentChatResponse>)
-      }
-
-      const reader = response.body.getReader()
-      const decoder = new TextDecoder()
-      let buffer = ''
-      let accumulated = ''
-      let done: Partial<FayzAgentChatResponse> | null = null
-
-      const dispatch = (eventName: string, data: string) => {
-        if (!data) return
-        let payload: Record<string, unknown>
-        try {
-          payload = JSON.parse(data) as Record<string, unknown>
-        } catch {
-          return
-        }
-        if (eventName === 'delta') {
-          const text = typeof payload.text === 'string' ? payload.text : ''
-          if (text) {
-            accumulated += text
-            callbacks?.onDelta?.(accumulated, text)
-          }
-        } else if (eventName === 'done') {
-          done = payload as Partial<FayzAgentChatResponse>
-        } else if (eventName === 'error') {
-          throw new FayzAgentError(
-            typeof payload.error === 'string' ? payload.error : 'Agent stream failed',
-            response.status,
-          )
-        }
-      }
-
-      let eventName = 'message'
-      let dataLines: string[] = []
-      const processLine = (line: string) => {
-        if (line === '') {
-          dispatch(eventName, dataLines.join('\n'))
-          eventName = 'message'
-          dataLines = []
-        } else if (line.startsWith('event:')) {
-          eventName = line.slice(6).trim()
-        } else if (line.startsWith('data:')) {
-          dataLines.push(line.slice(5).trimStart())
-        }
-      }
-
-      for (;;) {
-        const { value, done: streamDone } = await reader.read()
-        if (streamDone) break
-        buffer += decoder.decode(value, { stream: true })
-        let newline = buffer.indexOf('\n')
-        while (newline >= 0) {
-          processLine(buffer.slice(0, newline).replace(/\r$/, ''))
-          buffer = buffer.slice(newline + 1)
-          newline = buffer.indexOf('\n')
-        }
-      }
-      processLine(buffer.replace(/\r$/, ''))
-      processLine('')
-
-      // The final `done` event carries the same payload shape as the JSON
-      // route; accumulated deltas back-fill `content` if the broker omits it.
-      const finalPayload: Partial<FayzAgentChatResponse> = { ...(done ?? {}) }
-      if (!finalPayload.content) finalPayload.content = accumulated
-      return normalizeResponse(finalPayload)
-    },
-
-    async listConversations(externalUserId, signal) {
-      const query = externalUserId ? `?externalUserId=${encodeURIComponent(externalUserId)}` : ''
-      const body = await request<{ conversations?: FayzAgentConversationSummary[] }>(
-        `/conversations${query}`,
-        { method: 'GET', signal },
-      )
-      return body.conversations ?? []
-    },
-
-    async getConversation(conversationId, externalUserId, signal) {
-      const query = externalUserId ? `?externalUserId=${encodeURIComponent(externalUserId)}` : ''
-      const body = await request<{ conversation: FayzAgentConversationDetail }>(
-        `/conversations/${encodeURIComponent(conversationId)}${query}`,
-        { method: 'GET', signal },
-      )
-      return body.conversation
-    },
-  }
-}

package/src/ai-builder.ts

@@ -1,115 +0,0 @@
-// The AI Builder request taxonomy — the contract the platform's request
-// classifier targets. The classifier itself lives in the `fayz` platform repo;
-// this is the canonical source of truth for the request classes and the
-// architecture layer each is allowed to touch (docs/ARCHITECTURE.md).
-
-/** Ownership layer a request may modify. */
-export type FayzLayer = 'app' | 'plugin-config' | 'private-extension' | 'platform' | 'none'
-
-export type AiBuilderRequestClass =
-  | 'app-edit'
-  | 'plugin-config'
-  | 'private-extension'
-  | 'platform-or-plugin-upgrade'
-  | 'unsafe-blocked'
-
-export interface AiBuilderRequestClassDef {
-  id: AiBuilderRequestClass
-  label: string
-  /** Which ownership layer this class is allowed to modify. */
-  layer: FayzLayer
-  /** Who may perform it. */
-  editableBy: 'ai' | 'partner' | 'fayz' | 'none'
-  needsCode: boolean
-  needsDeploy: boolean
-  description: string
-  examples: string[]
-}
-
-export const AI_BUILDER_REQUEST_CLASSES: Record<AiBuilderRequestClass, AiBuilderRequestClassDef> = {
-  'app-edit': {
-    id: 'app-edit',
-    label: 'App edit',
-    layer: 'app',
-    editableBy: 'ai',
-    needsCode: false,
-    needsDeploy: false,
-    description:
-      'Change the generated app: pages, routes, layout, theme, copy, blocks, slots. Manifest-level edits (ladder 1–4) need no code; custom components/pages (ladder 5–6) are app-owned code.',
-    examples: [
-      'Change the brand color and headline',
-      'Add a new landing page with a hero and product grid',
-      'Reorder dashboard cards',
-    ],
-  },
-  'plugin-config': {
-    id: 'plugin-config',
-    label: 'Plugin config',
-    layer: 'plugin-config',
-    editableBy: 'ai',
-    needsCode: false,
-    needsDeploy: false,
-    description:
-      'Configure an installed plugin as manifest data: enabled modules, fields, statuses, rules, feature flags, labels, currency.',
-    examples: [
-      'Enable the reconciliation module in financial',
-      'Add a "VIP" status to clients',
-      'Turn on delivery pricing in the menu',
-    ],
-  },
-  'private-extension': {
-    id: 'private-extension',
-    label: 'Private extension',
-    layer: 'private-extension',
-    editableBy: 'partner',
-    needsCode: true,
-    needsDeploy: true,
-    description:
-      'Add new business behaviour as an app-local plugin (own entities, data, migrations, AI tools, connectors). The sanctioned partner/Silvio path — scaffold with `fayz create plugin`. See CUSTOMIZATION.md.',
-    examples: [
-      'Build a loyalty-points engine with its own table',
-      'Add a custom importer for a legacy ERP',
-      'Integrate a provider Fayz does not support yet (adapter)',
-    ],
-  },
-  'platform-or-plugin-upgrade': {
-    id: 'platform-or-plugin-upgrade',
-    label: 'Platform / plugin upgrade',
-    layer: 'platform',
-    editableBy: 'fayz',
-    needsCode: true,
-    needsDeploy: true,
-    description:
-      'Change owned by Fayz: bump SDK/plugin versions, run manifest/DB migrations, evolve an engine. Not editable from a generated app.',
-    examples: [
-      'Upgrade @fayz-ai/core across the fleet',
-      'Migrate manifests v2 → v3',
-      'Add a capability to an official plugin',
-    ],
-  },
-  'unsafe-blocked': {
-    id: 'unsafe-blocked',
-    label: 'Unsafe / blocked',
-    layer: 'none',
-    editableBy: 'none',
-    needsCode: false,
-    needsDeploy: false,
-    description:
-      'Requests that would break the boundary and must be refused or rerouted: mutating SDK/runtime/plugin internals, forking an SDK page, importing a provider SDK directly into app code, or bypassing tenancy/permissions/security.',
-    examples: [
-      'Edit the code inside @fayz-ai/plugin-crm',
-      'Copy an SDK page into the app and modify it',
-      'Call the Supabase client directly from a storefront component',
-      'Disable row-level security for a tenant',
-    ],
-  },
-}
-
-export const AI_BUILDER_REQUEST_CLASS_IDS = Object.keys(
-  AI_BUILDER_REQUEST_CLASSES,
-) as AiBuilderRequestClass[]
-
-/** True when a request class is permitted (anything but unsafe-blocked). */
-export function isAllowedRequestClass(id: AiBuilderRequestClass): boolean {
-  return id !== 'unsafe-blocked'
-}

package/src/app-params.ts

@@ -1,69 +0,0 @@
-import type { FayzAppParams, FayzRuntimeEnvironment } from './types'
-
-function readSearchParams(): URLSearchParams {
-  const href = globalThis.location?.href
-  return href ? new URL(href).searchParams : new URLSearchParams()
-}
-
-function readMeta(name: string): string | undefined {
-  const documentRef = globalThis.document
-  const value = documentRef?.querySelector<HTMLMetaElement>(`meta[name="${name}"]`)?.content?.trim()
-  return value || undefined
-}
-
-function readEnv(name: string): string | undefined {
-  const env = (import.meta as unknown as { env?: Record<string, string | undefined> }).env
-  return env?.[name]?.trim() || undefined
-}
-
-function firstValue(...values: Array<string | undefined>): string | undefined {
-  return values.find((value) => value && value.trim())?.trim()
-}
-
-function normalizeEnvironment(value?: string): FayzRuntimeEnvironment {
-  return value === 'production' ? 'production' : 'preview'
-}
-
-export function resolveAppParams(): FayzAppParams {
-  const search = readSearchParams()
-  const token = firstValue(
-    search.get('token') ?? undefined,
-    search.get('fayz_token') ?? undefined,
-    readMeta('fayz-token'),
-    readEnv('VITE_FAYZ_TOKEN'),
-  )
-  const appId = firstValue(
-    search.get('appId') ?? undefined,
-    search.get('app_id') ?? undefined,
-    readMeta('fayz-app-id'),
-    readEnv('VITE_FAYZ_APP_ID'),
-  )
-  const projectId = firstValue(
-    search.get('projectId') ?? undefined,
-    search.get('project_id') ?? undefined,
-    readMeta('fayz-project-id'),
-    readEnv('VITE_FAYZ_PROJECT_ID'),
-  )
-  const apiBaseUrl = firstValue(
-    search.get('apiBaseUrl') ?? undefined,
-    search.get('api_base_url') ?? undefined,
-    readMeta('fayz-api-base-url'),
-    readEnv('VITE_FAYZ_API_BASE_URL'),
-    globalThis.location?.origin,
-  ) ?? ''
-  const environment = normalizeEnvironment(firstValue(
-    search.get('environment') ?? undefined,
-    readMeta('fayz-environment'),
-    readEnv('VITE_FAYZ_ENVIRONMENT'),
-  ))
-
-  return {
-    apiBaseUrl,
-    environment,
-    ...(appId ? { appId } : {}),
-    ...(projectId ? { projectId } : {}),
-    ...(token ? { token } : {}),
-  }
-}
-
-export const appParams = resolveAppParams()