analytics_hub

• Release 0.5.0: port zeely-mobile fixes, drop session support, add CI

Port behavior fixes made in the zeely-mobile copies of these packages:

• ProviderIdentifier equality/hashCode now include the runtime type so
  identifiers of different subclasses with the same name don't collide
• AnalyticsHub.initialize initializes providers sequentially
  (Future.forEach) instead of concurrently
• Quieter logging: sendEvent logs at fine level and the dispatch
  pipeline no longer logs each step
• Provider constructors accept an optional interceptors parameter

Remove session support (breaking): Session, HubSessionDelegate,
AnalyticsHub.sessionDelegate and AnalytycsProvider.setSession are gone;
apps manage user identity directly on the underlying SDKs. The
getAnonymousId parameters of the Mixpanel/Appsflyer providers are
removed with it.

Add GitHub Actions CI modeled on basalt_dart: analyze/format/test plus
publish dry-run on every push/PR, and tag-driven pub.dev publishing via
OIDC (-v tags).

Co-Authored-By: Claude Fable 5 [email protected]

• Audit cleanup: drop dead code and unnecessary dependencies

• Firebase/Appsflyer providers: remove flush() overrides that existed
  only to log a "not supported" message — the base AnalytycsProvider
  flush() is already a no-op. This drops the logging dependency from
  all three provider packages (mixpanel no longer imported it at all).
• analytics_hub core is now a pure Dart package: flutter_test dev
  dependency removed (tests only use package:test), so dart test
  works without a Flutter SDK.
• Remove unused dev dependencies: test from the provider packages
  (their tests use flutter_test), lints from mixpanel (inherited from
  the workspace root), test from the root package (no tests there).
• Provider tests: delete dead _TestEvent classes and
  registerFallbackValue setup left over from the removed setSession
  tests, plus the now-unused analytics_hub imports.
• Core internals: remove unused DispatchTarget.providerIdentifier
  getter; EventDispatcher.dispatch returns the executor future directly
  instead of awaiting into a local.
• Root README: close the unterminated yaml code fence in Quick start
  that swallowed the rest of the page on render.

Co-Authored-By: Claude Fable 5 [email protected]

• Rename AnalytycsProvider to AnalyticsProvider, fix workspace layout

Fix the long-standing typo in the provider base class name across all
packages, docs, examples, and tests. No compatibility alias is kept —
the packages have no external consumers yet.

Also move resolution: workspace from pubspec_overrides.yaml into each
package's pubspec.yaml (the layout basalt_dart and zeely-mobile use, and
what dart test's workspace validation expects) and delete the
overrides files.

Co-Authored-By: Claude Fable 5 [email protected]

• Fix mixpanel_flutter lower bound for pub.dev score compliance

Ran pana (the tool pub.dev uses to compute package score) against all
four packages. analytics_hub itself scores a clean 160/160.

Found a real bug via the "compatible with dependency constraint lower
bounds" check: mixpanel_flutter's declared minimum (2.0.0) allows
versions up to 2.2.0 where Mixpanel.track() returns void instead of
Future. MixpanelEventResolver.resolve declares a Future
return type and returns the track() call directly, so pinning an old
2.x mixpanel_flutter breaks analysis (and would break at runtime for
anyone actually on that range). Raised the lower bound to >=2.3.0,
where track() became async. Verified dart analyze is clean and tests
pass with dependencies downgraded to their lower bounds.

The three provider packages can't get a full pana score yet since they
depend on analytics_hub, which isn't published to pub.dev — pana (like
pub.dev itself) resolves dependency_overrides are ignored for scoring,
so this is a publish-order concern rather than a code issue: publish
analytics_hub first, then the providers.

Co-Authored-By: Claude Fable 5 [email protected]

• Add design spec for basalt_dart-style documentation

Covers badges + workspace banners on all READMEs, a "what's inside"
reference table in the core README, a packages/analytics_hub/doc/
folder with four deep-dive guides, and a root CONTRIBUTING.md —
scoped down from basalt_dart's equivalent docs to this repo's size.

