@wakastellar/ui 3.3.3 → 3.5.0

package/src/components/editor/blocks/waka-ai-assist-block.tsx

@@ -0,0 +1,284 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../../utils/cn"
+import type { PlateElementProps } from "../waka-editor-elements"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export const AI_ASSIST_BLOCK_TYPE = "ai_assist" as const
+
+/** Status of the AI request */
+export type AiAssistStatus = "idle" | "loading" | "streaming" | "complete" | "error"
+
+/** Slate node for AI assist blocks */
+export interface AiAssistElement {
+  type: typeof AI_ASSIST_BLOCK_TYPE
+  /** The user's prompt/question */
+  prompt: string
+  /** The AI-generated response */
+  response: string
+  /** Current status */
+  status: AiAssistStatus
+  /** Model used for generation */
+  model?: string
+  /** Timestamp of generation */
+  generatedAt?: string
+  /** Error message if status is "error" */
+  errorMessage?: string
+  /** Token count */
+  tokenCount?: number
+  children: Array<{ text: string }>
+}
+
+export interface WakaAiAssistBlockProps extends PlateElementProps {
+  element?: AiAssistElement & Record<string, unknown>
+  /** Callback to trigger AI generation. Receives the prompt, returns a response or streams it. */
+  onGenerate?: (prompt: string) => Promise<string>
+  /** Callback when the user accepts the response and wants it inserted into the document */
+  onAccept?: (response: string) => void
+  /** Callback when the user discards the response */
+  onDiscard?: () => void
+}
+
+// ============================================================================
+// Status Indicator
+// ============================================================================
+
+function StatusIndicator({ status }: { status: AiAssistStatus }) {
+  const config: Record<AiAssistStatus, { label: string; color: string; pulse: boolean }> = {
+    idle: { label: "Ready", color: "bg-muted-foreground/30", pulse: false },
+    loading: { label: "Thinking...", color: "bg-amber-500", pulse: true },
+    streaming: { label: "Writing...", color: "bg-blue-500", pulse: true },
+    complete: { label: "Complete", color: "bg-emerald-500", pulse: false },
+    error: { label: "Error", color: "bg-destructive", pulse: false },
+  }
+
+  const c = config[status]
+
+  return (
+    <div className="flex items-center gap-1.5">
+      <div className={cn("h-2 w-2 rounded-full", c.color, c.pulse && "animate-pulse")} />
+      <span className="text-[10px] font-medium text-muted-foreground">{c.label}</span>
+    </div>
+  )
+}
+
+// ============================================================================
+// Element Component
+// ============================================================================
+
+/**
+ * WakaAiAssistBlock - A Plate.js block where the user poses a question or prompt,
+ * and the AI response is inserted directly into the document. Supports streaming
+ * responses, accept/discard actions, and model attribution.
+ *
+ * Designed to work with `@platejs/ai` AIChatPlugin, or standalone with a custom
+ * `onGenerate` callback.
+ *
+ * Register in Plate editor:
+ * ```ts
+ * components: {
+ *   [AI_ASSIST_BLOCK_TYPE]: (props) => <WakaAiAssistBlock {...props} onGenerate={myHandler} />,
+ * }
+ * ```
+ */
+export function WakaAiAssistBlock({
+  attributes,
+  children,
+  element,
+  className,
+  onGenerate,
+  onAccept,
+  onDiscard,
+}: WakaAiAssistBlockProps) {
+  const el = element as AiAssistElement | undefined
+  const status = el?.status || "idle"
+  const prompt = el?.prompt || ""
+  const response = el?.response || ""
+
+  return (
+    <div
+      {...attributes}
+      contentEditable={false}
+      className={cn(
+        "my-4 rounded-lg overflow-hidden",
+        "border border-border",
+        "bg-gradient-to-br from-violet-50/30 via-card to-blue-50/30",
+        "dark:from-violet-950/10 dark:via-card dark:to-blue-950/10",
+        "shadow-sm",
+        className
+      )}
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-2.5 border-b border-border/50">
+        <div className="flex items-center gap-2">
+          {/* Sparkle icon */}
+          <div className="relative">
+            <svg
+              className="h-4 w-4 text-violet-600 dark:text-violet-400"
+              viewBox="0 0 24 24"
+              fill="currentColor"
+              aria-hidden="true"
+            >
+              <path d="M12 2L13.09 8.26L18 6L14.74 10.91L21 12L14.74 13.09L18 18L13.09 15.74L12 22L10.91 15.74L6 18L9.26 13.09L3 12L9.26 10.91L6 6L10.91 8.26L12 2Z" />
+            </svg>
+            {(status === "loading" || status === "streaming") && (
+              <div className="absolute inset-0 animate-ping">
+                <svg className="h-4 w-4 text-violet-400/50" viewBox="0 0 24 24" fill="currentColor">
+                  <path d="M12 2L13.09 8.26L18 6L14.74 10.91L21 12L14.74 13.09L18 18L13.09 15.74L12 22L10.91 15.74L6 18L9.26 13.09L3 12L9.26 10.91L6 6L10.91 8.26L12 2Z" />
+                </svg>
+              </div>
+            )}
+          </div>
+          <span className="text-xs font-bold uppercase tracking-wider text-violet-700 dark:text-violet-300">
+            AI Assistant
+          </span>
+          {el?.model && (
+            <span className="text-[10px] font-mono text-muted-foreground bg-muted px-1.5 py-0.5 rounded">
+              {el.model}
+            </span>
+          )}
+        </div>
+
+        <StatusIndicator status={status} />
+      </div>
+
+      {/* Prompt */}
+      <div className="px-4 py-3 border-b border-border/30">
+        <div className="flex items-start gap-2">
+          <div className="flex-shrink-0 mt-0.5 h-5 w-5 rounded-full bg-foreground/10 flex items-center justify-center">
+            <svg className="h-3 w-3 text-foreground/60" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+            </svg>
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-sm text-foreground leading-relaxed">
+              {prompt || <span className="text-muted-foreground italic">Ask the AI assistant a question...</span>}
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {/* Response */}
+      {(response || status === "loading" || status === "streaming") && (
+        <div className="px-4 py-3">
+          <div className="flex items-start gap-2">
+            <div className="flex-shrink-0 mt-0.5 h-5 w-5 rounded-full bg-violet-100 dark:bg-violet-500/20 flex items-center justify-center">
+              <svg className="h-3 w-3 text-violet-600 dark:text-violet-400" viewBox="0 0 24 24" fill="currentColor">
+                <path d="M12 2L13.09 8.26L18 6L14.74 10.91L21 12L14.74 13.09L18 18L13.09 15.74L12 22L10.91 15.74L6 18L9.26 13.09L3 12L9.26 10.91L6 6L10.91 8.26L12 2Z" />
+              </svg>
+            </div>
+            <div className="flex-1 min-w-0">
+              {status === "loading" && !response ? (
+                <div className="space-y-2">
+                  <div className="h-3 w-3/4 bg-muted rounded animate-pulse" />
+                  <div className="h-3 w-1/2 bg-muted rounded animate-pulse" />
+                  <div className="h-3 w-5/6 bg-muted rounded animate-pulse" />
+                </div>
+              ) : (
+                <div className="text-sm text-foreground leading-relaxed whitespace-pre-wrap prose prose-sm dark:prose-invert max-w-none">
+                  {response}
+                  {status === "streaming" && (
+                    <span className="inline-block w-1.5 h-4 bg-violet-500 ml-0.5 animate-pulse rounded-sm" />
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Error */}
+      {status === "error" && el?.errorMessage && (
+        <div className="mx-4 mb-3 px-3 py-2 rounded-md bg-destructive/10 border border-destructive/20">
+          <p className="text-xs text-destructive">{el.errorMessage}</p>
+        </div>
+      )}
+
+      {/* Actions */}
+      {status === "complete" && response && (
+        <div className="flex items-center justify-between px-4 py-2 border-t border-border/50 bg-muted/20">
+          <div className="flex items-center gap-2 text-[10px] text-muted-foreground">
+            {el?.tokenCount && <span>{el.tokenCount} tokens</span>}
+            {el?.generatedAt && (
+              <span>
+                {new Date(el.generatedAt).toLocaleTimeString("fr-FR", { hour: "2-digit", minute: "2-digit" })}
+              </span>
+            )}
+          </div>
+          <div className="flex items-center gap-2">
+            {onDiscard && (
+              <button
+                type="button"
+                onClick={onDiscard}
+                className="px-3 py-1 rounded text-xs font-medium text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
+              >
+                Discard
+              </button>
+            )}
+            {onAccept && (
+              <button
+                type="button"
+                onClick={() => onAccept(response)}
+                className="px-3 py-1 rounded text-xs font-medium bg-primary text-primary-foreground hover:bg-primary/90 transition-colors shadow-sm"
+              >
+                Insert into document
+              </button>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Hidden Slate children */}
+      <div className="hidden">{children}</div>
+    </div>
+  )
+}
+
+WakaAiAssistBlock.displayName = "WakaAiAssistBlock"
+
+// ============================================================================
+// Node Factory
+// ============================================================================
+
+export function createAiAssistNodes(options?: {
+  prompt?: string
+  model?: string
+}): AiAssistElement[] {
+  return [
+    {
+      type: AI_ASSIST_BLOCK_TYPE,
+      prompt: options?.prompt || "",
+      response: "",
+      status: "idle",
+      model: options?.model || "claude-sonnet-4-20250514",
+      children: [{ text: "" }],
+    },
+  ]
+}
+
+export async function createAiAssistPlugin(
+  onGenerate?: (prompt: string) => Promise<string>,
+  onAccept?: (response: string) => void,
+) {
+  try {
+    const { createPlatePlugin } = await import("platejs/react")
+    return createPlatePlugin({
+      key: AI_ASSIST_BLOCK_TYPE,
+      node: {
+        isElement: true,
+        isVoid: true,
+        type: AI_ASSIST_BLOCK_TYPE,
+        component: (props: WakaAiAssistBlockProps) => (
+          <WakaAiAssistBlock {...props} onGenerate={onGenerate} onAccept={onAccept} />
+        ),
+      },
+    })
+  } catch {
+    console.warn("[WakaAiAssistBlock] platejs not installed")
+    return null
+  }
+}

package/src/components/editor/blocks/waka-api-endpoint-block.tsx

@@ -0,0 +1,382 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../../utils/cn"
+import type { PlateElementProps } from "../waka-editor-elements"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export const API_ENDPOINT_BLOCK_TYPE = "api_endpoint" as const
+
+/** HTTP method type */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS"
+
+/** A single parameter/header definition */
+export interface ApiParam {
+  name: string
+  type: string
+  required: boolean
+  description: string
+}
+
+/** A response definition */
+export interface ApiResponse {
+  status: number
+  description: string
+  body?: string
+}
+
+/** Slate node for API endpoint block */
+export interface ApiEndpointElement {
+  type: typeof API_ENDPOINT_BLOCK_TYPE
+  /** HTTP method */
+  method: HttpMethod
+  /** Route path (e.g. "/api/v1/projects/:id") */
+  route: string
+  /** Endpoint description */
+  description: string
+  /** Authentication requirement */
+  auth: string
+  /** Required permissions/roles */
+  permissions: string[]
+  /** Rate limit description */
+  rateLimit?: string
+  /** Path/query parameters */
+  params?: ApiParam[]
+  /** Request body (JSON string) */
+  requestBody?: string
+  /** Response definitions */
+  responses: ApiResponse[]
+  children: Array<{ text: string }>
+}
+
+export interface WakaApiEndpointBlockProps extends PlateElementProps {
+  element?: ApiEndpointElement & Record<string, unknown>
+}
+
+// ============================================================================
+// Method Badge
+// ============================================================================
+
+const METHOD_COLORS: Record<HttpMethod, { bg: string; text: string; border: string }> = {
+  GET: { bg: "bg-emerald-100 dark:bg-emerald-500/15", text: "text-emerald-700 dark:text-emerald-400", border: "border-emerald-300 dark:border-emerald-600/40" },
+  POST: { bg: "bg-blue-100 dark:bg-blue-500/15", text: "text-blue-700 dark:text-blue-400", border: "border-blue-300 dark:border-blue-600/40" },
+  PUT: { bg: "bg-amber-100 dark:bg-amber-500/15", text: "text-amber-700 dark:text-amber-400", border: "border-amber-300 dark:border-amber-600/40" },
+  PATCH: { bg: "bg-orange-100 dark:bg-orange-500/15", text: "text-orange-700 dark:text-orange-400", border: "border-orange-300 dark:border-orange-600/40" },
+  DELETE: { bg: "bg-red-100 dark:bg-red-500/15", text: "text-red-700 dark:text-red-400", border: "border-red-300 dark:border-red-600/40" },
+  HEAD: { bg: "bg-gray-100 dark:bg-gray-500/15", text: "text-gray-700 dark:text-gray-400", border: "border-gray-300 dark:border-gray-600/40" },
+  OPTIONS: { bg: "bg-purple-100 dark:bg-purple-500/15", text: "text-purple-700 dark:text-purple-400", border: "border-purple-300 dark:border-purple-600/40" },
+}
+
+function MethodBadge({ method }: { method: HttpMethod }) {
+  const colors = METHOD_COLORS[method] || METHOD_COLORS.GET
+  return (
+    <span className={cn(
+      "inline-flex items-center px-2 py-0.5 rounded text-[11px] font-bold font-mono tracking-wide border",
+      colors.bg, colors.text, colors.border
+    )}>
+      {method}
+    </span>
+  )
+}
+
+// ============================================================================
+// Status Badge
+// ============================================================================
+
+function StatusBadge({ status }: { status: number }) {
+  const color = status < 300
+    ? "text-emerald-700 dark:text-emerald-400 bg-emerald-50 dark:bg-emerald-500/10"
+    : status < 400
+      ? "text-blue-700 dark:text-blue-400 bg-blue-50 dark:bg-blue-500/10"
+      : status < 500
+        ? "text-amber-700 dark:text-amber-400 bg-amber-50 dark:bg-amber-500/10"
+        : "text-red-700 dark:text-red-400 bg-red-50 dark:bg-red-500/10"
+
+  return (
+    <span className={cn("text-[11px] font-mono font-bold px-1.5 py-0.5 rounded", color)}>
+      {status}
+    </span>
+  )
+}
+
+// ============================================================================
+// JSON Code Block
+// ============================================================================
+
+function CodePreview({ code, label }: { code: string; label: string }) {
+  const [expanded, setExpanded] = React.useState(false)
+  const lines = code.split("\n")
+  const isLong = lines.length > 6
+
+  return (
+    <div className="mt-2">
+      <div className="flex items-center justify-between mb-1">
+        <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+          {label}
+        </span>
+        {isLong && (
+          <button
+            type="button"
+            onClick={() => setExpanded(!expanded)}
+            className="text-[10px] text-primary hover:underline"
+          >
+            {expanded ? "Collapse" : "Expand"}
+          </button>
+        )}
+      </div>
+      <pre className={cn(
+        "text-[12px] font-mono leading-relaxed p-3 rounded-md overflow-x-auto",
+        "bg-gray-950 dark:bg-gray-900 text-gray-100",
+        "border border-gray-800/50",
+        !expanded && isLong && "max-h-[150px] overflow-hidden relative"
+      )}>
+        {!expanded && isLong && (
+          <div className="absolute bottom-0 left-0 right-0 h-10 bg-gradient-to-t from-gray-950 dark:from-gray-900 to-transparent" />
+        )}
+        <code>{code}</code>
+      </pre>
+    </div>
+  )
+}
+
+// ============================================================================
+// Element Component
+// ============================================================================
+
+/**
+ * WakaApiEndpointBlock - A Plate.js block for documenting REST API endpoints.
+ * Displays method, route, parameters, request body, and responses with
+ * syntax-colored JSON previews.
+ *
+ * Register in Plate editor:
+ * ```ts
+ * components: {
+ *   [API_ENDPOINT_BLOCK_TYPE]: WakaApiEndpointBlock,
+ * }
+ * ```
+ */
+export function WakaApiEndpointBlock({
+  attributes,
+  children,
+  element,
+  className,
+}: WakaApiEndpointBlockProps) {
+  const el = element as ApiEndpointElement | undefined
+  const method = el?.method || "GET"
+  const route = el?.route || "/api/v1/resource"
+  const methodColors = METHOD_COLORS[method] || METHOD_COLORS.GET
+
+  const [activeTab, setActiveTab] = React.useState<"params" | "body" | "responses">(
+    el?.params && el.params.length > 0 ? "params" : el?.requestBody ? "body" : "responses"
+  )
+
+  return (
+    <div
+      {...attributes}
+      contentEditable={false}
+      className={cn(
+        "my-4 rounded-lg overflow-hidden",
+        "border",
+        methodColors.border,
+        "shadow-sm",
+        className
+      )}
+    >
+      {/* Method + Route header */}
+      <div className={cn(
+        "flex items-center gap-3 px-4 py-3",
+        methodColors.bg
+      )}>
+        <MethodBadge method={method} />
+        <code className={cn("text-sm font-mono font-semibold", methodColors.text)}>
+          {route}
+        </code>
+      </div>
+
+      {/* Description + meta */}
+      <div className="px-4 py-3 border-b border-border/50 bg-card/50">
+        {el?.description && (
+          <p className="text-sm text-foreground mb-2">{el.description}</p>
+        )}
+
+        <div className="flex flex-wrap gap-3 text-[11px]">
+          {el?.auth && (
+            <div className="flex items-center gap-1 text-muted-foreground">
+              <svg className="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
+              </svg>
+              <span className="font-medium">{el.auth}</span>
+            </div>
+          )}
+
+          {el?.permissions && el.permissions.length > 0 && (
+            <div className="flex items-center gap-1">
+              <svg className="h-3 w-3 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z" />
+              </svg>
+              {el.permissions.map((perm, i) => (
+                <span key={i} className="px-1.5 py-0.5 rounded bg-muted text-muted-foreground font-mono text-[10px]">
+                  {perm}
+                </span>
+              ))}
+            </div>
+          )}
+
+          {el?.rateLimit && (
+            <div className="flex items-center gap-1 text-muted-foreground">
+              <svg className="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+              </svg>
+              <span className="font-medium">{el.rateLimit}</span>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Tabs */}
+      <div className="flex border-b border-border/50">
+        {[
+          { id: "params" as const, label: "Parameters", count: el?.params?.length },
+          { id: "body" as const, label: "Request Body", show: !!el?.requestBody },
+          { id: "responses" as const, label: "Responses", count: el?.responses?.length },
+        ].filter((tab) => tab.show !== false && (tab.count === undefined || tab.count > 0)).map((tab) => (
+          <button
+            key={tab.id}
+            type="button"
+            onClick={() => setActiveTab(tab.id)}
+            className={cn(
+              "px-4 py-2 text-xs font-medium transition-colors relative",
+              activeTab === tab.id
+                ? "text-foreground"
+                : "text-muted-foreground hover:text-foreground"
+            )}
+          >
+            {tab.label}
+            {tab.count !== undefined && (
+              <span className="ml-1 text-[10px] text-muted-foreground">({tab.count})</span>
+            )}
+            {activeTab === tab.id && (
+              <div className={cn("absolute bottom-0 left-0 right-0 h-0.5", methodColors.bg.replace("bg-", "bg-").replace("/15", ""))} style={{ backgroundColor: method === "GET" ? "#10b981" : method === "POST" ? "#3b82f6" : method === "PUT" ? "#f59e0b" : method === "DELETE" ? "#ef4444" : "#6b7280" }} />
+            )}
+          </button>
+        ))}
+      </div>
+
+      {/* Tab content */}
+      <div className="px-4 py-3">
+        {/* Parameters tab */}
+        {activeTab === "params" && el?.params && el.params.length > 0 && (
+          <div className="overflow-x-auto">
+            <table className="w-full text-xs">
+              <thead>
+                <tr className="border-b border-border">
+                  <th className="text-left font-semibold text-muted-foreground py-1.5 pr-4">Name</th>
+                  <th className="text-left font-semibold text-muted-foreground py-1.5 pr-4">Type</th>
+                  <th className="text-left font-semibold text-muted-foreground py-1.5 pr-4">Required</th>
+                  <th className="text-left font-semibold text-muted-foreground py-1.5">Description</th>
+                </tr>
+              </thead>
+              <tbody>
+                {el.params.map((param, i) => (
+                  <tr key={i} className="border-b border-border/30">
+                    <td className="py-1.5 pr-4 font-mono font-medium text-foreground">{param.name}</td>
+                    <td className="py-1.5 pr-4 font-mono text-muted-foreground">{param.type}</td>
+                    <td className="py-1.5 pr-4">
+                      {param.required ? (
+                        <span className="text-red-600 dark:text-red-400 font-semibold">required</span>
+                      ) : (
+                        <span className="text-muted-foreground">optional</span>
+                      )}
+                    </td>
+                    <td className="py-1.5 text-muted-foreground">{param.description}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+
+        {/* Request body tab */}
+        {activeTab === "body" && el?.requestBody && (
+          <CodePreview code={el.requestBody} label="Request Body" />
+        )}
+
+        {/* Responses tab */}
+        {activeTab === "responses" && el?.responses && (
+          <div className="space-y-3">
+            {el.responses.map((resp, i) => (
+              <div key={i}>
+                <div className="flex items-center gap-2 mb-1">
+                  <StatusBadge status={resp.status} />
+                  <span className="text-xs text-muted-foreground">{resp.description}</span>
+                </div>
+                {resp.body && <CodePreview code={resp.body} label={`Response ${resp.status}`} />}
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Hidden Slate children */}
+      <div className="hidden">{children}</div>
+    </div>
+  )
+}
+
+WakaApiEndpointBlock.displayName = "WakaApiEndpointBlock"
+
+// ============================================================================
+// Node Factory
+// ============================================================================
+
+export function createApiEndpointNodes(options?: Partial<Omit<ApiEndpointElement, "type" | "children">>): ApiEndpointElement[] {
+  return [
+    {
+      type: API_ENDPOINT_BLOCK_TYPE,
+      method: options?.method || "GET",
+      route: options?.route || "/api/v1/resource/:id",
+      description: options?.description || "Retrieves a resource by its unique identifier.",
+      auth: options?.auth || "Bearer JWT",
+      permissions: options?.permissions || ["ROLE_USER"],
+      rateLimit: options?.rateLimit || "100 req/min",
+      params: options?.params || [
+        { name: "id", type: "UUID", required: true, description: "Resource unique identifier" },
+      ],
+      requestBody: options?.requestBody,
+      responses: options?.responses || [
+        {
+          status: 200,
+          description: "Success",
+          body: '{\n  "data": {\n    "id": "uuid",\n    "name": "Example",\n    "createdAt": "2026-04-14T00:00:00Z"\n  }\n}',
+        },
+        {
+          status: 404,
+          description: "Resource not found",
+          body: '{\n  "error": "NOT_FOUND",\n  "message": "Resource not found"\n}',
+        },
+      ],
+      children: [{ text: "" }],
+    },
+  ]
+}
+
+export async function createApiEndpointPlugin() {
+  try {
+    const { createPlatePlugin } = await import("platejs/react")
+    return createPlatePlugin({
+      key: API_ENDPOINT_BLOCK_TYPE,
+      node: {
+        isElement: true,
+        isVoid: true,
+        type: API_ENDPOINT_BLOCK_TYPE,
+        component: WakaApiEndpointBlock,
+      },
+    })
+  } catch {
+    console.warn("[WakaApiEndpointBlock] platejs not installed")
+    return null
+  }
+}