vps_utilities 1.3.1

A multiplatform utilities package for VPS Citizen Mobile application. Supports iOS, Android, Web, Windows, macOS, and Linux. Provides network layer, secure storage, token management, registry, form en [...]

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

1.3.1 - 2026-03-05

Added

• Network – Configurable timeouts: [RestClient] now accepts optional connectTimeout, receiveTimeout, and sendTimeout [Duration] parameters (defaults: 15 s / 60 s / 15 s). Pass them through [VpsUtilities.initialize] to override per-app. Example: VpsUtilities.initialize(baseUrl: '...', receiveTimeout: const Duration(seconds: 120)). See Network – Timeouts.
• Form engine – Step indicator options: [VpsFormPageConfig] and [VpsFormEngineConfig] support optional initialStep (default 2; form starts at step 2), showStepIndicator (default true; hide stepper when false), and showStepNumbers (default true; unnumbered circles when false). Total steps are computed dynamically from initialStep and whether the pre-confirm (OB) flow runs. [VpsDefaultFormPageConfig] implements these getters. See Form engine – Step indicator and VpsFormEngineConfig.
• Form engine – Pre-confirm flow (OB flow): Optional [VpsFormPageConfig.shouldRunPreConfirmFlow] and [runPreConfirmFlow]. When shouldRunPreConfirmFlow(subModule, baseUrl) returns true (e.g. for OB modules), the engine calls runPreConfirmFlow(context, subModule, payload) before pushing the confirm page. The app can push occurrence location and station selection screens, merge results into the payload, and return the enriched map; return null to cancel. Payload should include at least location and station_id. See Form engine.
• Form engine – Location widget default: Built-in location field builder now enables myLocationButtonEnabled; when no initial location is set, the PlacePicker opens centered on the current user location (device GPS) where supported.
• Form engine – Default confirm page: Occurrence Location and Police Station rows: When the payload contains location and/or station_name (or station_id), [VpsFormDefaultConfirmPage] shows dedicated Occurrence Location and Police Station rows at the top of the details card, matching legacy vps_citizen confirm layout.
• Form engine – Default occurrence location and station screens: [VpsFormDefaultOccurrenceLocationScreen] and [VpsFormDefaultStationScreen] for the pre-confirm (OB) flow. [VpsFormDefaultScreens.showOccurrenceLocationPicker] and [VpsFormDefaultScreens.showStationPicker] push these screens and return the result map. Use them in [VpsFormPageConfig.runPreConfirmFlow]. Optional [VpsFormPageConfig.getStations] to supply stations; when null, the package uses [RegistryDataSource.getRegistryWithStationsAndOfficers].stations.

Changed

• Form engine: Submit flow now matches vps_citizen. Form page shows "Submit" button on the last page (or "Next" on non-final pages). On tap, the engine validates, runs narrative flow (if enabled), then optionally runs the pre-confirm flow when configured, then pushes the confirm page. [VpsFormDefaultConfirmPage] now matches vps_citizen layout: step indicator (step 3 of 4), white card with module name header and field rows (ordered by SubModule.fields), Edit button (pops back), and Submit button (performs actual submission). [VpsFormEngine.onNextPressed] now receives a [BuildContext] parameter (a descendant of BlocProvider) so the callback can read [VpsFormCubit] and push the confirm page with correct form state.
• Form engine config: [VpsFormPageConfig] adds optional mapsApiKey for Google Maps location picker fields. [VpsUtilities.initialize] now accepts optional googleMapsApiKey; when set, the form engine uses it for location fields (pageConfig.mapsApiKey overrides when provided).
• Documentation: Updated form_engine.md (pre-confirm flow, VpsFormPageConfig table, location default, Step indicator, VpsFormEngineConfig table and example), README.md (pre-confirm flow note, step indicator options, VpsFormEngineConfig parameters), docs/README.md (form engine index), and CHANGELOG to reflect the submit flow, default confirm page layout, onNextPressed signature, mapsApiKey, pre-confirm flow, and step indicator options (initialStep, showStepIndicator, showStepNumbers).

