@entrinsik/vite-plugin-informer 1.0.0

package/src/deploy.js

@@ -0,0 +1,156 @@
+import { createClient } from './client.js';
+import { readdir, readFile, stat, access } from 'node:fs/promises';
+import { join, relative, posix, basename, dirname } from 'node:path';
+
+const TEXT_EXTENSIONS = new Set([
+    '.html', '.css', '.js', '.mjs', '.json', '.svg',
+    '.xml', '.txt', '.md', '.csv', '.map', '.yaml', '.yml'
+]);
+
+// Files above this size use chunked upload via Flow.js protocol
+const CHUNK_THRESHOLD = 512 * 1024; // 512KB
+
+// Config files to upload from project root (if they exist)
+const ROOT_CONFIG_FILES = ['data-access.yaml'];
+
+/**
+ * Deploy a built Vite project to Informer as a Magic Report.
+ *
+ * @param {{ baseUrl: string, apiKey?: string, user?: string, pass?: string, slug: string, distDir: string, name?: string, description?: string }} opts
+ */
+export async function deploy({ baseUrl, apiKey, user, pass, slug, distDir, name, description }) {
+    const api = createClient({ baseUrl, apiKey, user, pass });
+
+    // 1. Get current user for natural ID
+    const me = await api.get('me');
+    const naturalId = `${me.username}:${slug}`;
+
+    // 2. Lookup report by natural ID
+    let report = await api.get(`reports/${naturalId}`);
+
+    // 3. Create if not found
+    if (!report) {
+        console.log(`Report "${naturalId}" not found, creating...`);
+        await api.post('reports', {
+            type: 'magicReport',
+            name: name || slug,
+            description: description || ''
+        });
+        // Re-fetch to get the full report
+        report = await api.get(`reports/${naturalId}`);
+        if (!report) {
+            throw new Error(`Failed to create report "${naturalId}"`);
+        }
+        console.log(`Created report: ${report.id}`);
+    }
+
+    // 4. Update name/description if provided
+    const updates = {};
+    if (name) updates.name = name;
+    if (description !== undefined) updates.description = description;
+    if (Object.keys(updates).length > 0) {
+        await api.put(`reports/${naturalId}`, updates);
+    }
+
+    // 5. Snapshot via report route
+    console.log('Creating snapshot...');
+    await api.post(`reports/${naturalId}/snapshots`, {
+        trigger: 'refresh',
+        limit: 10
+    });
+
+    // 6. Clear existing files via report route
+    console.log('Clearing existing files...');
+    const files = await api.get(`reports/${naturalId}/files?start=0&end=10000`);
+    if (files && Array.isArray(files)) {
+        // Delete non-directories first
+        const nonDirs = files.filter(f => !f.directory);
+        await Promise.all(nonDirs.map(f => api.del(`reports/${naturalId}/files/${f.id}`)));
+
+        // Then delete directories in reverse order (deepest first by path length)
+        const dirs = files
+            .filter(f => f.directory)
+            .sort((a, b) => (b.path || '').length - (a.path || '').length);
+        for (const d of dirs) {
+            await api.del(`reports/${naturalId}/files/${d.id}`);
+        }
+    }
+
+    // 7. Upload dist/ contents via report routes
+    console.log(`Uploading files from ${distDir}...`);
+    const entries = await walkDir(distDir);
+
+    for (const filePath of entries) {
+        const relPath = posix.normalize(relative(distDir, filePath).split('\\').join('/'));
+        const content = await readFile(filePath);
+
+        if (content.length > CHUNK_THRESHOLD) {
+            // Large file: chunked upload via Flow.js protocol
+            await api.uploadChunked({
+                reportId: naturalId,
+                path: relPath,
+                buffer: content,
+                filename: basename(filePath)
+            });
+            console.log(`  ${relPath} (${formatSize(content.length)}, chunked)`);
+        } else {
+            // Small file: direct JSON upload
+            const ext = '.' + relPath.split('.').pop();
+            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
+            const payload = isText
+                ? { content: content.toString('utf8'), encoding: 'utf8' }
+                : { content: content.toString('base64'), encoding: 'base64' };
+
+            await api.put(`reports/${naturalId}/contents/${relPath}`, payload);
+            console.log(`  ${relPath}`);
+        }
+    }
+
+    // 8. Upload config files from project root (e.g., data-access.yaml)
+    const projectRoot = dirname(distDir);
+    let configCount = 0;
+    for (const configFile of ROOT_CONFIG_FILES) {
+        const configPath = join(projectRoot, configFile);
+        try {
+            await access(configPath);
+            const content = await readFile(configPath, 'utf8');
+            await api.put(`reports/${naturalId}/contents/${configFile}`, {
+                content,
+                encoding: 'utf8'
+            });
+            console.log(`  ${configFile} (from project root)`);
+            configCount++;
+        } catch {
+            // File doesn't exist, skip
+        }
+    }
+
+    // 9. Print report URL
+    const totalFiles = entries.length + configCount;
+    const reportUrl = `${baseUrl.replace(/\/+$/, '')}/reports/r/${naturalId}`;
+    console.log(`\nPublished ${totalFiles} files to: ${reportUrl}`);
+}
+
+/**
+ * Recursively walk a directory, returning file paths (not directories).
+ */
+async function walkDir(dir) {
+    const results = [];
+    const items = await readdir(dir);
+    for (const item of items) {
+        const full = join(dir, item);
+        const s = await stat(full);
+        if (s.isDirectory()) {
+            results.push(...await walkDir(full));
+        } else {
+            results.push(full);
+        }
+    }
+    return results;
+}
+
+function formatSize(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/index.js

@@ -0,0 +1,88 @@
+import dotenv from 'dotenv';
+
+/**
+ * Vite plugin for local Magic Report development.
+ *
+ * - Proxies /api requests to the Informer server with Basic auth
+ * - Injects window.__INFORMER__ context mock in dev mode
+ * - Sets base to './' so built assets use relative paths
+ *
+ * @param {{ mock?: object }} options
+ * @returns {import('vite').Plugin}
+ */
+export default function informer(options = {}) {
+    let isDev = false;
+
+    return {
+        name: 'vite-plugin-informer',
+
+        config(_, { command }) {
+            dotenv.config();
+
+            isDev = command === 'serve';
+
+            const cfg = {
+                base: './'
+            };
+
+            if (isDev) {
+                const baseUrl = process.env.INFORMER_URL;
+                const apiKey = process.env.INFORMER_API_KEY;
+                const user = process.env.INFORMER_USER;
+                const pass = process.env.INFORMER_PASS;
+
+                if (baseUrl) {
+                    const auth = apiKey
+                        ? 'Bearer ' + apiKey
+                        : 'Basic ' + Buffer.from(`${user}:${pass}`).toString('base64');
+
+                    cfg.server = {
+                        proxy: {
+                            '/api': {
+                                target: baseUrl,
+                                changeOrigin: true,
+                                headers: {
+                                    Authorization: auth
+                                }
+                            }
+                        }
+                    };
+                }
+            }
+
+            return cfg;
+        },
+
+        transformIndexHtml: {
+            order: 'pre',
+            handler(html) {
+                if (!isDev) return html;
+
+                const mock = {
+                    report: {
+                        id: 'dev-local',
+                        name: 'Local Development'
+                    },
+                    ...options.mock
+                };
+
+                const script = `<script>
+(function() {
+    'use strict';
+    window.__INFORMER__ = ${JSON.stringify(mock)};
+})();
+</script>`;
+
+                // Insert after <head> tag, matching server behavior
+                const headIdx = html.indexOf('<head>');
+                if (headIdx !== -1) {
+                    const insertPos = headIdx + '<head>'.length;
+                    return html.slice(0, insertPos) + '\n' + script + '\n' + html.slice(insertPos);
+                }
+
+                // Fallback: prepend
+                return script + '\n' + html;
+            }
+        }
+    };
+}

package/templates/skill/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: informer
+description: Building Magic Reports with local Vite development. Covers the dev/publish workflow and key Informer APIs for datasets, queries, and integrations.
+---
+
+# Magic Report Development
+
+## What is a Magic Report?
+
+A Magic Report is a custom HTML/JS/CSS application that runs inside Informer. It can:
+- Query Informer datasets (Elasticsearch-indexed data)
+- Execute saved queries
+- Make authenticated requests to external APIs via integrations (Salesforce, etc.)
+- Render charts, tables, and interactive visualizations
+
+Reports are stored in Informer libraries and served through the Informer UI.
+
+## Local Development Workflow
+
+### Development Mode (`npm run dev`)
+
+The Vite plugin proxies `/api/*` requests to your Informer server with Basic auth. This means:
+- Your code makes fetch calls to `/api/...` (no host needed)
+- The plugin adds authentication headers automatically
+- You get hot reload while working against real Informer data
+
+Configuration is in `.env`:
+```
+INFORMER_URL=http://localhost:3000
+INFORMER_API_KEY=your-api-key
+```
+
+Or use basic auth:
+```
+INFORMER_URL=http://localhost:3000
+INFORMER_USER=admin
+INFORMER_PASS=yourpassword
+```
+
+### Deploying (`npm run deploy`)
+
+Builds your project and uploads to an Informer library:
+1. Creates/finds a Magic Report by slug (from package.json `name`)
+2. Snapshots the library for rollback
+3. Clears existing files
+4. Uploads all built assets from `dist/`
+5. Uploads `data-access.yaml` from project root (if it exists)
+6. Report is viewable at `/reports/r/{owner}:{slug}`
+
+## Discovering Resources
+
+Once `.env` is configured, Claude can query the Informer API directly to help you find available resources. Ask Claude to look up:
+
+- **Integrations**: `curl -u $USER:$PASS "$INFORMER_URL/api/integrations"` - Find integration slugs for QuickBooks, Salesforce, etc.
+- **Datasets**: `curl -u $USER:$PASS "$INFORMER_URL/api/datasets-list"` - Find dataset IDs and field names
+- **Queries**: `curl -u $USER:$PASS "$INFORMER_URL/api/queries-list"` - Find saved query IDs
+- **Datasources**: `curl -u $USER:$PASS "$INFORMER_URL/api/datasources"` - Find SQL datasource IDs
+
+This helps you find the correct IDs/slugs to use in your code and `data-access.yaml`. Just ask Claude to "show me available integrations" or "find the QuickBooks integration slug".
+
+## Key APIs
+
+All endpoints are relative to `/api`. In dev mode, the Vite proxy handles auth.
+
+### List Datasets
+
+```javascript
+const response = await fetch('/api/datasets-list');
+const datasets = await response.json();
+// Returns: [{ id, name, description, records, size, ... }, ...]
+```
+
+Use this to discover available datasets. Each dataset has:
+- `id` - UUID or natural ID like `admin:sales-data`
+- `name` - Display name
+- `records` - Approximate record count
+
+### Search Dataset (Elasticsearch)
+
+```javascript
+const response = await fetch(`/api/datasets/${datasetId}/_search`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        query: { match_all: {} },
+        size: 100,
+        from: 0,
+        _source: ['field1', 'field2'],  // Optional: limit fields returned
+        sort: [{ field1: 'desc' }],      // Optional: sort order
+        aggs: {                          // Optional: aggregations
+            total: { sum: { field: 'amount' } }
+        }
+    })
+});
+const result = await response.json();
+
+// Response structure:
+// result.hits.total - total matching records
+// result.hits.hits - array of { _source: { field1, field2, ... } }
+// result.aggregations - aggregation results (if requested)
+```
+
+**Common query patterns:**
+
+```javascript
+// Filter by exact value
+{ query: { bool: { filter: [{ term: { status: 'active' } }] } } }
+
+// Filter by 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 (AND)
+{ query: { bool: { filter: [
+    { term: { region: 'North' } },
+    { range: { amount: { gte: 1000 } } }
+] } } }
+```
+
+**Common aggregations:**
+
+```javascript
+// Sum, avg, min, max
+{ aggs: { total: { sum: { field: 'amount' } } } }
+
+// Group by field
+{ aggs: { by_region: { terms: { field: 'region', size: 50 } } } }
+
+// Group with nested 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' } } }
+    }
+} }
+```
+
+### List Queries
+
+```javascript
+const response = await fetch('/api/queries-list');
+const queries = await response.json();
+// Returns: [{ id, name, description, ... }, ...]
+```
+
+### Execute Query
+
+```javascript
+const response = await fetch(`/api/queries/${queryId}/_execute`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        parameters: { param1: 'value1' }  // Optional query parameters
+    })
+});
+const result = await response.json();
+```
+
+### List Integrations
+
+```javascript
+const response = await fetch('/api/integrations');
+const result = await response.json();
+// result.items = [{ id, name, slug, type, ... }, ...]
+```
+
+Integrations are authenticated connections to external APIs (Salesforce, REST APIs, etc.).
+
+### Make Integration Request
+
+```javascript
+const response = await fetch(`/api/integrations/${slugOrId}/request`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        url: '/data/v59.0/query',           // Path relative to integration's base URL
+        method: 'GET',                       // HTTP method
+        params: { q: 'SELECT Id FROM Account' },  // Query params
+        data: { /* body for POST/PUT */ },   // Request body
+        headers: { /* extra headers */ }     // Additional headers
+    })
+});
+const result = await response.json();
+
+// Response structure:
+// result.status - HTTP status code
+// result.data - response body from the external API
+// result.error - true if upstream returned an error status
+```
+
+**Salesforce example:**
+```javascript
+const response = 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, Amount FROM Opportunity WHERE StageName = 'Closed Won'"
+        }
+    })
+});
+const result = await response.json();
+const records = result.data.records;
+```
+
+## Data Access Configuration
+
+When your report is published and shared, you must declare which APIs it needs access to. Create a `data-access.yaml` file in your project root (it will be published with your report).
+
+**Important:** Without this file, all API access is blocked when the report runs in Informer.
+
+### Basic Example
+
+```yaml
+# data-access.yaml
+
+datasets:
+  - admin:sales-data
+  - admin:customers
+
+queries:
+  - admin:monthly-summary
+
+integrations:
+  - salesforce
+```
+
+### With Row-Level Security
+
+Restrict data based on the viewing user's profile:
+
+```yaml
+datasets:
+  # Users only see their region's data
+  - id: admin:orders
+    filter:
+      region: $user.custom.region
+
+  # Users only see their own records
+  - id: admin:sales
+    filter:
+      sales_rep: $user.username
+```
+
+### Integration with Credentials
+
+Pass user-specific credentials to external APIs:
+
+```yaml
+integrations:
+  - id: partner-api
+    headers:
+      Authorization: Bearer $user.custom.partnerToken
+    params:
+      client_id: $tenant.id
+```
+
+### Available Variables
+
+| Variable | Description |
+|----------|-------------|
+| `$user.username` | Login name |
+| `$user.email` | Email address |
+| `$user.displayName` | Full name |
+| `$user.custom.xxx` | Custom user field |
+| `$tenant.id` | Tenant ID |
+| `$report.id` | Report UUID |
+
+### Resource Types
+
+| Type | API Access Granted |
+|------|-------------------|
+| `datasets` | `_search`, `fields` |
+| `queries` | `_execute` |
+| `datasources` | `_query` |
+| `integrations` | `request` |
+| `libraries` | `contents/*` |
+
+For edge cases, you can also whitelist raw API paths:
+
+```yaml
+apis:
+  - POST /api/custom/endpoint
+```
+
+## Report Context
+
+When running inside Informer (not dev mode), the report receives context:
+
+```javascript
+const reportId = window.__INFORMER__?.report?.id;
+const reportName = window.__INFORMER__?.report?.name;
+```
+
+In dev mode, the Vite plugin mocks this with placeholder values.
+
+## PDF Export
+
+Reports can be exported to PDF via `POST /api/reports/{id}/_print`.
+
+### How it works
+
+1. Informer opens your report in a headless browser (Puppeteer)
+2. Waits for network requests to complete
+3. Waits for `window.informerReady` to become `true`
+4. Adds `.print` class to `<html>`
+5. Captures the page as PDF using print media
+
+### Signal when ready
+
+Set `window.informerReady` to signal when your report is fully rendered:
+
+```javascript
+// Start of app
+window.informerReady = false;
+
+// After all charts/content rendered
+window.informerReady = true;
+```
+
+### Rendering details
+
+- **Print media is used** - Standard `@media print` CSS rules apply
+- **`.print` class added** - Informer adds a `.print` class to `<html>` for additional targeting
+- **Viewport is 1200px** by default (configurable via `viewportWidth` option)
+- **Box shadows are removed** - They render as grey boxes in PDFs
+- **Colors are preserved** - `print-color-adjust: exact` is applied automatically
+
+### Print CSS
+
+Use standard `@media print` rules or the `.print` class:
+
+```css
+/* Standard print media query */
+@media print {
+    body {
+        background: white;
+        color: black;
+    }
+
+    .no-print {
+        display: none;
+    }
+}
+
+/* Or use the .print class (added by Informer) */
+.print .no-print {
+    display: none;
+}
+
+/* Avoid page breaks inside elements */
+.chart-container {
+    break-inside: avoid;
+}
+```
+
+### Print API options
+
+```javascript
+await fetch(`/api/reports/${reportId}/_print`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        format: 'Letter',        // Letter, Legal, Tabloid, A3, A4, A5
+        landscape: false,
+        viewportWidth: 1200,     // 400-2400, affects responsive layouts
+        waitForReady: true,      // Wait for window.informerReady
+        save: false              // true = save to downloads, false = return PDF
+    })
+});
+```
+
+## Reference Files
+
+- `references/api-reference.md` - Detailed API documentation
+- `references/report-templates.md` - HTML/CSS/JS starter templates