vendure 3.0.1

Flutter SDK for Vendure Open Source Headless Commerce Framework.

3.0.1 - 2026-09-22

Fixes

• Transient network failures: Added retry logic for transient connection-level network failures in the data source layer, improving reliability in unstable network conditions.

Features

• Real exercises: Added gym exercises for the Vendure SDK — warmup and fetch-product-by-id operations to validate SDK functionality.

Chores

• Added .memsearch recall artifact to .gitignore.
• Post-publish steps documented in PUBLISH.md.

3.0.0 - 2026-08-07

Complete SDK rewrite using the Zuraffa v5 + Zorphy architecture. All Freezed-based models have been replaced with concrete @JsonSerializable entities generated from the Vendure GraphQL schema. The package now follows a clean-architecture layout (domain / data layers) while preserving the public Vendure facade API.

Breaking Changes (AC-7)

• Entities relocated — all entity classes moved from lib/src/types/ and lib/src/input_types/ to lib/src/domain/entities/<snake_case>/. The old lib/src/types/ directory is now a single shim (exports.dart) that re-exports from the new location. lib/src/input_types/ has been removed entirely; PaginatedList / ListOptions now live at lib/src/domain/entities/paginated_list.dart.
• Merged enums — the 12 enum types (CurrencyCode, ErrorCode, LanguageCode, Permission, SortOrder, AdjustmentType, AssetType, DeletionResult, GlobalFlag, HistoryEntryType, LogicalOperator, OrderType) are now a merged superset of the former types/ and input_types/ variants, located at lib/src/domain/entities/enums/. Enum values use @JsonValue for correct GraphQL round-tripping (e.g. CurrencyCode.usd ↔ "USD").
• Dropped generated copyWith / == / hashCode / when extensions — Freezed is no longer a dependency. Entities are plain @JsonSerializable classes without generated equality, copyWith, or union when methods. Consumers that relied on .copyWith() must implement manual copy logic.
• json_serializable is now dev-only (D1 deviation, AC-7) — freezed, freezed_annotation, and mocktail have been removed from dependencies. json_serializable remains in dev_dependencies (not fully removed) because entities use @JsonSerializable for JSON round-tripping; this is documented as deviation D1.
• mocktail removed — test doubles are no longer bundled; the test suite runs against a live Vendure instance.
• vendure_session.dart removed — session management is handled internally by the Vendure facade and TokenManager; the standalone session file is gone.

Architecture (clean-architecture layout)

