@trackunit/iris-app 1.12.7 → 1.12.10

package/src/generators/preset/files/.agents/skills/customfields/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: customfields
+description: Use when storing app data on entities, persisting user input, defining custom fields in manifest, or reading/writing entity-specific data.
+---
+
+# CustomFields
+
+## Overview
+
+CustomFields extend the Trackunit data model by storing additional information on entities (assets, accounts, groups, sites). This is the primary mechanism for persisting IrisX app data.
+
+## When to Use
+
+- Storing user input or preferences
+- Adding metadata to assets/accounts/groups/sites
+- Persisting app-specific configuration
+- Creating custom KPIs or fleet attributes
+
+**Not for:** External databases or storage solutions (use CustomFields instead).
+
+## Defining Custom Fields
+
+### Manifest Configuration
+
+```typescript
+customFieldDefinitions: [
+  {
+    type: 'STRING',
+    entityType: 'ASSET',
+    key: 'myCustomField',
+    translations: [{
+      language: 'en',
+      title: 'My Custom Field',
+      description: 'Description of what this field stores',
+    }],
+    uiEditable: true,
+    uiVisible: true,
+    scopeType: 'ACCOUNT' // or 'ACCOUNT_WRITE_GLOBAL_READ' or 'GLOBAL'
+  }
+]
+```
+
+### Required Properties
+
+| Property | Description |
+|----------|-------------|
+| `type` | Field data type |
+| `entityType` | `ACCOUNT`, `ASSET`, `GROUP`, or `SITE` |
+| `key` | Programmatic identifier (immutable after creation) |
+| `translations` | UI labels and descriptions |
+| `scopeType` | Data access scope |
+
+### Optional Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `uiEditable` | `true` | Can be edited in Manager UI |
+| `uiVisible` | `true` | Visible in Manager UI |
+
+## Supported Field Types
+
+| Type | Description | Extra Properties |
+|------|-------------|------------------|
+| `BOOLEAN` | True/false values | - |
+| `DATE` | ISO8601 formatted dates | - |
+| `DROPDOWN` | Predefined option lists | `allValues`, `multiSelect`, `valueReplacements` |
+| `EMAIL` | Email addresses with mailto links | - |
+| `NUMBER` | Numeric values | `minimum`, `maximum`, `isInteger`, `unitSi`, `unitUs` |
+| `PHONE_NUMBER` | E.164 formatted phone numbers | - |
+| `STRING` | Free text | `minimumLength`, `maximumLength`, `pattern` |
+| `STRING_LIST` | Array of strings | - |
+| `WEB_ADDRESS` | URLs as clickable links | - |
+| `JSON` | JSON objects | - |
+| `FILE` | File attachments | - |
+| `MONETARY` | Currency values (ISO 4217) | `currency` |
+
+## Example Field Definitions
+
+### String with Validation
+
+```typescript
+{
+  type: 'STRING',
+  entityType: 'ASSET',
+  key: 'serialNumber',
+  translations: [{ language: 'en', title: 'Serial Number', description: 'Asset serial number' }],
+  minimumLength: 5,
+  maximumLength: 20,
+  pattern: '^[A-Z0-9]+$'
+}
+```
+
+### Number with Units
+
+```typescript
+{
+  type: 'NUMBER',
+  entityType: 'ASSET',
+  key: 'fuelCapacity',
+  translations: [{ language: 'en', title: 'Fuel Capacity', description: 'Tank capacity' }],
+  minimum: 0,
+  maximum: 1000,
+  unitSi: 'L',
+  unitUs: 'gal'
+}
+```
+
+### Dropdown with Multiple Selection
+
+```typescript
+{
+  type: 'DROPDOWN',
+  entityType: 'ASSET',
+  key: 'features',
+  translations: [{ language: 'en', title: 'Features', description: 'Available features' }],
+  allValues: ['GPS', 'Camera', 'Bluetooth', 'WiFi'],
+  multiSelect: true
+}
+```
+
+## Scope Types
+
+| Scope | Description |
+|-------|-------------|
+| `ACCOUNT` | Values shared within a single account only |
+| `ACCOUNT_WRITE_GLOBAL_READ` | Account can write, all accounts can read |
+| `GLOBAL` | Values shared between all accounts with entity access |
+
+## Using CustomFields in React
+
+### Required Imports
+
+```typescript
+import { 
+  useCustomFieldsValueAndDefinition,
+  useUpdateCustomFieldValues
+} from '@trackunit/custom-field-api';
+import { CustomField } from '@trackunit/custom-field-components';
+import { useCurrentUserSystemOfMeasurement } from '@trackunit/react-core-hooks';
+```
+
+### Basic Implementation
+
+```typescript
+import React from 'react';
+import { useForm } from 'react-hook-form';
+import { Card, CardBody, CardHeader, CardFooter, Button, Spinner } from '@trackunit/react-components';
+import { useCustomFieldsValueAndDefinition, useUpdateCustomFieldValues } from '@trackunit/custom-field-api';
+import { CustomField } from '@trackunit/custom-field-components';
+import { useCurrentUserSystemOfMeasurement } from '@trackunit/react-core-hooks';
+
+const CustomFieldsForm = ({ assetId }: { assetId: string }) => {
+  const { register, handleSubmit, formState, setValue, control } = useForm({
+    shouldUnregister: false,
+  });
+  
+  const { systemOfMeasurement } = useCurrentUserSystemOfMeasurement();
+  
+  const { fields, loading } = useCustomFieldsValueAndDefinition({
+    entityType: "ASSET",
+    entityId: assetId,
+    systemOfMeasurement: systemOfMeasurement ?? "SI",
+  });
+  
+  const { updateCustomFields, inProgress } = useUpdateCustomFieldValues(
+    assetId,
+    "ASSET",
+    fields,
+    systemOfMeasurement ?? "SI"
+  );
+
+  if (loading) return <Spinner />;
+
+  return (
+    <Card>
+      <CardHeader heading="Custom Fields" />
+      <CardBody>
+        {fields.map(field => {
+          const isEditable = field.valueEditable && (field.definition.uiEditable ?? true);
+          return (
+            <CustomField
+              key={field.definition.key}
+              control={control}
+              field={field}
+              formState={formState}
+              isEditable={isEditable}
+              register={register}
+              setValue={setValue}
+              unitPreference={systemOfMeasurement}
+            />
+          );
+        })}
+      </CardBody>
+      <CardFooter>
+        <Button 
+          loading={inProgress} 
+          onClick={handleSubmit(updateCustomFields)}
+        >
+          {inProgress ? "Saving..." : "Save Changes"}
+        </Button>
+      </CardFooter>
+    </Card>
+  );
+};
+```
+
+## Best Practices
+
+### Field Design
+- **Use descriptive keys**: Choose clear, descriptive field keys that won't need changing
+- **Add proper translations**: Always provide meaningful titles and descriptions
+- **Set appropriate constraints**: Use min/max values, length limits, and patterns for validation
+
+### Performance
+- **Batch updates**: Use `useUpdateCustomFieldValues` to update multiple fields at once
+- **Handle loading states**: Always show loading indicators while fetching data
+- **Error handling**: Implement proper error handling for failed updates
+
+### Deployment
+- **Field keys are immutable**: Cannot be changed after creation
+- **Definition updates**: Changing field definitions affects all existing data
+- **Approval process**: Custom field changes require app approval and marketplace submission
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Changing field key after creation | Keys are immutable; plan carefully upfront |
+| Missing translations | Always provide titles and descriptions for UI |
+| Using external storage | CustomFields are the recommended persistence mechanism |
+| No loading states | Show `<Spinner />` while fetching data |
+| Skipping error handling | Handle failed updates gracefully |
+
+## References
+
+- [Save Data from Your App](https://developers.trackunit.com/docs/save-data-from-your-app)
+- [Defining a Custom Field](https://developers.trackunit.com/docs/defining-a-custom-field)
+- [Using a Custom Field](https://developers.trackunit.com/docs/using-a-custom-field)
+- [Deploying a New Custom Field](https://developers.trackunit.com/docs/deploying-a-new-custom-field)

package/src/generators/preset/files/.agents/skills/graphql/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: graphql
+description: Use when setting up GraphQL tooling, writing queries/mutations, generating hooks, or fetching data from Trackunit API.
+---
+
+# GraphQL API Integration
+
+## Overview
+
+Trackunit exposes a GraphQL API with NX executors for code generation. Use `@trackunit/react-graphql-tools` to generate typed React hooks from `.graphql` files.
+
+## When to Use
+
+- Setting up GraphQL in an extension
+- Writing queries or mutations
+- Generating React hooks from `.graphql` files
+- Fetching data from Trackunit API
+
+**Not for:** Time series data (use `graphql-timeseries` skill).
+
+## Setup
+
+### Install GraphQL Tools
+
+```bash
+npm install @trackunit/react-graphql-tools
+```
+
+### Set Up GraphQL Tooling
+
+```bash
+npx nx generate @trackunit/react-graphql-tools:add-graphql --project=[project-name]
+```
+
+Where `[project-name]` is found in the library's `project.json` file (format: `[subdir-name]-[extension-name]` for extensions in subdirectories).
+
+### Generate React Hooks
+
+```bash
+npx nx run [feature-name]-[extension-name]:graphql-hooks
+```
+
+This generates React hooks from `.graphql` files in the `src` folder.
+
+## GraphQL File Structure
+
+Create `.graphql` files in `libs/[feature-name]/[extension-name]/src/` directory.
+
+### Query Syntax
+
+```graphql
+query QueryName($variable: Type) {
+  fieldName {
+    subField
+  }
+}
+```
+
+### Mutation Syntax
+
+```graphql
+mutation MutationName($variable: Type!) {
+  mutationField(input: $variable) {
+    result
+  }
+}
+```
+
+## React Integration
+
+### Import Generated Hooks
+
+```typescript
+import { QueryNameDocument } from "./generated/graphql-api/graphql";
+```
+
+### Use Queries
+
+```typescript
+import { useQuery } from '@trackunit/react-graphql-hooks';
+
+const { data, loading, error } = useQuery(QueryNameDocument, {
+  variables: { /* your variables */ }
+});
+```
+
+### Use Mutations
+
+```typescript
+import { useMutation } from '@apollo/client';
+
+const [mutationName, { data, loading, error }] = useMutation(MutationNameDocument);
+```
+
+## Common Patterns
+
+### Query with Variables
+
+```typescript
+const { data, loading, error } = useQuery(GetAssetDocument, {
+  variables: { assetId: "123" }
+});
+
+if (loading) return <Spinner />;
+if (error) return <ErrorMessage error={error} />;
+
+return <AssetDisplay asset={data?.asset} />;
+```
+
+### Mutation with Refetch
+
+```typescript
+import { useMutation } from '@apollo/client';
+
+const [updateAsset, { loading }] = useMutation(UpdateAssetDocument, {
+  refetchQueries: [{ query: GetAssetDocument, variables: { assetId } }]
+});
+
+const handleUpdate = async (input) => {
+  await updateAsset({ variables: { input } });
+};
+```
+
+### Polling
+
+```typescript
+const { data } = useQuery(GetAssetsDocument, {
+  pollInterval: 5000, // Poll every 5 seconds
+});
+```
+
+## References
+
+- [Calling Trackunit GraphQL API](https://developers.trackunit.com/docs/graphql-api)
+- [Apollo useQuery documentation](https://www.apollographql.com/docs/react/data/queries)
+- [Apollo useMutation documentation](https://www.apollographql.com/docs/react/data/mutations)
+- [GraphQL Code Generator](https://the-guild.dev/graphql/codegen)
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using generic GraphQL libraries | Use `@trackunit/react-graphql-tools` only |
+| Missing hook generation | Run `nx run [project]:graphql-hooks` after adding `.graphql` files |
+| Wrong project name format | Use `[subdir-name]-[extension-name]` from `project.json` |
+| No loading/error states | Always handle `loading` and `error` from hooks |
+| Importing from wrong path | Import from `./generated/graphql-api/graphql` |

package/src/generators/preset/files/.agents/skills/graphql-timeseries/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: graphql-timeseries
+description: Use when querying machine insights, engine metrics, fuel data, operating hours, or building charts with historical time-based data.
+---
+
+# GraphQL Time Series API
+
+## Overview
+
+Query time series data through GraphQL using PromQL (Prometheus Query Language). Use `rangeQuery` for time series charts, `instantQuery` for current values.
+
+## When to Use
+
+- Querying engine metrics (speed, temperature, fuel rate)
+- Building historical data charts
+- Calculating increases over time periods (daily fuel usage, operating hours)
+- Getting current sensor values
+
+**Not for:** Static entity data (use `graphql` skill).
+
+## Query Structure
+
+### Range Query (Time Series Data)
+
+```graphql
+query GetTimeSeriesData($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(query: "metric_name", start: $start, end: $end, step: $step) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result {
+              values { timestamp value }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Instant Query (Single Point in Time)
+
+```graphql
+query GetInstantData($assetId: ID!, $time: DateTime!) {
+  asset(id: $assetId) {
+    timeSeries {
+      instantQuery(query: "metric_name", time: $time) {
+        data {
+          ... on TimeSeriesVectorData {
+            result { value { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Common Metrics
+
+### Machine Insights
+
+Not all assets have all insights. Common metrics include:
+
+**Engine Metrics:**
+- `machine_insight_engine_speed`
+- `machine_insight_engine_coolant_temperature`
+- `machine_insight_engine_oil_pressure`
+- `machine_insight_engine_oil_temperature`
+- `machine_insight_engine_fuel_rate`
+- `machine_insight_engine_total_fuel_used`
+- `machine_insight_engine_percent_load_at_current_speed`
+- `machine_insight_cumulative_engine_hours`
+
+**Fuel & Emissions:**
+- `machine_insight_fuel_level`
+- `machine_insight_fuel_tank_capacity`
+- `machine_insight_fuel_used_last_24`
+- `machine_insight_cumulative_co2_emissions`
+
+**Operating Hours:**
+- `machine_insight_cumulative_operating_hours`
+- `machine_insight_cumulative_idle_hours`
+- `machine_insight_cumulative_moving_hours`
+- `machine_insight_cumulative_productive_hours`
+
+**Battery & Electric:**
+- `machine_insight_battery_state_of_charge_percent`
+- `machine_insight_battery_state_of_health_percent`
+- `machine_insight_battery_temperature`
+- `machine_insight_battery_current`
+- `machine_insight_battery_potential`
+
+**Location & Movement:**
+- `machine_insight_speed`
+- `machine_insight_altitude`
+- `machine_insight_total_vehicle_distance`
+
+**Environmental:**
+- `machine_insight_ambient_air_temperature`
+- `machine_insight_barometric_pressure`
+
+## PromQL Examples
+
+### Calculate Daily Increases
+
+```graphql
+query IncreaseOperatingHours($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(
+        query: "increase(machine_insight_cumulative_operating_hours[1d])",
+        start: $start,
+        end: $end,
+        step: $step
+      ) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result { values { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Filter with Conditions
+
+```graphql
+query HighFuelConsumption($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(
+        query: "increase(machine_insight_engine_total_fuel_used[1d]) > 13",
+        start: $start,
+        end: $end,
+        step: $step
+      ) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result { values { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Combine Metrics
+
+```graphql
+query FuelWithHighIdle($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(
+        query: "(increase(machine_insight_engine_total_fuel_used[1d]) > 13) and (increase(machine_insight_cumulative_idle_hours[1d]) > 4)",
+        start: $start,
+        end: $end,
+        step: $step
+      ) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result { values { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Key Points
+
+- **Always use fragments** for both `TimeSeriesMatrixData` and `TimeSeriesVectorData`
+- **Use PromQL functions**: `increase()`, `rate()`, `avg_over_time()`
+- **Filter at query level** with operators: `>`, `<`, `>=`, `<=`, `==`, `!=`
+- **Time windows** use brackets: `[1d]`, `[1h]`, `[15m]`
+- **Step intervals**: Choose based on data granularity needed
+- **Timestamps** are Unix timestamps in seconds
+- **Values** are returned as strings - convert to numbers as needed
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing fragment for data type | Use `... on TimeSeriesMatrixData` or `TimeSeriesVectorData` |
+| Not handling missing metrics | Not all assets have all insights; handle empty results |
+| Using values as numbers directly | Values are strings; convert with `parseFloat()` |
+| Wrong step interval | Match step to desired chart granularity |

package/src/generators/preset/files/.agents/skills/irisx-app-sdk/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: irisx-app-sdk
+description: Use when creating apps, adding extensions, configuring CSP/scopes, or needing SDK command reference. Core SDK documentation.
+---
+
+# IrisX App SDK Development
+
+## Overview
+
+IrisX Apps are React applications that integrate into Trackunit Manager at defined extension points. Use SDK commands (not generic React/Node.js) for all project operations.
+
+## When to Use
+
+- Creating new apps or extensions
+- Configuring security (CSP headers, scopes)
+- Looking up extension types or SDK commands
+- Understanding runtime hooks availability
+
+**Not for:** GraphQL setup (use `graphql` skill), browser testing (use `browser-testing` skill).
+
+## Extension Points
+
+Extensions are React applications that integrate into specific points in Trackunit Manager:
+
+| Extension Type | Location |
+|----------------|----------|
+| `ASSET_HOME_EXTENSION` | New tabs in Assets Home screen |
+| `SITE_HOME_EXTENSION` | New tabs in Site Home screen |
+| `FLEET_EXTENSION` | Menu items in Main Menu |
+| `REPORT_EXTENSION` | New reports in Reports screen |
+| `WIDGET_EXTENSION` | Dashboard widgets |
+| `IRIS_APP_SETTINGS_EXTENSION` | Configuration UI in App library |
+| `ADMIN_EXTENSION` | Admin UI tabs (admin-only) |
+| `CUSTOMER_HOME_EXTENSION` | UI within Customer Home |
+| `ASSET_EVENTS_ACTIONS_EXTENSION` | UI in Asset Home Events |
+| `LIFECYCLE_EXTENSION` | Handles app install/uninstall events |
+| `SERVERLESS_FUNCTION_EXTENSION` | Serverless backend functions |
+
+## Commands
+
+### Create New App
+
+```bash
+npx nx generate @trackunit/iris-app:create [name-of-your-app]
+```
+
+See: [Creating a new app](https://developers.trackunit.com/docs/creating-a-new-app)
+
+### Create New Extension
+
+```bash
+npx nx g @trackunit/iris-app:extend --name=[my-extension-name] --app=[app-name] --directory=[feature] --type=[extension-type]
+```
+
+See: [Creating a new extension](https://developers.trackunit.com/docs/creating-a-new-extension)
+
+### Run App
+
+```bash
+npx nx run [name-of-your-app]:serve
+```
+
+See: [Running the Iris App SDK](https://developers.trackunit.com/docs/running-the-iris-app-sdk)
+
+## Security Configuration
+
+IrisX Apps are locked down by default. External API requests and embedded content require proper Content Security Policy (CSP) configuration in the app manifest.
+
+### CSP Headers Example
+
+```typescript
+cspHeader: {
+  'frame-src': ['https://api.example.com', 'https://dashboard.example.com'],
+  'script-src': ['https://api.example.com'],
+  'connect-src': ['https://api.example.com'],
+},
+```
+
+### Scopes Example
+
+```typescript
+scopes: [
+  {scope: "required.scope.1", optional: false},
+  {scope: "required.scope.2", optional: true},
+],
+```
+
+Apps requiring API access need scopes configured in the manifest, and the app must be deployed with those scopes to work locally. Never submit an app automatically - instruct the user to do so.
+
+See: [Embedding IrisX Dashboards in Apps](https://developers.trackunit.com/docs/analytics-dashboards-in-apps#troubleshooting)
+
+## Runtime Hooks
+
+IrisX Apps have access to runtime hooks from `@trackunit/react-core-hooks`:
+
+- `useAssetRuntime()` - Asset information in asset-scoped extensions
+- `useCustomerRuntime()` - Customer data
+- `useEventRuntime()` - Event details
+- `useSiteRuntime()` - Site information
+- Plus navigation, user context, and utility hooks
+
+See the `react-core-hooks` skill for full details.
+
+## Quality Assurance
+
+Before completing any task: Always use `read_lints` to check for and fix all ESLint and TypeScript errors in modified files.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using `create-react-app` or `npm init` | Use `nx generate @trackunit/iris-app:create` |
+| Mocking data without asking | Always use real GraphQL API |
+| Missing scopes in manifest | Add required scopes; deploy to enable locally |
+| External API blocked | Add domain to `cspHeader` in manifest |
+| Auto-submitting app | Never auto-submit; instruct user to deploy |