Hype Dash
Production-ready TypeScript SDK for creating and managing Lark/Feishu dashboards via REST API with Model Context Protocol (MCP) server support.
Features
- Type-Safe: Full TypeScript support with comprehensive type definitions
- Fluent API: Intuitive builder pattern for creating dashboard blocks
- 7 Block Types: Charts, Metrics, Views, Text, Lists, Tab Pages, and Filters
- MCP Server: Native Claude Code integration via Model Context Protocol
- Production Ready: Error handling, retries, logging, and validation
- Batch Operations: Efficiently create multiple blocks at once
- 2025 Dashboard Features: Latest Lark dashboard capabilities
- Python SDK: Comprehensive Python SDK for Lark Base data management
Installation
TypeScript/JavaScript
npm install @hypelab/hype-dash
Python
cd python
pip install -r requirements.txt
See Python SDK Documentation for detailed setup and usage.
Quick Start
Basic Usage
import { LarkDashboardClient, ChartBlockBuilder, AggregationType } from '@hypelab/hype-dash';
const client = new LarkDashboardClient({
apiKey: process.env.LARK_API_KEY!,
region: 'sg', // 'sg' | 'cn' | 'us'
logging: true,
});
// Create a dashboard
const dashboardId = await client.createDashboard({
name: 'Sales Dashboard',
appToken: 'YOUR_APP_TOKEN',
});
// Add a bar chart
const chartBlock = ChartBlockBuilder.bar()
.dataSource('YOUR_APP_TOKEN', 'YOUR_TABLE_ID')
.xAxis({ fieldName: 'Category' })
.yAxis([{ fieldName: 'Revenue', aggregation: AggregationType.SUM }])
.title('Revenue by Category')
.colors(['#3b82f6', '#10b981', '#f59e0b'])
.build();
await client.addBlock('YOUR_APP_TOKEN', dashboardId, chartBlock);
Available Block Types
1. Chart Blocks
import { ChartBlockBuilder, ChartType, AggregationType } from '@hypelab/hype-dash';
// Bar Chart
const barChart = ChartBlockBuilder.bar()
.dataSource(appToken, tableId)
.xAxis({ fieldName: 'Month' })
.yAxis([
{ fieldName: 'Sales', aggregation: AggregationType.SUM, label: 'Total Sales' },
{ fieldName: 'Orders', aggregation: AggregationType.COUNT, label: 'Order Count' }
])
.title('Monthly Sales Performance')
.showLegend(true)
.build();
// Line Chart
const lineChart = ChartBlockBuilder.line()
.dataSource(appToken, tableId)
.xAxis({ fieldName: 'Date' })
.yAxis([{ fieldName: 'Revenue', aggregation: AggregationType.SUM }])
.build();
// Pie Chart
const pieChart = ChartBlockBuilder.pie()
.dataSource(appToken, tableId)
.series({ fieldName: 'Category' })
.yAxis([{ fieldName: 'Amount', aggregation: AggregationType.SUM }])
.build();
2. Metrics Blocks
import { MetricsBlockBuilder, AggregationType } from '@hypelab/hype-dash';
const metrics = new MetricsBlockBuilder()
.dataSource(appToken, tableId)
.fieldName('Revenue')
.aggregation(AggregationType.SUM)
.title('Total Revenue')
.prefix('$')
.decimals(2)
.trendComparison(30, 'days')
.build();
3. View Blocks
import { ViewBlockBuilder, ViewType } from '@hypelab/hype-dash';
const tableView = ViewBlockBuilder.table()
.dataSource(appToken, tableId, viewId)
.title('Customer List')
.showToolbar(true)
.height(400)
.build();
const kanbanView = ViewBlockBuilder.kanban()
.dataSource(appToken, tableId, viewId)
.build();
4. Text Blocks
import { TextBlockBuilder } from '@hypelab/hype-dash';
const heading = new TextBlockBuilder()
.heading('Dashboard Overview')
.alignment('center')
.build();
const paragraph = new TextBlockBuilder()
.paragraph('Welcome to the sales dashboard.')
.build();
MCP Server Usage
The SDK includes a Model Context Protocol server for Claude Code integration.
Setup
Add to your ~/.claude.json or Claude Code configuration:
{
"mcpServers": {
"hype-dash": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@hypelab/hype-dash"],
"env": {
"LARK_API_KEY": "your-api-key-here",
"LARK_REGION": "sg"
}
}
}
}
Available MCP Tools
create_dashboard- Create a new dashboardcreate_chart_block- Add chart visualizationscreate_metrics_block- Add KPI metricscreate_view_block- Add table/kanban viewscreate_text_block- Add text contentlist_dashboards- List all dashboardsdelete_dashboard- Remove dashboards
Usage with Claude Code
Create a sales dashboard with:
- Bar chart showing revenue by month
- KPI card for total revenue
- Table view of recent orders
Claude will use the MCP tools to create the dashboard automatically.
Python SDK
The project includes a comprehensive Python SDK for managing Lark Base data. This allows you to:
- Sync External Data: Import data from TikTok Ads, databases, APIs, etc.
- Batch Operations: Efficiently create/update thousands of records
- Data Transformation: Transform and validate data before loading
- Automatic Dashboard Updates: Dashboards automatically reflect data changes
Quick Example
from lark_client import LarkBaseClient, LarkConfig
from data_manager import DataManager
# Initialize client
config = LarkConfig(
app_id=os.getenv('LARK_APP_ID'),
app_secret=os.getenv('LARK_APP_SECRET')
)
client = LarkBaseClient(config)
data_manager = DataManager(client)
# Sync TikTok campaign data
tiktok_data = fetch_tiktok_campaigns() # Your data source
result = data_manager.batch_upsert_records(
app_token='YOUR_APP_TOKEN',
table_id='YOUR_TABLE_ID',
records=tiktok_data,
key_field='campaign_id'
)
print(f"Synced {result['total']} campaigns")
# Your dashboards now show updated data automatically!
Python SDK Features
- Full CRUD operations for tables, fields, and records
- Batch operations with automatic pagination
- Data validation and transformation utilities
- Incremental sync with timestamp tracking
- Field mapping for external data sources
- Rate limiting and error handling
- Comprehensive logging
See Python SDK Documentation for complete guide.
Workflow: Python + TypeScript
- Python: Manage data (create tables, sync external sources, batch updates)
- TypeScript: Create beautiful dashboards to visualize the data
- Automatic: Dashboards update automatically when data changes
# 1. Python: Sync data
data_manager.batch_upsert_records(...)
// 2. TypeScript: Create dashboard
const chart = ChartBlockBuilder.bar()
.dataSource(appToken, tableId)
.build();
Configuration
Client Options
const client = new LarkDashboardClient({
apiKey: string; // Required: Lark API key
region?: 'sg' | 'cn' | 'us'; // Default: 'sg'
apiUrl?: string; // Optional: Custom API URL
logging?: boolean; // Default: false
timeout?: number; // Default: 30000ms
maxRetries?: number; // Default: 3
retryDelay?: number; // Default: 1000ms
});
Environment Variables
LARK_API_KEY=your-api-key
LARK_REGION=sg
LARK_LOGGING=true
Advanced Features
Batch Operations
const blocks = [
ChartBlockBuilder.bar().dataSource(appToken, tableId).build(),
MetricsBlockBuilder.sum('Revenue').dataSource(appToken, tableId).build(),
ViewBlockBuilder.table().dataSource(appToken, tableId, viewId).build(),
];
const results = await client.batchCreateBlocks(appToken, blocks);
Filtering
import { FilterOperator, FilterConjunction } from '@hypelab/hype-dash';
const chart = ChartBlockBuilder.bar()
.dataSource(appToken, tableId)
.filters(FilterConjunction.AND, [
{ fieldName: 'Status', operator: FilterOperator.IS, value: 'Active' },
{ fieldName: 'Revenue', operator: FilterOperator.GT, value: 1000 }
])
.build();
Error Handling
import { ValidationError } from '@hypelab/hype-dash';
try {
await client.addBlock(appToken, dashboardId, block);
} catch (error) {
if (error instanceof ValidationError) {
console.error('Validation failed:', error.message);
} else {
console.error('API error:', error);
}
}
API Reference
LarkDashboardClient
createDashboard(dashboard: Dashboard): Promise<string>addBlock(appToken: string, dashboardId: string, block: DashboardBlock): Promise<string>updateBlock(appToken: string, blockId: string, block: Partial<DashboardBlock>): Promise<void>deleteBlock(appToken: string, blockId: string): Promise<void>listBlocks(appToken: string): Promise<DashboardBlock[]>batchCreateBlocks(appToken: string, blocks: DashboardBlock[]): Promise<BatchOperationResult[]>
Builders
ChartBlockBuilder- Create chart visualizationsMetricsBlockBuilder- Create KPI metricsViewBlockBuilder- Create data viewsTextBlockBuilder- Create text blocksListBlockBuilder- Create list blocks (2025)TabPageBlockBuilder- Create tab pages (2025)
Examples
See the /examples directory for complete examples:
basic-dashboard.ts- Simple dashboard creationcomplete-dashboard.ts- Full-featured dashboardmulti-source-dashboard.ts- Multiple data sourcesrealtime-dashboard.ts- Real-time data updates
TypeScript Support
The SDK is written in TypeScript and provides comprehensive type definitions:
import type {
DashboardBlock,
ChartConfig,
MetricsConfig,
ViewConfig,
ChartType,
ViewType,
AggregationType,
} from '@hypelab/hype-dash';
Requirements
TypeScript/JavaScript
- Node.js >= 16.0.0
- TypeScript >= 5.0.0 (for TypeScript projects)
Python
- Python >= 3.8
- See python/requirements.txt for dependencies
Troubleshooting
Common Issues
Authentication Errors
- Verify your LARK_API_KEY is correct
- Check API key permissions in Lark admin console
- Ensure region matches your Lark workspace ('sg', 'cn', or 'us')
Network Errors
- Check firewall settings
- Verify network connectivity to Lark API
- Try increasing timeout in client config
Validation Errors
- Ensure required fields are provided
- Check data types match API expectations
- Verify field names exist in your Lark tables
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE file for details.
Support
- GitHub Issues: https://github.com/hypelab/hype-dash/issues
- Email: dev@hypelab.com
Changelog
See CHANGELOG.md for version history and updates.