Co-Authored-By: Claude Fable 5 [email protected]

• Add basalt_dart-style documentation

Badges + "part of workspace" banners on every README (EN/UA), a
"what's inside" reference table in the core README, a
packages/analytics_hub/doc/ folder with four deep-dive guides
(getting started, providers, interceptors & context, testing), and a
root CONTRIBUTING.md — implements the design spec, which is removed
now that it's realized in the actual docs.

Skipped the MIT license badge from the original spec: the repo has no
LICENSE file, so that badge would have been false.

Co-Authored-By: Claude Sonnet 5 [email protected]

• Remove initialize and dispose from provider lifecycle

SDK lifecycle belongs in the app — keep only flush for buffered backends.

Co-authored-by: Cursor [email protected]

• Fix example formatting for CI

Co-authored-by: Cursor [email protected]

Co-authored-by: Claude Fable 5 [email protected]
Co-authored-by: Cursor [email protected]

Changed

• ProviderIdentifier equality and hashCode now include the runtime type, so identifiers of different subclasses with the same name no longer collide. toString now prints the concrete subclass name.
• Reduced logging noise: sendEvent logs at fine level and the internal dispatch pipeline no longer logs each step.

Breaking Changes

• Removed session support: Session, HubSessionDelegate, the AnalyticsHub.sessionDelegate parameter, and AnalyticsProvider.setSession are gone. Manage user identity directly on the underlying SDKs.
• Removed AnalyticsHub.initialize / AnalyticsProvider.initialize and AnalyticsHub.dispose / AnalyticsProvider.dispose. SDK lifecycle belongs in the app — pass already-initialized backend instances into provider constructors; call flush before shutdown if a provider buffers events.
• Fixed the misspelled provider base class name: AnalytycsProvider is now AnalyticsProvider.

Changed

• Simplified provider-specific overrides API: EventProvider now exposes a direct overrides: EventOverrides? field instead of options: EventOptions?.
• EventOverridesApplier.apply now accepts EventOverrides? and no longer depends on EventOptions.
• Updated core example, tests, and documentation to use EventProvider(overrides: ...) and the EventOverrides type directly.

Breaking Changes

• The EventOptions type has been removed from the public API.
• Code that previously used EventProvider(options: EventOptions(overrides: ...)) must be updated to use EventProvider(overrides: EventOverrides(...)) instead.

Changed

• Added AnalyticsHub.flush() to allow explicit provider flush before app shutdown.
• Updated AnalytycsProvider contract:
  • provider interceptors are now constructor-injected (final List<EventInterceptor> interceptors);
  • added overridable flush() lifecycle method.
• Simplified dispatch context building by removing provider context merge from EventDispatchContextBuilder.
• Improved observability with additional logging in dispatch pipeline (AnalyticsHub, dispatcher, chain executor, overrides applier).
• Updated tests to match context behavior without provider metadata merge and added flush coverage.
• Updated examples/docs for provider constructor usage with explicit interceptors.

Changed

• Relaxed ContextEntry inheritance restriction by changing it from abstract base class to abstract class.

Changed

• Refined interception context architecture by extracting ContextEntry and introducing shared Context contract (Context, ContextEntry, EventContext, EventDispatchContext).
• Updated dispatch context to use typed metadata context composition instead of separate hub/provider metadata maps.
• Removed hub-level interceptor context from AnalyticsHub; dispatch context now combines event context and provider interceptor context.
• Renamed provider metadata contract from interceptorMetadata to interceptorContext.
• Extended/updated tests for typed context merge behavior (event context + provider context) and removed obsolete hub-context assertions.
• Updated README docs (EN/UA), examples, and package version snippets for 0.3.1.

Added