1.3.0 - 2026-02-05

Added

• Registry utility: Shared registry models ([RegistryModel], [RegistryDatum], [SubModule], [Field], [StationResponseModel], [StationOfficer], etc.) and [RegistryDataSource] for fetching registry (and optionally stations/officers) via the package [NetworkService] and [guardedApiCall]. Supports both officer app (registry only, configurable endpoint e.g. officer_registry) and citizen app (registry + stations + officers, optional fields initial_iprs, documents). Resolve with VpsUtilities.resolve<RegistryDataSource>(); throws [GuardedApiException] on API failure.
• Flexible secure storage: VpsUtilities.setSecureData, getSecureData, removeSecureData, clearAllSecureData, containsSecureKey for arbitrary key-value data. Same encrypted backend as the auth token. SecureStorage class is exported and can be resolved via VpsUtilities.resolve<SecureStorage>().
• Form engine: Configurable form with paging, validation, [VpsFormEngine], [VpsFormPageConfig], [VpsFormEngineConfig], [FieldBuilderRegistry], [VpsFieldBuildInput], and context.pushForm(SubModule) single-call API. Optional AI narrative Q&A and review dialogs. Built-in default builders for text, textarea, number; placeholders for select, location, mugshot, etc. Custom builders via register(type, builder) or registerByName(name, builder).
• AI narrative enhancement: [NarrativeServicePort] (real impl when aiNarrativeBaseUrl set, no-op otherwise). [NarrativeKeysHelper], [VpsNarrativeDialog], [VpsEnhancedNarrativeReviewDialog], [VpsNarrativeFlowHandler]. Form engine runs narrative flow on Next (last page) before onProceedToConfirm.
• Form engine config: [VpsFormPageConfig] (baseUrl, onFormOpen, onFormSubmitted, onProceedToConfirm, optional custom narrative dialogs). [VpsUtilities.formEngineConfig] for registration. VpsUtilities.reset() clears form config.
• Device info: [DeviceInfoProvider], [DeviceInfoData], VpsUtilities.collectDeviceInfo() for device registration payloads.
• Cache: [CacheManager] with stale-while-revalidate, [CacheConfig], [CacheEntry]. Resolve via VpsUtilities.resolve<CacheManager>(); call initialize() before use.
• Full documentation: docs/ folder with dedicated docs for initialization, network, token, secure storage, cache, device info, responsive, registry, form engine, narrative. docs/README.md index. Main README links to all docs.

Changed

• Registry: Documented in docs/registry.md. Form engine uses [SubModule] and [Field] from registry.
• Responsive: Documented in docs/responsive.md.

1.2.0 - 2026-01-30

Changed

• Multiplatform: Package is explicitly multiplatform; supports iOS, Android, Web, Windows, macOS, and Linux from a single codebase. Description and README updated; no UI (uses-material-design: false).

1.1.0 - 2026-01-30

Added

• Cubit state management: TokenCubit and TokenState for token state (hasToken, token); syncs with TokenStore; provide via BlocProvider, react with BlocBuilder/BlocListener
• Network layer: NetworkService (getHttp, postHttp, putHttp, deleteHttp) with Dio and RestClient
• Secure token storage via flutter_secure_storage; VpsUtilities.setAuthToken and VpsUtilities.getAuthToken
• Optional per-request token parameter on each HTTP method (use token for a single request without setting it globally)
• ApiErrors enum for response error handling (serverError, badRequest, notFound, validationFailed, unauthenticated, notPermitted, unknown, noInternet, failure)
• Base URL from package initialization; BaseUrlConfigRepository and Kiwi DI for all network and config types
• Logging only in debug mode (guarded with kDebugMode)

1.0.0 - 2026-01-30

Added

• Initial package setup
• Basic package structure
• Base URL config and Kiwi injector