puck-plugin-opensource-ai

Plugin de chat AI para o Puck Editor com providers OpenAI e OpenRouter.

Agora com suporte a análise de imagem (URL ou upload no painel), usada como contexto visual para geração/atualização da página.

Instalação

npm install puck-plugin-opensource-ai

Peer dependencies esperadas no projeto consumidor:

• react
• react-dom
• @puckeditor/core

Uso no client (Puck)

import { createAiChatPlugin } from "puck-plugin-opensource-ai";

const aiPlugin = createAiChatPlugin({
  endpoint: "/api/ai/generate",
  provider: "openai", // ou "openrouter"
});

// Exemplo de uso no Puck
// <Puck plugins={[aiPlugin]} config={config} ... />

Tipagem da configuração

type AiProvider = "openai" | "openrouter";

type AiChatPluginOptions = {
  endpoint?: string;
  provider: AiProvider;
  suggestions?: { label: string; prompt: string }[];
  onGenerate?: (data: Data) => void;
};

Análise de imagem no painel

• Você pode colar uma URL de imagem no campo Image URL (optional).
• Ou usar Upload para enviar uma imagem local.
• Ao enviar, o plugin manda imageUrl para o backend como contexto visual.

Segurança (importante)

Não passe API key no client. O plugin chama um endpoint backend (endpoint) e o backend usa as chaves via variáveis de ambiente privadas.

API server-side

No backend, use:

import { generatePuckContent } from "puck-plugin-opensource-ai/server";

A função espera (mínimo):

• prompt: string
• componentDocs: string
• provider: "openai" | "openrouter"

Campos opcionais:

• imageUrl
• currentData
• model
• maxTokens
• unsplashAccessKey
• extraInstructions
• exampleSection
• examplePage
• openaiApiKey e openrouterApiKey (override server-side; normalmente use env)

Variáveis de ambiente

# Para provider=openai
OPENAI_API_KEY=...

# Para provider=openrouter
OPENROUTER_API_KEY=...

# Opcional (se usar sanitização de imagens via busca)
UNSPLASH_ACCESS_KEY=...

Exemplo de endpoint (Next.js App Router)

app/api/ai/generate/route.ts:

import {
  generatePuckContent,
  type AiProvider,
} from "puck-plugin-opensource-ai/server";

export async function POST(req: Request) {
  try {
    const body = await req.json();

    const result = await generatePuckContent({
      prompt: body.prompt,
      imageUrl: body.imageUrl,
      currentData: body.currentData,
      provider: body.provider as AiProvider,
      componentDocs: body.componentDocs, // string com docs dos componentes do seu Puck
      unsplashAccessKey: process.env.UNSPLASH_ACCESS_KEY,
    });

    return Response.json(result, { status: result.error ? 400 : 200 });
  } catch (error: any) {
    return Response.json(
      {
        message: "AI generation failed.",
        error: error?.message || "Unknown error",
      },
      { status: 500 },
    );
  }
}

Exemplo de endpoint (Vite + Express)

server/index.ts:

import express from "express";
import {
  generatePuckContent,
  type AiProvider,
} from "puck-plugin-opensource-ai/server";

const app = express();
app.use(express.json());

app.post("/api/ai/generate", async (req, res) => {
  try {
    const body = req.body;

    const result = await generatePuckContent({
      prompt: body.prompt,
      imageUrl: body.imageUrl,
      currentData: body.currentData,
      provider: body.provider as AiProvider,
      componentDocs: body.componentDocs,
      unsplashAccessKey: process.env.UNSPLASH_ACCESS_KEY,
    });

    res.status(result.error ? 400 : 200).json(result);
  } catch (error: any) {
    res.status(500).json({
      message: "AI generation failed.",
      error: error?.message || "Unknown error",
    });
  }
});

app.listen(3001, () => {
  console.log("AI server running on http://localhost:3001");
});

No client Vite, aponte o endpoint para esse backend (ou configure proxy).

Scripts do pacote

npm run typecheck
npm run build

Troubleshooting

• Missing API key: defina OPENAI_API_KEY ou OPENROUTER_API_KEY no backend.
• Unexpected AI response format: o modelo retornou payload fora do JSON esperado; tente reduzir complexidade do prompt.
• Erros de CORS no Vite: configure proxy (vite.config.ts) ou habilite CORS no backend.
• Para análise de imagem por URL, use uma URL pública acessível pelo provider.