• lib/src/domain/entities/ — 179 Zorphy-style entities (fallback form: @JsonSerializable concrete classes; 41 scalar-only leaf entities flagged as zorphyCandidate: true in entity-manifest.json for future Zorphy migration once zuraffa#272 is resolved).
• lib/src/domain/repositories/ — repository interfaces (Order, Catalog, Customer, System).
• lib/src/domain/usecases/ — use-case classes per domain area.
• lib/data/datasources/remote/ — VendureRemoteDataSource (GraphQL execution).
• lib/data/repositories/ — data-layer repository implementations.
• lib/vendure.dart — public Vendure facade (unchanged public API surface).

Schema Source (FR-003 / AC-5)

All 179 entities were generated from the Vendure GraphQL schema captured via standalone introspection (tool/introspect_schema.dart) on 2026-08-06. Provenance and counts are recorded in specs/001-vendure-zuraffa-plugin-rewri/research.md (179 entities, 12 enums, 22 unions, 6 interfaces, 9 scalars).

Fixes

• Enum JSON round-tripping — enum values now use @JsonValue annotations so that GraphQL uppercase values (e.g. "USD", "INSUFFICIENT_STOCK_ERROR") decode correctly. Previously the fallback $enumDecode matched by Dart enum name (lowercase) and crashed on uppercase GraphQL values.
• Nullable entity fields — entity fields are now nullable to match the Vendure GraphQL schema (most fields are nullable), preventing Null cast crashes during deserialization.
• Response enum normalization — VendureRemoteDataSource no longer double-converts enum values in mutation responses; raw GraphQL values are passed to the generated _$EnumMap decoders.

2.19.0 - 2026-06-16

• Fix: Added reentrancy guard to prevent race conditions during concurrent Vendure initialization across all initialization methods.
• Fix: Set queryRequestTimeout: null on internal token fetch clients to resolve a graphql 5.x race condition where Stream.timeout could double-complete the internal Completer.
• Internal: Proper HTTP client lifecycle management (create and close) in token fetch helper methods.
• Internal: Reset _initializing flag on dispose() to allow clean re-initialization.
• Docs: Added sponsor badges (App Store, Google Play, Zikzak AI) to README.

2.18.0

• Change: Updated dependencies to the latest compatible versions.

2.17.0

• Feature: Added API key authentication support for machine-to-machine authentication. New initializeWithApiKey() method and setApiKey() runtime setter.
• Feature: All initialization methods (initialize, initializeWithNativeAuth, initializeWithFirebaseAuth, initializeWithCustomAuth) now accept apiKey and apiKeyHeaderKey parameters.
• Internal: HTTP requests and WebSocket subscriptions now include the API key header (defaults to vendure-api-key).

2.16.0

• Fix: Active customer stream subscription now uses the Customer fragment, allowing sanitizeGraphQLQuery to inject customFields. Previously the subscription used an inline selection, so customFields was always null on WebSocket updates.
• Change: Updated http dependency to the latest compatible version, which may include performance improvements and bug fixes.

2.15.0

• Feature: Added support for paginated queries and mutations
• Breaking Change: Converted to dart package with support for both Flutter and Dart
• Fix: Authentication methods now always throw exceptions instead of returning null
• Internal: Code formatting and linting improvements

2.14.1

• Fix: Instead of returning null, always throw exception on Auth

2.14.0

• Feature: Converted to dart package, with support for Flutter and Dart.

2.13.0

• Feature: Added support for nested custom fields in customFieldsConfig.
• Feature: Support for SCALAR_CUSTOM_FIELDS marker to request customFields as a raw scalar (prevents JSON subfield selection errors).
• Performance: Optimized the Customer fragment by leaning down fields, resulting in faster queries.
• Internal: Enhanced GraphQL query sanitization to handle complex nested fragments.

2.12.0

• Fix: Restored the customFields operation that was accidentally removed in the previous release. customFields support is now available again for all operations that accept custom fields.
• Note: If you experienced missing customFields behaviour in 2.11.0, upgrading to 2.12.0 will restore the expected functionality.

2.11.0

• Fix: Ensure enum field mappings include MetricInterval, MetricType, and StockMovementType so enum normalization converts these fields correctly.
• Internal: Updated VendureUtils enum mappings and normalization logic to reduce false positives for generic type fields.
• Tests: Added/adjusted unit tests for enum conversion of new mappings and list-valued enum fields.

2.10.0

• Added Support for activeCustomerStream Subscription: Now you can subscribe to real-time updates for the active customer.
• Improved Enum Handling: Updated internal field-to-type mappings for all Shop API enums (CurrencyCode, LanguageCode, Permission, AdjustmentType, GlobalFlag, ErrorCode, LogicalOperator, DeletionResult, etc.).
• New Utility VendureSchemaUtils.discoverEnums(): A new utility to manually trigger schema introspection and register custom enums at runtime.
• Enhanced Normalization: Improved GraphQL data normalization for subscription results and custom fields.

2.9.0

• Fixed Enum Conversion for Conflicting Field Names: Enhanced normalizeGraphQLData to handle cases where multiple GraphQL types have fields with the same name (e.g., Parser.type, Order.type, Asset.type).
• Robust Fallback Mechanism: Added fallback logic that checks if a string value matches ANY known enum value from the introspection cache, ensuring all enums are converted even when field-to-type mappings conflict.
• Better Support for Custom Types: Custom plugin types with enum fields are now properly converted without requiring manual enum mapping.
• Non-Breaking Enhancement: The change is backward compatible and requires no API changes from consumers.

2.8.0

• Added global enum conversion toggles: VendureUtils.convertQueryEnums and VendureUtils.convertMutationEnums (both default to true).
• Added VendureUtils.setConvertEnums({bool? queryEnums, bool? mutationEnums}) helper to change conversion flags globally.
• normalizeGraphQLData and normalizeMutationData now respect global flags and also accept a per-call convertEnums override.
• Fixed mutation normalization to only convert actual enum fields using schema introspection (no heuristic conversions).
• Added per-call convertEnums parameter to CustomOperations mutation methods for fine-grained control.
• Exported VendureUtils from the package entrypoint so the global flags and helper are accessible to package consumers.
• Bumped package version to 2.8.0 in pubspec.yaml.
• Internal: improved safety around enum conversions and added tests for enum normalization behavior.

2.7.0

• BREAKING CHANGE: Removed default 10-second timeout for GraphQL queries
• Immediate Failure Detection: Connection failures now fail immediately instead of waiting for timeout
• Optional Timeout: The timeout parameter is now truly optional - only applies if explicitly set
• Improved User Experience: Apps can now detect unreachable backends instantly and proceed with fallback behavior

2.5.0

• Robust Enum Normalization: Refactored normalization to use dynamic schema introspection for all enum fields and values. Now supports automatic camelCase conversion for all enums, regardless of field name.
• Field-to-Enum Mapping: Added automatic mapping of GraphQL fields to their enum types using introspection, ensuring all enum fields are normalized.
• SDK Cleanup: Removed all debug prints, centralized normalization logic, and improved recursion for speed and maintainability.
• DRY & Fast: Refactored normalization to avoid duplicate logic and unnecessary recursion, making it production-grade and easy to extend.
• No Breaking Changes: All existing APIs remain compatible, but normalization is now more reliable and future-proof.

2.4.0

• Enhanced Language Code Support: Improved dynamic language code handling with proper URI parsing instead of string concatenation.
• Dynamic Channel Token Management: Added setChannelToken() and getChannelToken() methods for runtime channel switching.
• Better URI Handling: Fixed URI construction to properly handle existing query parameters and language codes in endpoints.
• New Static Methods: Added setLanguageCode(), getLanguageCode(), setChannelToken(), and getChannelToken() for dynamic configuration.
• Preserved Original Endpoints: When no language code is set, the original endpoint URL is preserved as-is without modification.
• Multi-tenant Support: Enhanced support for multi-channel applications with dynamic channel token switching.

2.3.0

• Updated graphql package to latest compatible version.
• Fixed async/generic bug in mutate for bool and map return types.
• Improved type safety and error handling for all custom operations.
• All previous bugfixes and enum normalization improvements included.

2.2.0

• Improved error handling for all Vendure error types (e.g. InvalidCredentialsError, ErrorResult, etc.) so authentication failures always throw a standardized, testable message.
• Defensive null checks for error messages to prevent type errors.
• Enum normalization restored: all enum values for keys in _vendureTypeEnums are now converted to Dart/camelCase style recursively.
• Type safety enforced for all map responses.
• Internal logging and debug improvements for error diagnosis.
• See normalizeGraphQLData and authentication methods for details.

2.1.1

• Added refresh token via Vendure instance: Vendure.instance.refreshToken(params) now available for direct use.
• Makes token refresh accessible from the singleton instance for all auth flows.

2.1.0

• Added refresh token support via TokenManager and Vendure.refreshToken.
• You can now refresh authentication tokens dynamically for long-lived sessions or custom auth flows.
• See Vendure.refreshToken and TokenManager for usage.

2.0.0

⚠️ Breaking Change

• CustomOperations API: The fromJson parameter is now optional for mutate, query, queryList, and mutateList methods.
• If fromJson is not provided, the raw normalized data is returned (cast to the expected type).
• This change breaks previous usage where fromJson was required.
• Update your code to handle the new method signatures and return types.

1.8.0

• Added static setAuthToken method to update the authentication token on the initialized Vendure instance.

1.7.2

• added timeout option to Vendure initialization methods
• increased default GraphQL client timeout to 10 seconds (was 5 seconds)

1.7.1

• fixed enum value conversion in _convertEnumToDartFormat method
• improved handling of camelCase enum values (e.g., 'staticVal' now correctly preserved instead of being converted to 'staticval')
• method now properly handles both SCREAMING_SNAKE_CASE and camelCase enum formats

1.7.0

• fixed native authentication implementation
• improved GraphQL client configuration with better caching policies
• added default headers for HTTP requests
• enhanced guest session handling
• fixed typo in available countries query filename
• added comprehensive test suites for user journeys

1.6.0

• added support for vendure-token header to pass the channel
• added languageCode support for translations

1.5.0

• added mutateList for mutations that return a List

1.4.0

• refactored custom operations code

1.3.0

• changed fromJson data type to dynamic

1.2.6

• fixed customfields config not passing to order and system operations

1.2.5

• fixed internal type import

1.2.4

• fixed ActiveCustomer error on active order removeAllItems

1.2.3

• fixed Customer customFields parsing issue

1.2.2

• fixed Turkish Lira TRY conversion issue

1.2.1

• Removed CollectionWithParentChildren entity

1.2.0

• Added getCollectionsWithParentChildren method
• Added getCollectionWithChildren method
• Added getCollectionWithParent method
• Added getCollectionWithParentChildren method
• Updated FacetValue to includ Facet

1.1.0

• Added support for customfields. define customfieldsConfig on initialize

1.0.1

• Updated productId and productVariantId int types to String

0.9.1

• Renamed type to CollectionWithParentChildren for simplicity

0.9.0

• Added getCollectionsWithParentChildren method

0.8.5

• fixed the bug options not passing on getCollections

0.8.4

• changed getCollectionById tpe to String from int

0.8.3

• changed getOrderByCode return type to Order

0.8.2

• updated http dependency

0.8.1

• Added setOrderShippingMethod example

0.8.0

• Strong types are implemented for all methods

0.7.0

• All shop-api methods are implemented

0.6.6

• Updated README

0.6.3

• Added setOrderShippingAddress method
• Added getActiveOrder method
• Added addPaymentToOrder method
• Added getOrderByCode method
• Added getPaymentMethods method
• Added getShippingMethods method
• Added setCustomerForOrder method

0.5.1

• Added setOrderShippingAddress and updated README example

0.5.0

• Exported types

0.4.2

• Updated Readme explaining how to manage firebase token changes

0.4.1

• Update the instance credentials without reinitizialize

0.4.0

• Made it singleton with predefined initialization methods NativeAuth,FirebaseAuth,Token and Custom Auth

0.3.1

• fixed http dependency

0.3.0

• Added automated opinionated session refresh management

0.2.0

• Added extractResponseHeaders method to extract response headers.

0.1.0

• Initial version.