@contractspec/example.analytics-dashboard 0.0.0-canary-20260113170453

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+# @contractspec/example.analytics-dashboard
+
+Website: https://contractspec.io/
+
+
+> Analytics Dashboard Example - Comprehensive data visualization and reporting solution
+
+## Overview
+
+This example demonstrates a full-featured analytics and dashboarding system built with ContractSpec, showcasing:
+
+- **Customizable Dashboards** - Drag-and-drop widget layouts
+- **Visual Query Builder** - Build queries without writing SQL
+- **Multiple Widget Types** - Charts, metrics, tables, maps
+- **Scheduled Reports** - Automated report generation and delivery
+- **Public Sharing** - Share dashboards with external stakeholders
+
+## Entities
+
+### Dashboard
+
+Main container for widgets and visualizations.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| organizationId | string | Organization owner |
+| name | string | Dashboard name |
+| slug | string | URL-friendly identifier |
+| description | string? | Dashboard description |
+| status | DashboardStatus | DRAFT, PUBLISHED, ARCHIVED |
+| refreshInterval | RefreshInterval | Auto-refresh frequency |
+| defaultDateRange | TimeRange | Default time filter |
+| isPublic | boolean | Public visibility |
+| shareToken | string? | Public access token |
+
+### Widget
+
+Individual visualization component on a dashboard.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| dashboardId | string | Parent dashboard |
+| name | string | Widget title |
+| type | WidgetType | LINE_CHART, BAR_CHART, PIE_CHART, METRIC, TABLE, etc. |
+| gridX, gridY | number | Grid position |
+| gridWidth, gridHeight | number | Grid dimensions |
+| queryId | string? | Linked query |
+| config | JSON | Widget-specific configuration |
+
+### Query
+
+Reusable data query definition.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| name | string | Query name |
+| type | QueryType | SQL, METRIC, AGGREGATION, CUSTOM |
+| definition | JSON | Query definition |
+| sql | string? | Raw SQL for SQL type |
+| metricIds | string[] | Metrics for METRIC type |
+| cacheTtlSeconds | number | Cache duration |
+| isShared | boolean | Shared across org |
+
+### Report
+
+Scheduled report definition.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| dashboardId | string | Source dashboard |
+| name | string | Report name |
+| schedule | string | Cron expression |
+| format | ReportFormat | PDF, PNG, CSV |
+| recipients | string[] | Email addresses |
+| lastRunAt | DateTime? | Last execution time |
+
+## Contracts
+
+### Dashboard Management
+
+```typescript
+// Create a new dashboard
+CreateDashboardContract
+Input: { name, slug, description?, refreshInterval? }
+Output: Dashboard
+
+// Add widget to dashboard
+AddWidgetContract
+Input: { dashboardId, name, type, gridX?, gridY?, queryId?, config? }
+Output: Widget
+
+// Get dashboard with widgets
+GetDashboardContract
+Input: { dashboardId? | slug? | shareToken? }
+Output: Dashboard (with widgets)
+
+// List user's dashboards
+ListDashboardsContract
+Input: { status?, search?, limit?, offset? }
+Output: { dashboards, total }
+```
+
+### Query Management
+
+```typescript
+// Create a query
+CreateQueryContract
+Input: { name, type, definition, sql?, metricIds?, cacheTtlSeconds? }
+Output: Query
+
+// Execute query
+ExecuteQueryContract
+Input: { queryId, parameters?, dateRange?, filters?, forceRefresh? }
+Output: { data, columns, rowCount, executionTimeMs, cached }
+```
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `analytics.dashboard.created` | Dashboard created |
+| `analytics.dashboard.published` | Dashboard published |
+| `analytics.widget.added` | Widget added to dashboard |
+| `analytics.query.created` | Query created |
+| `analytics.query.executed` | Query executed |
+| `analytics.dashboard.viewed` | Dashboard viewed |
+| `analytics.report.generated` | Scheduled report generated |
+
+## Widget Types
+
+- **Line Chart** - Time series data
+- **Bar Chart** - Categorical comparisons
+- **Pie Chart** - Part-to-whole relationships
+- **Area Chart** - Stacked time series
+- **Scatter Plot** - Correlation analysis
+- **Metric** - Single KPI display
+- **Table** - Tabular data
+- **Heatmap** - Density visualization
+- **Funnel** - Conversion analysis
+- **Map** - Geographic data
+- **Text** - Markdown content
+- **Embed** - External iframe
+
+## Query Types
+
+### Metric Query
+
+Query usage metrics from the metering system.
+
+```json
+{
+  "type": "METRIC",
+  "metricIds": ["active_users", "api_calls", "storage_used"]
+}
+```
+
+### Aggregation Query
+
+Build aggregations with measures and dimensions.
+
+```json
+{
+  "type": "AGGREGATION",
+  "source": "events",
+  "measures": [
+    { "name": "total_count", "field": "id", "aggregation": "COUNT" }
+  ],
+  "dimensions": [
+    { "name": "date", "field": "created_at", "type": "TIME", "granularity": "DAY" }
+  ],
+  "filters": [
+    { "field": "event_type", "operator": "eq", "value": "page_view" }
+  ]
+}
+```
+
+### SQL Query
+
+Write custom SQL (requires feature flag).
+
+```json
+{
+  "type": "SQL",
+  "sql": "SELECT date_trunc('day', created_at) as day, count(*) FROM events GROUP BY 1"
+}
+```
+
+## Usage
+
+```typescript
+import {
+  AnalyticsDashboardFeature,
+  CreateDashboardContract,
+  AddWidgetContract,
+  createQueryEngine,
+} from '@contractspec/example.analytics-dashboard';
+
+// Create a dashboard
+const dashboard = await execute(CreateDashboardContract, {
+  name: 'Sales Overview',
+  slug: 'sales-overview',
+  description: 'Key sales metrics and trends',
+  refreshInterval: 'FIFTEEN_MINUTES',
+});
+
+// Add a metric widget
+const widget = await execute(AddWidgetContract, {
+  dashboardId: dashboard.id,
+  name: 'Total Revenue',
+  type: 'METRIC',
+  gridX: 0,
+  gridY: 0,
+  gridWidth: 3,
+  gridHeight: 2,
+  queryId: revenueQueryId,
+  config: {
+    format: 'currency',
+    prefix: '$',
+    showChange: true,
+  },
+});
+
+// Execute a query
+const queryEngine = createQueryEngine();
+const result = await queryEngine.execute(
+  { type: 'METRIC', metricIds: ['daily_revenue'] },
+  { dateRange: { start: new Date('2024-01-01'), end: new Date() } }
+);
+```
+
+## Dependencies
+
+- `@contractspec/lib.schema` - Entity definitions
+- `@contractspec/lib.contracts` - Contract definitions
+- `@contractspec/lib.identity-rbac` - Access control
+- `@contractspec/lib.metering` - Usage metrics integration
+- `@contractspec/module.audit-trail` - Change tracking
+- `@contractspec/module.notifications` - Report delivery
+
+## Feature Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `ANALYTICS_SQL_QUERIES` | Enable SQL query support | false |
+| `ANALYTICS_SCHEDULED_REPORTS` | Enable scheduled reports | true |
+| `ANALYTICS_PUBLIC_DASHBOARDS` | Allow public sharing | false |
+| `ANALYTICS_ADVANCED_WIDGETS` | Enable maps, funnels | true |
+| `ANALYTICS_QUERY_CACHING` | Enable result caching | true |
+
+## Permissions
+
+| Permission | Description | Default Roles |
+|------------|-------------|---------------|
+| `dashboard:view` | View dashboards | viewer, analyst, admin |
+| `dashboard:create` | Create dashboards | analyst, admin |
+| `dashboard:edit` | Edit dashboards | analyst, admin |
+| `dashboard:delete` | Delete dashboards | admin |
+| `dashboard:share` | Share externally | analyst, admin |
+| `query:create` | Create queries | analyst, admin |
+| `query:execute` | Execute queries | viewer, analyst, admin |
+| `report:schedule` | Schedule reports | analyst, admin |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/dashboard/dashboard.enum.d.ts

