# Analytics (/docs/capabilities/analytics)

Declare `analytics` in your manifest and register an `IAnalyticsSource` through `contributions.analytics`. Add `auth` when connecting external accounts and register connection profiles/authenticators as described in [authentication](/docs/capabilities/auth). `dataSource` is not required.

Each authorized connection gets its own provider context with identity, credentials, configuration and HTTP client. The host owns registration and binding lifetime. Handle the `Either` returned by registration; unregister during deactivation when needed.

The provider owns datasets and dynamic filter options. It declares extraction modes, native row identity or whole-scope identity, coverage and continuation. An absent execution request means the initial snapshot. Reject unsupported execution requests. Never label partial or unverified data as complete, or infer deletions from an incomplete page. Changes and remote aggregation have explicit contracts; support depends on the addon.

This example exposes a small in-memory dataset. External providers must validate requests and implement only the modes/filters they advertise.

```ts
import {
  type AddonContext,
  type AnalyticsDatasetManifest,
  type IAnalyticsSource,
  createAnalyticsDatasetScope,
  Either,
} from '@mr-tick/sdk'

const dataset: AnalyticsDatasetManifest = {
  id: 'readings',
  name: 'Readings',
  description: 'An in-memory example',
  sourceFormat: 'json',
  endpoint: '/readings',
  extraction: { modes: ['snapshot'], identity: { kind: 'row', columns: ['id'] } },
  columns: [{ name: 'id', label: 'ID', type: 'string' }],
}

const source: IAnalyticsSource = {
  createInstance: () => ({
    listAnalyticsDatasets: async () => Either.success([dataset]),
    getFilterOptions: async () => Either.success([]),
    fetchAnalyticsDataset: async (input) => Either.success({
      dataset,
      rows: [{ id: 'reading-1' }],
      fetchedAt: new Date().toISOString(),
      execution: {
        kind: 'snapshot',
        coverage: 'complete',
        scope: createAnalyticsDatasetScope(input),
      },
    }),
  }),
}

export function registerAnalytics(context: AddonContext) {
  return context.contributions.analytics.register(source)
}
```

Snapshot pages can include `batch: { index, offset, finished, totalRows }`, a continuation and a coverage reason. Follow the continuation using the same scope and batch size. `finished` describes traversal, not snapshot consistency: multi-page Redmine reads remain unverified. A preview page never represents a global total, even when it closes traversal. Failed pages do not advance the cursor.

Declare `selection: { dateRange, project }` to support the built-in date/project inputs. Omission means unsupported; the host sends only declared selections, while provider-owned filters keep their own identifiers.

Redmine uses bounded JSON pages with native IDs. Atom discovery remains a limited feed. The desktop ingests batches into DuckDB generations and publishes atomically after completed traversal. Charts query the entire published selection through bounded local pages. Failed refreshes preserve the prior publication and explicit coverage.

Declare `extraction.changes: { deletions: 'none' | 'explicit' }` alongside the `changes` mode for checkpoint updates, or `extraction.windowRescan: { dateColumn }` for date-window rescans. Checkpoints advance only with atomic publication. Deltas without tombstones never delete absent rows. Redmine issues use `updated_on`; time entries use a `spent_on` window because their endpoint ignores `updated_on`.

Analytics restores saved spaces and local publications when reopened. Polling defaults to five minutes while the view is open, with a manual option; full reconciliation runs when due after six hours or through Synchronize. Refreshes preserve visible charts and expose batch progress. Deletions and older edits without a change feed require full reconciliation; remote real-time consistency is not guaranteed.


For remote aggregation, also declare `extraction.aggregation` with accepted dimensions/operators and `postProcessing: 'projection-only'`. The host validates measure projection and completed traversal. Remote totals allow local projection/filtering and are never regrouped as raw records. Redmine does not advertise this mode.
