@entrinsik/vite-plugin-informer 1.0.0

package/templates/skill/references/api-reference.md

@@ -0,0 +1,242 @@
+# API Quick Reference
+
+All endpoints are relative to `/api`. The Vite plugin handles authentication in dev mode.
+
+## Datasets
+
+### GET /api/datasets-list
+List all datasets the user can access.
+
+```javascript
+const datasets = await fetch('/api/datasets-list').then(r => r.json());
+// [{ id, name, description, records, size, tags, sharing }, ...]
+```
+
+### POST /api/datasets/{id}/_search
+Query dataset data using Elasticsearch DSL.
+
+```javascript
+const result = await fetch(`/api/datasets/${id}/_search`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        query: { match_all: {} },
+        size: 100,
+        from: 0,
+        _source: ['field1', 'field2'],
+        sort: [{ field1: 'desc' }],
+        aggs: { total: { sum: { field: 'amount' } } }
+    })
+}).then(r => r.json());
+
+// result.hits.total - count
+// result.hits.hits - [{ _source: { ... } }, ...]
+// result.aggregations - { total: { value: 12345 } }
+```
+
+**Query patterns:**
+```javascript
+// All records
+{ query: { match_all: {} } }
+
+// Exact match
+{ query: { bool: { filter: [{ term: { status: 'active' } }] } } }
+
+// Range
+{ query: { bool: { filter: [{ range: { amount: { gte: 1000 } } }] } } }
+
+// Date range
+{ query: { bool: { filter: [{ range: { date: { gte: '2024-01-01', lte: '2024-12-31' } } }] } } }
+
+// Multiple filters
+{ query: { bool: { filter: [
+    { term: { region: 'North' } },
+    { range: { amount: { gte: 1000 } } }
+] } } }
+
+// Text search
+{ query: { bool: { must: [{ match: { name: 'search text' } }] } } }
+```
+
+**Aggregation patterns:**
+```javascript
+// Metrics
+{ aggs: { total: { sum: { field: 'amount' } } } }
+{ aggs: { average: { avg: { field: 'amount' } } } }
+{ aggs: { minimum: { min: { field: 'amount' } } } }
+{ aggs: { maximum: { max: { field: 'amount' } } } }
+{ aggs: { count: { value_count: { field: 'id' } } } }
+{ aggs: { unique: { cardinality: { field: 'customer' } } } }
+
+// Group by
+{ aggs: { by_status: { terms: { field: 'status', size: 50 } } } }
+
+// Group with metric
+{ aggs: {
+    by_region: {
+        terms: { field: 'region', size: 50 },
+        aggs: { total: { sum: { field: 'amount' } } }
+    }
+} }
+
+// Date histogram
+{ aggs: {
+    by_month: {
+        date_histogram: { field: 'date', calendar_interval: 'month' },
+        aggs: { total: { sum: { field: 'amount' } } }
+    }
+} }
+```
+
+## Queries
+
+### GET /api/queries-list
+List saved queries.
+
+```javascript
+const queries = await fetch('/api/queries-list').then(r => r.json());
+// [{ id, name, description, tags, sharing }, ...]
+```
+
+### POST /api/queries/{id}/_execute
+Execute a saved query.
+
+```javascript
+const result = await fetch(`/api/queries/${id}/_execute`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        parameters: { startDate: '2024-01-01' }
+    })
+}).then(r => r.json());
+```
+
+## Integrations
+
+### GET /api/integrations
+List configured integrations.
+
+```javascript
+const result = await fetch('/api/integrations').then(r => r.json());
+// result.items = [{ id, name, slug, type, description }, ...]
+```
+
+### POST /api/integrations/{id}/request
+Make an authenticated request through an integration.
+
+```javascript
+const result = await fetch(`/api/integrations/${slugOrId}/request`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        url: '/path/to/endpoint',
+        method: 'GET',              // GET, POST, PUT, PATCH, DELETE
+        params: { key: 'value' },   // Query parameters
+        data: { key: 'value' },     // Request body (POST/PUT/PATCH)
+        headers: {}                 // Additional headers
+    })
+}).then(r => r.json());
+
+// result.status - HTTP status
+// result.data - Response body
+// result.error - true if error status
+```
+
+**Salesforce examples:**
+
+```javascript
+// SOQL query
+await fetch('/api/integrations/salesforce/request', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        url: '/data/v59.0/query',
+        method: 'GET',
+        params: { q: "SELECT Id, Name FROM Account LIMIT 10" }
+    })
+});
+
+// Get record
+await fetch('/api/integrations/salesforce/request', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        url: '/data/v59.0/sobjects/Account/001xxxxxxxxxxxx',
+        method: 'GET'
+    })
+});
+
+// Create record
+await fetch('/api/integrations/salesforce/request', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        url: '/data/v59.0/sobjects/Contact',
+        method: 'POST',
+        data: { FirstName: 'John', LastName: 'Doe', Email: 'john@example.com' }
+    })
+});
+```
+
+## Data Access Configuration
+
+Create `data-access.yaml` in your project root to declare which APIs your report needs. Without this file, all API access is blocked when published.
+
+```yaml
+# data-access.yaml
+
+datasets:
+  - admin:sales-data
+
+queries:
+  - admin:summary
+
+integrations:
+  - salesforce
+```
+
+### Row-Level Security
+
+```yaml
+datasets:
+  - id: admin:orders
+    filter:
+      region: $user.custom.region
+      owner: $user.username
+```
+
+### Integration Credentials
+
+```yaml
+integrations:
+  - id: partner-api
+    headers:
+      Authorization: Bearer $user.custom.apiToken
+    params:
+      tenant: $tenant.id
+```
+
+### Variables
+
+- `$user.username`, `$user.email`, `$user.displayName`
+- `$user.custom.xxx` - Custom user fields
+- `$tenant.id`
+- `$report.id`, `$report.name`
+
+## Error Handling
+
+API errors return:
+```javascript
+{
+    statusCode: 400,
+    error: 'Bad Request',
+    message: 'Description of error'
+}
+```
+
+Common status codes:
+- `400` - Bad request / validation error
+- `401` - Not authenticated
+- `403` - Not authorized
+- `404` - Not found
+- `502` - Upstream error (integration request failed)

