For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
chore: update Javadoc for bulk upload and uploads client deprecation
Refresh documentation across all transaction and uploads client variants
to reflect expanded bulk upload support and mark the legacy uploads API
as deprecated.
Key changes:
Update createBulkTransactionsUploadUrl Javadoc to document support for both incomingTransactionsFile and historicalTransactionsFile types (sync, async, raw, and async-raw clients)
Mark UploadsClient.create(), createPart(), and update() (and all async/raw variants) as deprecated in favor of the bulk transactions upload URL endpoint
Add deprecation notice pointing consumers to the Historical Transaction Uploads integration guide
[ADDED] Configurable SDK logging via the new LogConfig, LogLevel, ILogger, Logger, and ConsoleLogger types in com.kard.api.core. Pass a LogConfig to KardApiClientBuilder.logging(LogConfig) or AsyncKardApiClientBuilder.logging(LogConfig) to capture HTTP request/response activity at your desired level (DEBUG, INFO, WARN, ERROR). Logging is silent by default — no output is produced unless explicitly enabled. Supply a custom ILogger implementation to redirect output to any logging framework.
[FIXED] Query-parameter getters on several request types (GetFilesMetadataRequest, GetEarnedRewardsRequest, GetLocationsByUserRequest, GetOffersByUserRequest, GetSubscriptionsRequest, ActivateOfferRequest, BoostOfferRequest) were annotated with @JsonProperty instead of @JsonIgnore. They are now correctly marked @JsonIgnore, preventing these fields from being unintentionally serialized into a request body.
GetEarnedRewardsRequest now supports an optional include parameter that accepts a comma-separated list of related resources (merchant, offer) to embed in the earned-rewards response. Pass the value via the builder with .include("merchant,offer") — existing builder chains require no changes.
The CardNetwork class has been moved from com.kard.api.resources.transactions.types to com.kard.api.resources.commons.types. Existing code that imports CardNetwork from the old package will fail to compile. Update all import statements from import com.kard.api.resources.transactions.types.CardNetwork; to import com.kard.api.resources.commons.types.CardNetwork;.
Two new types — AttributionState and AttributionFilter — are now available in the com.kard.api.resources.users.attributions.types package. NotificationAttributionAttributes and OfferAttributionAttributes each expose a new optional getState() method that returns placement context (offer rank and active filters) recorded at the time of the attribution event. Existing builder chains require no changes.
The getType() method on CreateFileUploadData and FileUploadUrlData now returns a FileUploadType enum instead of a hardcoded String. The new FileUploadType enum exposes constants INCOMING_TRANSACTIONS_FILE and HISTORICAL_TRANSACTIONS_FILE and a Visitor<T> interface for exhaustive handling. Additionally, type is now a required first step in both classes’ staged builders — code that calls CreateFileUploadData.builder().attributes(...) or FileUploadUrlData.builder().id(...) directly will fail to compile and must be updated to call .type(FileUploadType.INCOMING_TRANSACTIONS_FILE) (or the appropriate variant) first.
Four NotificationType constants — LOCATION, USER_OFFER, OFFER, and MERCHANT — have been removed, along with their corresponding Value enum entries and Visitor interface methods (visitLocation(), visitUserOffer(), visitOffer(), visitMerchant()). Any exhaustive visitor implementations or switch statements referencing these values must be updated. Additionally, the following public classes have been deleted: BrokerAmount, BrokerAmountType, BrokerAsset, BrokerAssetType, BrokerOperationHours, BrokerOperationPeriod, BrokerPurchaseChannel, and BrokerReward. Code that references any of these removed types will fail to compile and must be migrated accordingly.
The offer, merchant, location, and userOffer variants have been removed from NotificationDataUnion. The corresponding factory methods (offer(), merchant(), location(), userOffer()), accessors (getOffer(), getMerchant(), getLocation(), getUserOffer()), type-check methods (isOffer(), isMerchant(), isLocation(), isUserOffer()), and Visitor interface methods (visitOffer(), visitMerchant(), visitLocation(), visitUserOffer()) have all been removed. Additionally, the public classes BrokerRewardType, LocationAddress, LocationCoordinates, LocationStatus, MerchantSource, OfferStatus, OfferType, and TimePeriod have been deleted. Existing code that references any of these APIs will fail to compile and must be updated.
The UserOfferStatus, WebhookLocationsAttributes, WebhookLocationsData, and WebhookLocationsRelationships classes have been removed from the com.kard.api.resources.notifications.types package. Existing code that references any of these types will fail to compile and must be updated — remove all usages and consult the updated API documentation for any replacement types.
The WebhookMerchantAttributes, WebhookMerchantData, and WebhookMerchantRelationships classes have been removed from the com.kard.api.resources.notifications.types package. Existing code that references these classes or their builder stage interfaces (such as MerchantIdStage, NameStage, AttributesStage, etc.) will fail to compile and must be updated. Review the updated API definition for replacement types to handle webhook merchant payloads.
The WebhookOfferAttributes and WebhookOfferData classes have been removed from the SDK. Code that references either class — including their staged builder interfaces and getter methods — will fail to compile. Remove all usages of these types; replacement types may be introduced in a future release.
The following public classes have been removed from the com.kard.api.resources.notifications.types package: WebhookOfferRelationships, WebhookUserOfferAttributes, WebhookUserOfferData, and WebhookUserOfferRelationships, along with all of their associated builder interfaces and getter methods. Existing code that references any of these types will fail to compile and must be updated to remove or replace those usages.
The getFinancialInstitutionName() method on CoreTransactionAttributes now returns Optional<String> instead of String. Existing code that calls this method without unwrapping the Optional will fail to compile and must be updated. Additionally, the FinancialInstitutionNameStage builder interface has been removed — financialInstitutionName is no longer a required builder step and is instead set via optional overloaded methods on _FinalStage. Builder chains that previously passed through FinancialInstitutionNameStage must be updated accordingly.
The CoreTransactionAttributes class now includes an optional financialInstitutionId field that provides a unique identifier for the financial institution. The existing financialInstitutionName field has been deprecated — consumers should migrate to financialInstitutionId going forward.
The cardLastFour field in CoreTransactionAttributes has been renamed to cardLastFours and changed from Optional<String> to Optional<List<String>>. This supports cases where multiple card candidates may be provided when the issuer cannot determine which specific card was used. Existing code accessing getCardLastFour() must be updated to use getCardLastFours() and handle the list type.
The xKardTargetIssuer configuration method has been moved from the main client builders (KardApiClientBuilder and AsyncKardApiClientBuilder) to the authentication builders. When using credential-based authentication, call xKardTargetIssuer() on the credentials builder returned by .credentials() instead of on the main client builder.
The CoreTransactionAttributes class now includes an optional cardLastFour field that provides the last four digits of the card used for the transaction.
The ProgressBar API has been restructured with breaking changes. The segmentIcon field has been replaced with a segments configuration object. The ProgressBarLabel class has been renamed to ProgressBarSegment, and ProgressBarLabels now uses ProgressBarLabelPair objects instead of ProgressBarLabel. Update your code to use the new type names and field structures when working with progress bar configurations.
The ProgressBar class now includes a new required ‘labels’ field that enables configurable label placement for different layout views. Three new types are available: ProgressBarLabels (containing details and default view configurations), ProgressBarLabel (with text and position properties), and ProgressBarLabelPosition enum (supporting LEFT and RIGHT positions).