• Universal event interception pipeline with both hub-level and provider-level interceptors.
• Typed event metadata via EventContext / EventContextEntry (one entry per type, gql_exec-style).
• New dispatch models: ResolvedEvent, EventDispatchContext, and InterceptorResult.
• Hub-level metadata (interceptorMetadata) and provider-level metadata (interceptorMetadata) in dispatch context.

Changed

• Reverted core event model to a single LogEvent approach.
• Simplified routing and provider abstractions to log-event-only contracts.
• Updated examples, tests, and documentation to use List<EventProvider>.
• AnalyticsHub.sendEvent now applies EventProvider.options.overrides before dispatch.
• Event now exposes context so metadata is created at event declaration time.
• Internal interception implementation was decomposed into src/core/interception/* components (EventDispatcher, context builder, chain executor, overrides applier).

Removed

• CustomLogEvent, CustomLogEventResolver, and CustomLogEventOptions.
• ECommerceEvent, all e-commerce event/data types, and ECommerceEventResolver.
• Generic resolver typing from ProviderIdentifier, AnalytycsProvider, and EventProvider.

Breaking Changes

• Event is no longer generic and resolves only via LogEventResolver.
• AnalytycsProvider is no longer generic and now exposes LogEventResolver.
• ProviderIdentifier is no longer generic.
• EventResolver contract changed from resolveEvent(Event) to resolve({required ResolvedEvent event, required EventDispatchContext context}).
• AnalytycsProvider now supports optional interceptors and interceptorMetadata.
• AnalyticsHub constructor now supports global interceptors and interceptorMetadata.

Changed

• Added nullable property value support in LogEvent.properties: Map<String, Object?>?.
• Added nullable property value support in LogEventOverrides.properties: Map<String, Object?>?.

Changed

• Updated README examples to the Event.providers / EventProvider API.
• Replaced legacy ProviderKey/providerKeys naming in docs with ProviderIdentifier/providers.
• Updated installation snippets to current package versions.

Added

• New provider-targeting model via EventProvider<R, O> and EventOptions.
• Per-provider overrides for LogEvent via LogEventOptions and LogEventOverrides.
• Typed per-provider payload overrides for CustomLogEvent<T> and ECommerceEvent<T> through CustomLogEventOptions<T> and ECommerceEventOptions<T>.

Changed

• Renamed provider identity API from ProviderKey to ProviderIdentifier.
• AnalyticsHub now routes events via Event.providers and EventProvider.identifier.
• Extended public API documentation to cover new options and routing abstractions.

Breaking Changes

• Event.providerKeys was removed. Implement Event.providers instead: List<EventProvider<R, O>> get providers.
• ProviderKey<R> was renamed to ProviderIdentifier<R>.
• AnalytycsProvider constructor parameter and field were renamed from key to identifier.
• Event<R> now requires options type parameter: Event<R, O extends EventOptions>.
• LogEvent now extends Event<LogEventResolver, LogEventOptions>.
• CustomLogEvent<T> moved to custom_log_event.dart and now extends Event<CustomLogEventResolver<T>, CustomLogEventOptions<T>>.
• ECommerceEvent now requires a payload type: ECommerceEvent<T> extends Event<ECommerceEventResolver, ECommerceEventOptions<T>>.

Added

• Public API documentation (public_member_api_docs) for all core types: AnalyticsHub, events, providers, session, and resolvers.
• Extended e-commerce event model with typed events and data classes: AddToCart, AddToWishlist, ViewCart, AddPaymentInfo, AddShippingInfo, BeginCheckout, Purchase, RemoveFromCart, SelectItem, ViewItem, ViewItemList, ViewPromotion, Refund, and ECommerceEventItem.

Added

• Initial implementation of AnalyticsHub to fan-out events to multiple analytics providers.
• Core event hierarchy: Event, LogEvent, CustomLogEvent<T>, ECommerceEvent and SelectPromotionECommerceEvent.
• Provider abstraction: AnalytycsProvider<R>, ProviderKey<R>, HubSessionDelegate and Session for centralized session management.