package/templates/skill/references/report-templates.md

@@ -0,0 +1,299 @@
+# Report Templates
+
+## Minimal Starter
+
+### index.html
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Report</title>
+    <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+    <div id="app">
+        <h1>Report Title</h1>
+        <div id="content"></div>
+    </div>
+    <script type="module" src="main.js"></script>
+</body>
+</html>
+```
+
+### styles.css
+```css
+* { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+    font-family: system-ui, sans-serif;
+    background: #0f172a;
+    color: #f1f5f9;
+    padding: 24px;
+}
+
+#app {
+    max-width: 1200px;
+    margin: 0 auto;
+}
+
+h1 {
+    font-size: 24px;
+    margin-bottom: 24px;
+}
+```
+
+### main.js
+```javascript
+window.informerReady = false;
+
+async function init() {
+    // List available datasets
+    const datasets = await fetch('/api/datasets-list').then(r => r.json());
+    console.log('Available datasets:', datasets);
+
+    // Query a dataset
+    if (datasets.length > 0) {
+        const result = await fetch(`/api/datasets/${datasets[0].id}/_search`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ query: { match_all: {} }, size: 10 })
+        }).then(r => r.json());
+
+        const records = result.hits.hits.map(h => h._source);
+        console.log('Records:', records);
+
+        // Render your content here
+        document.getElementById('content').innerHTML = `
+            <p>Found ${result.hits.total} records</p>
+            <pre>${JSON.stringify(records, null, 2)}</pre>
+        `;
+    }
+
+    window.informerReady = true;
+}
+
+init();
+```
+
+## Dashboard Layout
+
+### index.html
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Dashboard</title>
+    <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+    <div class="dashboard">
+        <header>
+            <h1>Dashboard Title</h1>
+            <p class="subtitle">Description of this dashboard</p>
+        </header>
+
+        <div class="metrics">
+            <div class="metric-card">
+                <span class="metric-value" id="metric1">--</span>
+                <span class="metric-label">Metric 1</span>
+            </div>
+            <div class="metric-card">
+                <span class="metric-value" id="metric2">--</span>
+                <span class="metric-label">Metric 2</span>
+            </div>
+            <div class="metric-card">
+                <span class="metric-value" id="metric3">--</span>
+                <span class="metric-label">Metric 3</span>
+            </div>
+            <div class="metric-card">
+                <span class="metric-value" id="metric4">--</span>
+                <span class="metric-label">Metric 4</span>
+            </div>
+        </div>
+
+        <div class="content">
+            <!-- Add your charts, tables, or other visualizations here -->
+            <div id="visualization"></div>
+        </div>
+    </div>
+
+    <script type="module" src="main.js"></script>
+</body>
+</html>
+```
+
+### styles.css
+```css
+* { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+    --bg: #0f172a;
+    --bg-card: #1e293b;
+    --border: #334155;
+    --text: #f1f5f9;
+    --text-muted: #94a3b8;
+    --primary: #6366f1;
+}
+
+body {
+    font-family: system-ui, sans-serif;
+    background: var(--bg);
+    color: var(--text);
+    line-height: 1.5;
+}
+
+.dashboard {
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 32px 24px;
+}
+
+header {
+    margin-bottom: 32px;
+}
+
+header h1 {
+    font-size: 28px;
+    font-weight: 700;
+}
+
+.subtitle {
+    color: var(--text-muted);
+    margin-top: 4px;
+}
+
+.metrics {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 16px;
+    margin-bottom: 24px;
+}
+
+.metric-card {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 20px;
+    text-align: center;
+}
+
+.metric-value {
+    display: block;
+    font-size: 32px;
+    font-weight: 700;
+    color: var(--primary);
+}
+
+.metric-label {
+    display: block;
+    font-size: 13px;
+    color: var(--text-muted);
+    margin-top: 4px;
+}
+
+.content {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 24px;
+}
+
+@media (max-width: 768px) {
+    .metrics { grid-template-columns: repeat(2, 1fr); }
+}
+
+@media (max-width: 480px) {
+    .metrics { grid-template-columns: 1fr; }
+}
+```
+
+### main.js
+```javascript
+window.informerReady = false;
+
+async function init() {
+    try {
+        await loadData();
+        window.informerReady = true;
+    } catch (err) {
+        console.error('Failed to load:', err);
+    }
+}
+
+async function loadData() {
+    // Replace with your dataset ID
+    const datasetId = 'admin:your-dataset';
+
+    const result = await fetch(`/api/datasets/${datasetId}/_search`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            query: { match_all: {} },
+            size: 0,
+            aggs: {
+                total: { sum: { field: 'amount' } },
+                count: { value_count: { field: 'id' } },
+                avg: { avg: { field: 'amount' } },
+                by_category: {
+                    terms: { field: 'category', size: 10 },
+                    aggs: { total: { sum: { field: 'amount' } } }
+                }
+            }
+        })
+    }).then(r => r.json());
+
+    // Update metrics
+    const aggs = result.aggregations;
+    document.getElementById('metric1').textContent = formatCurrency(aggs.total.value);
+    document.getElementById('metric2').textContent = aggs.count.value.toLocaleString();
+    document.getElementById('metric3').textContent = formatCurrency(aggs.avg.value);
+    document.getElementById('metric4').textContent = result.hits.total.toLocaleString();
+
+    // Use aggs.by_category.buckets for visualization
+    // Each bucket has: { key: 'Category Name', doc_count: 123, total: { value: 456 } }
+    console.log('Category data:', aggs.by_category.buckets);
+}
+
+function formatCurrency(val) {
+    return new Intl.NumberFormat('en-US', {
+        style: 'currency',
+        currency: 'USD',
+        minimumFractionDigits: 0
+    }).format(val);
+}
+
+init();
+```
+
+## PDF Export Tips
+
+The PDF renderer uses **print media** and adds a `.print` class to `<html>`.
+
+```css
+/* Standard @media print works */
+@media print {
+    body {
+        background: white;
+        color: black;
+    }
+
+    .no-print {
+        display: none;
+    }
+
+    /* Avoid page breaks inside charts/cards */
+    .chart-container,
+    .metric-card {
+        break-inside: avoid;
+    }
+}
+
+/* Or use the .print class */
+.print .no-print {
+    display: none;
+}
+```