dragble-types

Shared TypeScript type definitions for the Dragble Editor — the AI-powered email builder SDK. This is the single source of truth for all public API types used by the framework wrappers:

• dragble-react-editor
• dragble-vue-editor
• dragble-angular-editor

Website | Documentation | Dashboard

Installation

# npm
npm install dragble-types

# yarn
yarn add dragble-types

# pnpm
pnpm add dragble-types

Note: You typically don't need to install this package directly. It's included as a dependency of the framework wrappers (dragble-react-editor, dragble-vue-editor, dragble-angular-editor), and all types are re-exported from those packages.

Usage

Import types directly when you need fine-grained control:

import type {
  DragbleSDK,
  DragbleConfig,
  EditorOptions,
  DesignJson,
  EditorMode,
  ExportHtmlOptions,
  MergeTag,
  MergeTagGroup,
  Module,
  AIConfig,
  AppearanceConfig,
  ToolsConfig,
  FeaturesConfig,
  EditorEventName,
} from "dragble-types";

Or import from a framework wrapper (they re-export everything):

// React
import type { EditorOptions, DesignJson } from "dragble-react-editor";

// Vue
import type { EditorOptions, DesignJson } from "dragble-vue-editor";

// Angular
import type { EditorOptions, DesignJson } from "dragble-angular-editor";

What's Included

This package exports 200+ types covering the entire Dragble Editor SDK surface:

Category	Key Types
Core	EditorMode, ThemeMode, ViewMode, TextDirection, AccentColor, LocaleCode
Configuration	DragbleConfig, EditorOptions, AppearanceConfig, ToolsConfig, FeaturesConfig, AIConfig
Design data	DesignJson, RowData, ColumnData, ContentData, BodyValues
Export	ExportHtmlOptions, ExportImageOptions, ExportImageData, ExportPdfOptions, ExportPdfData, ExportZipOptions, ExportZipData
Merge tags	MergeTag, MergeTagGroup, MergeTagsConfig
Special links	SpecialLink, SpecialLinkGroup, SpecialLinksConfig
Modules	Module, ModuleData, ModuleMetadata, ModuleType
Popup	PopupConfig, PopupValues, PopupPosition, PopupOverlay
Collaboration	CollaborationFeaturesConfig, CommentAction, UserInfo
Custom tools	DragbleToolConfig, DragbleWidgetConfig, CustomToolConfig
Asset storage	ExternalStorageConfig, ExternalAsset, ExternalFolder
Events & callbacks	EditorEventName, DragbleCallbacks
Validation	AuditResult, AuditOptions, ValidatorFunction
MCP	ConnectMCPOptions, ConnectMCPResult, DisconnectMCPResult, MCPConnectErrorCode, MCPStatusResult, MCPToolFiredEvent
SDK interface	DragbleSDK (full interface for all public methods)

Project Structure

dragble-types/
  src/
    index.ts          # All type definitions (single-file source of truth)
  dist/               # Build output (declarations + JS)
  tsconfig.json       # TypeScript configuration

Scripts

Script	Description
npm run build	Compile TypeScript to dist/
npm run clean	Remove the dist/ directory

MCP (Model Context Protocol)

Connect AI clients (OpenCode, Claude Code, Cursor, Windsurf) to a live Dragble editor session.

Types

Type	Description
ConnectMCPOptions	Options for connectMCP() — id (BYOI session ID, required), editorMode
ConnectMCPResult	Result of connectMCP() — sessionId, pairingCode, resumed
DisconnectMCPResult	Result of disconnectMCP() — destroyed (true if PG record permanently deleted)
MCPConnectErrorCode	Error codes: MCP_NOT_AVAILABLE_ON_PLAN, MCP_DISABLED_BY_SDK, INVALID_MCP_SESSION_ID, MCP_ALREADY_CONNECTED, USER_ALREADY_HAS_ACTIVE_SESSION
MCPStatusResult	Current pairing status — { paired: false } or { paired: true, sessionId, mcpServerUrl }
MCPToolFiredEvent	Emitted when an AI client calls a tool — kind + args
GetPairingCodeResult	8-digit pairing code + expiry timestamp
EndPairingResult	Whether an active pairing code was revoked

SDK Methods

// Connect to MCP with a bring-your-own-id session
const result = await sdk.connectMCP({ id: "user-42-doc-99" });

// Check pairing status
const status = await sdk.getMCPStatus();

// Get a new pairing code (rotates the previous one)
const { code, expiresAt } = await sdk.getPairingCode();

// Revoke the active pairing code (session stays alive)
await sdk.endPairing();

// Permanently disconnect and destroy the session (PG + R2 deleted)
const { destroyed } = await sdk.disconnectMCP();

// Listen for AI tool calls in real time
const unsubscribe = sdk.onAIToolFired((event) => {
  console.log(`AI called ${event.kind}`, event.args);
});

Enabling MCP

MCP requires two conditions (dual-gate):

1. Plan allows it — Starter plan or higher (core.mcp in allowed features)
2. SDK opts in — features: { mcp: true } in the SDK config (default is false)

sdk.init({
  id: "editor-container",
  features: { mcp: true },
});

If the plan doesn't include MCP, connectMCP() rejects with MCP_NOT_AVAILABLE_ON_PLAN. If features.mcp is not set to true, connectMCP() rejects with MCP_DISABLED_BY_SDK.

Server-Side Session Termination

SaaS backends can force-destroy a session via HTTP (e.g., when a user's subscription ends):

curl -X DELETE https://mcp.dragble.com/sessions/user-42-doc-99 \
  -H "X-API-Key: db_mcp_your_key_here"

This permanently deletes the session record from the database. The AI client loses connection and cannot reconnect.

Contributing

See CONTRIBUTING.md for guidelines on how to contribute to this project.

License

MIT