@@ -0,0 +1,18 @@
+import * as _contractspec_lib_schema37 from "@contractspec/lib.schema";
+
+//#region src/dashboard/dashboard.enum.d.ts
+/**
+ * Dashboard status enum.
+ */
+declare const DashboardStatusEnum: _contractspec_lib_schema37.EnumType<[string, string, string]>;
+/**
+ * Widget type enum.
+ */
+declare const WidgetTypeEnum: _contractspec_lib_schema37.EnumType<[string, string, string, string, string, string, string, string, string, string, string, string]>;
+/**
+ * Refresh interval enum.
+ */
+declare const RefreshIntervalEnum: _contractspec_lib_schema37.EnumType<[string, string, string, string, string, string]>;
+//#endregion
+export { DashboardStatusEnum, RefreshIntervalEnum, WidgetTypeEnum };
+//# sourceMappingURL=dashboard.enum.d.ts.map

package/dist/dashboard/dashboard.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.enum.d.ts","names":[],"sources":["../../src/dashboard/dashboard.enum.ts"],"sourcesContent":[],"mappings":";;;;;;AAKa,cAAA,mBAIX,EAAA,0BAAA,CAJ8B,QAAA,CAAA,CAAA,MAAA,EAAA,MAAA,EAAA,MAAA,CAAA,CAAA;AAShC;AAkBA;;cAlBa,gBAaX,0BAAA,CAbyB;;;;cAkBd,qBAOX,0BAAA,CAP8B"}

package/dist/dashboard/dashboard.enum.js

@@ -0,0 +1,43 @@
+import { defineEnum } from "@contractspec/lib.schema";
+
+//#region src/dashboard/dashboard.enum.ts
+/**
+* Dashboard status enum.
+*/
+const DashboardStatusEnum = defineEnum("DashboardStatus", [
+	"DRAFT",
+	"PUBLISHED",
+	"ARCHIVED"
+]);
+/**
+* Widget type enum.
+*/
+const WidgetTypeEnum = defineEnum("WidgetType", [
+	"LINE_CHART",
+	"BAR_CHART",
+	"PIE_CHART",
+	"AREA_CHART",
+	"SCATTER_PLOT",
+	"METRIC",
+	"TABLE",
+	"HEATMAP",
+	"FUNNEL",
+	"MAP",
+	"TEXT",
+	"EMBED"
+]);
+/**
+* Refresh interval enum.
+*/
+const RefreshIntervalEnum = defineEnum("RefreshInterval", [
+	"NONE",
+	"MINUTE",
+	"FIVE_MINUTES",
+	"FIFTEEN_MINUTES",
+	"HOUR",
+	"DAY"
+]);
+
+//#endregion
+export { DashboardStatusEnum, RefreshIntervalEnum, WidgetTypeEnum };
+//# sourceMappingURL=dashboard.enum.js.map

package/dist/dashboard/dashboard.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.enum.js","names":[],"sources":["../../src/dashboard/dashboard.enum.ts"],"sourcesContent":["import { defineEnum } from '@contractspec/lib.schema';\n\n/**\n * Dashboard status enum.\n */\nexport const DashboardStatusEnum = defineEnum('DashboardStatus', [\n  'DRAFT',\n  'PUBLISHED',\n  'ARCHIVED',\n]);\n\n/**\n * Widget type enum.\n */\nexport const WidgetTypeEnum = defineEnum('WidgetType', [\n  'LINE_CHART',\n  'BAR_CHART',\n  'PIE_CHART',\n  'AREA_CHART',\n  'SCATTER_PLOT',\n  'METRIC',\n  'TABLE',\n  'HEATMAP',\n  'FUNNEL',\n  'MAP',\n  'TEXT',\n  'EMBED',\n]);\n\n/**\n * Refresh interval enum.\n */\nexport const RefreshIntervalEnum = defineEnum('RefreshInterval', [\n  'NONE',\n  'MINUTE',\n  'FIVE_MINUTES',\n  'FIFTEEN_MINUTES',\n  'HOUR',\n  'DAY',\n]);\n"],"mappings":";;;;;;AAKA,MAAa,sBAAsB,WAAW,mBAAmB;CAC/D;CACA;CACA;CACD,CAAC;;;;AAKF,MAAa,iBAAiB,WAAW,cAAc;CACrD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;AAKF,MAAa,sBAAsB,WAAW,mBAAmB;CAC/D;CACA;CACA;CACA;CACA;CACA;CACD,CAAC"}