diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6538ca9..6d78745 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.8.0" + ".": "0.9.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index e7b8198..c12f542 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 20 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cas-parser/cas-parser-cd8e042a9746bbe9bd180614fccc7597b85f4e8f6a29da6cd2f4cbf831fb2fbe.yml -openapi_spec_hash: e27c0d9cd8cdeb348c88e6c4e8777e39 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cas-parser/cas-parser-4d179917b01ea51a3325e7b37ecbbb60d0ba8f60381fe715ff3ec31284ca8042.yml +openapi_spec_hash: d027d37bd7051aa8c05fe1820c05b316 config_hash: 5509bb7a961ae2e79114b24c381606d4 diff --git a/CHANGELOG.md b/CHANGELOG.md index 49291ba..679b312 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 0.9.0 (2026-08-09) + +Full Changelog: [v0.8.0...v0.9.0](https://github.com/CASParser/cas-parser-java/compare/v0.8.0...v0.9.0) + +### Features + +* **api:** api update ([fc2389b](https://github.com/CASParser/cas-parser-java/commit/fc2389bdcf955faa09806458c8ea75e9647b1a18)) +* **api:** api update ([0b5a0a6](https://github.com/CASParser/cas-parser-java/commit/0b5a0a6ab6df4b9c90bdbb68aea0965fda0772a9)) + ## 0.8.0 (2026-08-04) Full Changelog: [v0.7.1...v0.8.0](https://github.com/CASParser/cas-parser-java/compare/v0.7.1...v0.8.0) diff --git a/README.md b/README.md index e406e83..38599f9 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ -[![Maven Central](https://img.shields.io/maven-central/v/com.cas_parser.api/cas-parser-java)](https://central.sonatype.com/artifact/com.cas_parser.api/cas-parser-java/0.8.0) -[![javadoc](https://javadoc.io/badge2/com.cas_parser.api/cas-parser-java/0.8.0/javadoc.svg)](https://javadoc.io/doc/com.cas_parser.api/cas-parser-java/0.8.0) +[![Maven Central](https://img.shields.io/maven-central/v/com.cas_parser.api/cas-parser-java)](https://central.sonatype.com/artifact/com.cas_parser.api/cas-parser-java/0.9.0) +[![javadoc](https://javadoc.io/badge2/com.cas_parser.api/cas-parser-java/0.9.0/javadoc.svg)](https://javadoc.io/doc/com.cas_parser.api/cas-parser-java/0.9.0) @@ -22,7 +22,7 @@ Use the Cas Parser MCP Server to enable AI assistants to interact with this API, -The REST API documentation can be found on [casparser.in](https://casparser.in/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.cas_parser.api/cas-parser-java/0.8.0). +The REST API documentation can be found on [casparser.in](https://casparser.in/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.cas_parser.api/cas-parser-java/0.9.0). @@ -33,7 +33,7 @@ The REST API documentation can be found on [casparser.in](https://casparser.in/d ### Gradle ```kotlin -implementation("com.cas_parser.api:cas-parser-java:0.8.0") +implementation("com.cas_parser.api:cas-parser-java:0.9.0") ``` ### Maven @@ -42,7 +42,7 @@ implementation("com.cas_parser.api:cas-parser-java:0.8.0") com.cas_parser.api cas-parser-java - 0.8.0 + 0.9.0 ``` diff --git a/build.gradle.kts b/build.gradle.kts index 264d238..2471416 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -9,7 +9,7 @@ repositories { allprojects { group = "com.cas_parser.api" - version = "0.8.0" // x-release-please-version + version = "0.9.0" // x-release-please-version } subprojects { diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClient.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClient.kt index 41b761e..83082f6 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClient.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClient.kt @@ -94,7 +94,13 @@ interface CasParserClient { /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL @@ -209,7 +215,13 @@ interface CasParserClient { /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, + * `@hotmail.com`, `@live.com`, `@msn.com`, and localised variants such as + * `@hotmail.co.uk`, `@live.in`, `@hotmail.fr`. Any other address registered as a personal + * Microsoft account also works, including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsync.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsync.kt index 8c613f7..9508d18 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsync.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsync.kt @@ -94,7 +94,13 @@ interface CasParserClientAsync { /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL @@ -213,7 +219,13 @@ interface CasParserClientAsync { /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, + * `@hotmail.com`, `@live.com`, `@msn.com`, and localised variants such as + * `@hotmail.co.uk`, `@live.in`, `@hotmail.fr`. Any other address registered as a personal + * Microsoft account also works, including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsyncImpl.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsyncImpl.kt index 35c5a95..6eb9b52 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsyncImpl.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientAsyncImpl.kt @@ -137,7 +137,13 @@ class CasParserClientAsyncImpl(private val clientOptions: ClientOptions) : CasPa /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL @@ -289,7 +295,13 @@ class CasParserClientAsyncImpl(private val clientOptions: ClientOptions) : CasPa /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, + * `@hotmail.com`, `@live.com`, `@msn.com`, and localised variants such as + * `@hotmail.co.uk`, `@live.in`, `@hotmail.fr`. Any other address registered as a personal + * Microsoft account also works, including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientImpl.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientImpl.kt index 50bfe57..7e0d442 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientImpl.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/client/CasParserClientImpl.kt @@ -131,7 +131,13 @@ class CasParserClientImpl(private val clientOptions: ClientOptions) : CasParserC /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL @@ -283,7 +289,13 @@ class CasParserClientImpl(private val clientOptions: ClientOptions) : CasParserC /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, + * `@hotmail.com`, `@live.com`, `@msn.com`, and localised variants such as + * `@hotmail.co.uk`, `@live.in`, `@hotmail.fr`. Any other address registered as a personal + * Microsoft account also works, including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParams.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParams.kt index 12bb059..be98a8d 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParams.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParams.kt @@ -2,6 +2,7 @@ package com.cas_parser.api.models.inbox +import com.cas_parser.api.core.Enum import com.cas_parser.api.core.ExcludeMissing import com.cas_parser.api.core.JsonField import com.cas_parser.api.core.JsonMissing @@ -18,6 +19,7 @@ import com.fasterxml.jackson.annotation.JsonProperty import java.util.Collections import java.util.Objects import java.util.Optional +import kotlin.jvm.optionals.getOrNull /** * Initiate OAuth flow to connect user's email inbox. @@ -34,7 +36,10 @@ import java.util.Optional * - `error` - Error code (e.g., `access_denied`, `token_exchange_failed`) * - `state` - Your original state parameter * - * **Store the `inbox_token` client-side** and use it for all subsequent inbox API calls. + * **Store the `inbox_token` client-side** and use it for all subsequent inbox API calls. The token + * is long-lived (it stores an encrypted refresh token), so a single OAuth connect gives ongoing + * access to both historical and future CAS statements in the user's inbox. Reuse the same token + * until the user revokes access via `/v4/inbox/disconnect` or their provider's account settings. */ class InboxConnectEmailParams private constructor( @@ -51,6 +56,22 @@ private constructor( */ fun redirectUri(): String = body.redirectUri() + /** + * Mail provider to connect. Defaults to `gmail`. + * - `gmail` - Google accounts: `@gmail.com` and Google Workspace domains. + * - `outlook` - personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, `@live.com`, + * `@msn.com` and localised variants (`@hotmail.co.uk`, `@live.in`, `@hotmail.fr`). Any other + * address registered as a personal Microsoft account also works, including custom domains. + * - `zoho` - Zoho Mail accounts, including custom domains hosted on Zoho. + * + * Any unrecognised value is treated as `gmail`. The resolved provider is returned in the + * response. + * + * @throws CasParserInvalidDataException if the JSON field has an unexpected type (e.g. if the + * server responded with an unexpected value). + */ + fun provider(): Optional = body.provider() + /** * State parameter for CSRF protection (returned in redirect) * @@ -66,6 +87,13 @@ private constructor( */ fun _redirectUri(): JsonField = body._redirectUri() + /** + * Returns the raw JSON value of [provider]. + * + * Unlike [provider], this method doesn't throw if the JSON field has an unexpected type. + */ + fun _provider(): JsonField = body._provider() + /** * Returns the raw JSON value of [state]. * @@ -116,6 +144,7 @@ private constructor( * This is generally only useful if you are already constructing the body separately. * Otherwise, it's more convenient to use the top-level setters instead: * - [redirectUri] + * - [provider] * - [state] */ fun body(body: Body) = apply { this.body = body.toBuilder() } @@ -132,6 +161,29 @@ private constructor( */ fun redirectUri(redirectUri: JsonField) = apply { body.redirectUri(redirectUri) } + /** + * Mail provider to connect. Defaults to `gmail`. + * - `gmail` - Google accounts: `@gmail.com` and Google Workspace domains. + * - `outlook` - personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, `@live.com`, + * `@msn.com` and localised variants (`@hotmail.co.uk`, `@live.in`, `@hotmail.fr`). Any + * other address registered as a personal Microsoft account also works, including custom + * domains. + * - `zoho` - Zoho Mail accounts, including custom domains hosted on Zoho. + * + * Any unrecognised value is treated as `gmail`. The resolved provider is returned in the + * response. + */ + fun provider(provider: Provider) = apply { body.provider(provider) } + + /** + * Sets [Builder.provider] to an arbitrary JSON value. + * + * You should usually call [Builder.provider] with a well-typed [Provider] value instead. + * This method is primarily for setting the field to an undocumented or not yet supported + * value. + */ + fun provider(provider: JsonField) = apply { body.provider(provider) } + /** State parameter for CSRF protection (returned in redirect) */ fun state(state: String) = apply { body.state(state) } @@ -290,6 +342,7 @@ private constructor( @JsonCreator(mode = JsonCreator.Mode.DISABLED) private constructor( private val redirectUri: JsonField, + private val provider: JsonField, private val state: JsonField, private val additionalProperties: MutableMap, ) { @@ -299,8 +352,11 @@ private constructor( @JsonProperty("redirect_uri") @ExcludeMissing redirectUri: JsonField = JsonMissing.of(), + @JsonProperty("provider") + @ExcludeMissing + provider: JsonField = JsonMissing.of(), @JsonProperty("state") @ExcludeMissing state: JsonField = JsonMissing.of(), - ) : this(redirectUri, state, mutableMapOf()) + ) : this(redirectUri, provider, state, mutableMapOf()) /** * Your callback URL to receive the inbox_token (must be http or https) @@ -310,6 +366,23 @@ private constructor( */ fun redirectUri(): String = redirectUri.getRequired("redirect_uri") + /** + * Mail provider to connect. Defaults to `gmail`. + * - `gmail` - Google accounts: `@gmail.com` and Google Workspace domains. + * - `outlook` - personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, `@live.com`, + * `@msn.com` and localised variants (`@hotmail.co.uk`, `@live.in`, `@hotmail.fr`). Any + * other address registered as a personal Microsoft account also works, including custom + * domains. + * - `zoho` - Zoho Mail accounts, including custom domains hosted on Zoho. + * + * Any unrecognised value is treated as `gmail`. The resolved provider is returned in the + * response. + * + * @throws CasParserInvalidDataException if the JSON field has an unexpected type (e.g. if + * the server responded with an unexpected value). + */ + fun provider(): Optional = provider.getOptional("provider") + /** * State parameter for CSRF protection (returned in redirect) * @@ -327,6 +400,13 @@ private constructor( @ExcludeMissing fun _redirectUri(): JsonField = redirectUri + /** + * Returns the raw JSON value of [provider]. + * + * Unlike [provider], this method doesn't throw if the JSON field has an unexpected type. + */ + @JsonProperty("provider") @ExcludeMissing fun _provider(): JsonField = provider + /** * Returns the raw JSON value of [state]. * @@ -363,12 +443,14 @@ private constructor( class Builder internal constructor() { private var redirectUri: JsonField? = null + private var provider: JsonField = JsonMissing.of() private var state: JsonField = JsonMissing.of() private var additionalProperties: MutableMap = mutableMapOf() @JvmSynthetic internal fun from(body: Body) = apply { redirectUri = body.redirectUri + provider = body.provider state = body.state additionalProperties = body.additionalProperties.toMutableMap() } @@ -387,6 +469,29 @@ private constructor( this.redirectUri = redirectUri } + /** + * Mail provider to connect. Defaults to `gmail`. + * - `gmail` - Google accounts: `@gmail.com` and Google Workspace domains. + * - `outlook` - personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com` and localised variants (`@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`). Any other address registered as a personal Microsoft account also + * works, including custom domains. + * - `zoho` - Zoho Mail accounts, including custom domains hosted on Zoho. + * + * Any unrecognised value is treated as `gmail`. The resolved provider is returned in + * the response. + */ + fun provider(provider: Provider) = provider(JsonField.of(provider)) + + /** + * Sets [Builder.provider] to an arbitrary JSON value. + * + * You should usually call [Builder.provider] with a well-typed [Provider] value + * instead. This method is primarily for setting the field to an undocumented or not yet + * supported value. + */ + fun provider(provider: JsonField) = apply { this.provider = provider } + /** State parameter for CSRF protection (returned in redirect) */ fun state(state: String) = state(JsonField.of(state)) @@ -433,6 +538,7 @@ private constructor( fun build(): Body = Body( checkRequired("redirectUri", redirectUri), + provider, state, additionalProperties.toMutableMap(), ) @@ -455,6 +561,7 @@ private constructor( } redirectUri() + provider().ifPresent { it.validate() } state() validated = true } @@ -476,6 +583,7 @@ private constructor( @JvmSynthetic internal fun validity(): Int = (if (redirectUri.asKnown().isPresent) 1 else 0) + + (provider.asKnown().getOrNull()?.validity() ?: 0) + (if (state.asKnown().isPresent) 1 else 0) override fun equals(other: Any?): Boolean { @@ -485,16 +593,172 @@ private constructor( return other is Body && redirectUri == other.redirectUri && + provider == other.provider && state == other.state && additionalProperties == other.additionalProperties } - private val hashCode: Int by lazy { Objects.hash(redirectUri, state, additionalProperties) } + private val hashCode: Int by lazy { + Objects.hash(redirectUri, provider, state, additionalProperties) + } override fun hashCode(): Int = hashCode override fun toString() = - "Body{redirectUri=$redirectUri, state=$state, additionalProperties=$additionalProperties}" + "Body{redirectUri=$redirectUri, provider=$provider, state=$state, additionalProperties=$additionalProperties}" + } + + /** + * Mail provider to connect. Defaults to `gmail`. + * - `gmail` - Google accounts: `@gmail.com` and Google Workspace domains. + * - `outlook` - personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, `@live.com`, + * `@msn.com` and localised variants (`@hotmail.co.uk`, `@live.in`, `@hotmail.fr`). Any other + * address registered as a personal Microsoft account also works, including custom domains. + * - `zoho` - Zoho Mail accounts, including custom domains hosted on Zoho. + * + * Any unrecognised value is treated as `gmail`. The resolved provider is returned in the + * response. + */ + class Provider @JsonCreator private constructor(private val value: JsonField) : Enum { + + /** + * Returns this class instance's raw value. + * + * This is usually only useful if this instance was deserialized from data that doesn't + * match any known member, and you want to know that value. For example, if the SDK is on an + * older version than the API, then the API may respond with new members that the SDK is + * unaware of. + */ + @com.fasterxml.jackson.annotation.JsonValue fun _value(): JsonField = value + + companion object { + + @JvmField val GMAIL = of("gmail") + + @JvmField val OUTLOOK = of("outlook") + + @JvmField val ZOHO = of("zoho") + + @JvmStatic fun of(value: String) = Provider(JsonField.of(value)) + } + + /** An enum containing [Provider]'s known values. */ + enum class Known { + GMAIL, + OUTLOOK, + ZOHO, + } + + /** + * An enum containing [Provider]'s known values, as well as an [_UNKNOWN] member. + * + * An instance of [Provider] can contain an unknown value in a couple of cases: + * - It was deserialized from data that doesn't match any known member. For example, if the + * SDK is on an older version than the API, then the API may respond with new members that + * the SDK is unaware of. + * - It was constructed with an arbitrary value using the [of] method. + */ + enum class Value { + GMAIL, + OUTLOOK, + ZOHO, + /** An enum member indicating that [Provider] was instantiated with an unknown value. */ + _UNKNOWN, + } + + /** + * Returns an enum member corresponding to this class instance's value, or [Value._UNKNOWN] + * if the class was instantiated with an unknown value. + * + * Use the [known] method instead if you're certain the value is always known or if you want + * to throw for the unknown case. + */ + fun value(): Value = + when (this) { + GMAIL -> Value.GMAIL + OUTLOOK -> Value.OUTLOOK + ZOHO -> Value.ZOHO + else -> Value._UNKNOWN + } + + /** + * Returns an enum member corresponding to this class instance's value. + * + * Use the [value] method instead if you're uncertain the value is always known and don't + * want to throw for the unknown case. + * + * @throws CasParserInvalidDataException if this class instance's value is a not a known + * member. + */ + fun known(): Known = + when (this) { + GMAIL -> Known.GMAIL + OUTLOOK -> Known.OUTLOOK + ZOHO -> Known.ZOHO + else -> throw CasParserInvalidDataException("Unknown Provider: $value") + } + + /** + * Returns this class instance's primitive wire representation. + * + * This differs from the [toString] method because that method is primarily for debugging + * and generally doesn't throw. + * + * @throws CasParserInvalidDataException if this class instance's value does not have the + * expected primitive type. + */ + fun asString(): String = + _value().asString().orElseThrow { + CasParserInvalidDataException("Value is not a String") + } + + private var validated: Boolean = false + + /** + * Validates that the types of all values in this object match their expected types + * recursively. + * + * This method is _not_ forwards compatible with new types from the API for existing fields. + * + * @throws CasParserInvalidDataException if any value type in this object doesn't match its + * expected type. + */ + fun validate(): Provider = apply { + if (validated) { + return@apply + } + + known() + validated = true + } + + fun isValid(): Boolean = + try { + validate() + true + } catch (e: CasParserInvalidDataException) { + false + } + + /** + * Returns a score indicating how many valid values are contained in this object + * recursively. + * + * Used for best match union deserialization. + */ + @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1 + + override fun equals(other: Any?): Boolean { + if (this === other) { + return true + } + + return other is Provider && value == other.value + } + + override fun hashCode() = value.hashCode() + + override fun toString() = value.toString() } override fun equals(other: Any?): Boolean { diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponse.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponse.kt index 968248e..98ae215 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponse.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponse.kt @@ -2,6 +2,7 @@ package com.cas_parser.api.models.inbox +import com.cas_parser.api.core.Enum import com.cas_parser.api.core.ExcludeMissing import com.cas_parser.api.core.JsonField import com.cas_parser.api.core.JsonMissing @@ -14,12 +15,14 @@ import com.fasterxml.jackson.annotation.JsonProperty import java.util.Collections import java.util.Objects import java.util.Optional +import kotlin.jvm.optionals.getOrNull class InboxConnectEmailResponse @JsonCreator(mode = JsonCreator.Mode.DISABLED) private constructor( private val expiresIn: JsonField, private val oauthUrl: JsonField, + private val provider: JsonField, private val status: JsonField, private val additionalProperties: MutableMap, ) { @@ -28,8 +31,9 @@ private constructor( private constructor( @JsonProperty("expires_in") @ExcludeMissing expiresIn: JsonField = JsonMissing.of(), @JsonProperty("oauth_url") @ExcludeMissing oauthUrl: JsonField = JsonMissing.of(), + @JsonProperty("provider") @ExcludeMissing provider: JsonField = JsonMissing.of(), @JsonProperty("status") @ExcludeMissing status: JsonField = JsonMissing.of(), - ) : this(expiresIn, oauthUrl, status, mutableMapOf()) + ) : this(expiresIn, oauthUrl, provider, status, mutableMapOf()) /** * Seconds until the OAuth URL expires (typically 10 minutes) @@ -47,6 +51,14 @@ private constructor( */ fun oauthUrl(): Optional = oauthUrl.getOptional("oauth_url") + /** + * The provider this OAuth URL was generated for + * + * @throws CasParserInvalidDataException if the JSON field has an unexpected type (e.g. if the + * server responded with an unexpected value). + */ + fun provider(): Optional = provider.getOptional("provider") + /** * @throws CasParserInvalidDataException if the JSON field has an unexpected type (e.g. if the * server responded with an unexpected value). @@ -67,6 +79,13 @@ private constructor( */ @JsonProperty("oauth_url") @ExcludeMissing fun _oauthUrl(): JsonField = oauthUrl + /** + * Returns the raw JSON value of [provider]. + * + * Unlike [provider], this method doesn't throw if the JSON field has an unexpected type. + */ + @JsonProperty("provider") @ExcludeMissing fun _provider(): JsonField = provider + /** * Returns the raw JSON value of [status]. * @@ -99,6 +118,7 @@ private constructor( private var expiresIn: JsonField = JsonMissing.of() private var oauthUrl: JsonField = JsonMissing.of() + private var provider: JsonField = JsonMissing.of() private var status: JsonField = JsonMissing.of() private var additionalProperties: MutableMap = mutableMapOf() @@ -106,6 +126,7 @@ private constructor( internal fun from(inboxConnectEmailResponse: InboxConnectEmailResponse) = apply { expiresIn = inboxConnectEmailResponse.expiresIn oauthUrl = inboxConnectEmailResponse.oauthUrl + provider = inboxConnectEmailResponse.provider status = inboxConnectEmailResponse.status additionalProperties = inboxConnectEmailResponse.additionalProperties.toMutableMap() } @@ -132,6 +153,18 @@ private constructor( */ fun oauthUrl(oauthUrl: JsonField) = apply { this.oauthUrl = oauthUrl } + /** The provider this OAuth URL was generated for */ + fun provider(provider: Provider) = provider(JsonField.of(provider)) + + /** + * Sets [Builder.provider] to an arbitrary JSON value. + * + * You should usually call [Builder.provider] with a well-typed [Provider] value instead. + * This method is primarily for setting the field to an undocumented or not yet supported + * value. + */ + fun provider(provider: JsonField) = apply { this.provider = provider } + fun status(status: String) = status(JsonField.of(status)) /** @@ -170,6 +203,7 @@ private constructor( InboxConnectEmailResponse( expiresIn, oauthUrl, + provider, status, additionalProperties.toMutableMap(), ) @@ -192,6 +226,7 @@ private constructor( expiresIn() oauthUrl() + provider().ifPresent { it.validate() } status() validated = true } @@ -213,8 +248,152 @@ private constructor( internal fun validity(): Int = (if (expiresIn.asKnown().isPresent) 1 else 0) + (if (oauthUrl.asKnown().isPresent) 1 else 0) + + (provider.asKnown().getOrNull()?.validity() ?: 0) + (if (status.asKnown().isPresent) 1 else 0) + /** The provider this OAuth URL was generated for */ + class Provider @JsonCreator private constructor(private val value: JsonField) : Enum { + + /** + * Returns this class instance's raw value. + * + * This is usually only useful if this instance was deserialized from data that doesn't + * match any known member, and you want to know that value. For example, if the SDK is on an + * older version than the API, then the API may respond with new members that the SDK is + * unaware of. + */ + @com.fasterxml.jackson.annotation.JsonValue fun _value(): JsonField = value + + companion object { + + @JvmField val GMAIL = of("gmail") + + @JvmField val OUTLOOK = of("outlook") + + @JvmField val ZOHO = of("zoho") + + @JvmStatic fun of(value: String) = Provider(JsonField.of(value)) + } + + /** An enum containing [Provider]'s known values. */ + enum class Known { + GMAIL, + OUTLOOK, + ZOHO, + } + + /** + * An enum containing [Provider]'s known values, as well as an [_UNKNOWN] member. + * + * An instance of [Provider] can contain an unknown value in a couple of cases: + * - It was deserialized from data that doesn't match any known member. For example, if the + * SDK is on an older version than the API, then the API may respond with new members that + * the SDK is unaware of. + * - It was constructed with an arbitrary value using the [of] method. + */ + enum class Value { + GMAIL, + OUTLOOK, + ZOHO, + /** An enum member indicating that [Provider] was instantiated with an unknown value. */ + _UNKNOWN, + } + + /** + * Returns an enum member corresponding to this class instance's value, or [Value._UNKNOWN] + * if the class was instantiated with an unknown value. + * + * Use the [known] method instead if you're certain the value is always known or if you want + * to throw for the unknown case. + */ + fun value(): Value = + when (this) { + GMAIL -> Value.GMAIL + OUTLOOK -> Value.OUTLOOK + ZOHO -> Value.ZOHO + else -> Value._UNKNOWN + } + + /** + * Returns an enum member corresponding to this class instance's value. + * + * Use the [value] method instead if you're uncertain the value is always known and don't + * want to throw for the unknown case. + * + * @throws CasParserInvalidDataException if this class instance's value is a not a known + * member. + */ + fun known(): Known = + when (this) { + GMAIL -> Known.GMAIL + OUTLOOK -> Known.OUTLOOK + ZOHO -> Known.ZOHO + else -> throw CasParserInvalidDataException("Unknown Provider: $value") + } + + /** + * Returns this class instance's primitive wire representation. + * + * This differs from the [toString] method because that method is primarily for debugging + * and generally doesn't throw. + * + * @throws CasParserInvalidDataException if this class instance's value does not have the + * expected primitive type. + */ + fun asString(): String = + _value().asString().orElseThrow { + CasParserInvalidDataException("Value is not a String") + } + + private var validated: Boolean = false + + /** + * Validates that the types of all values in this object match their expected types + * recursively. + * + * This method is _not_ forwards compatible with new types from the API for existing fields. + * + * @throws CasParserInvalidDataException if any value type in this object doesn't match its + * expected type. + */ + fun validate(): Provider = apply { + if (validated) { + return@apply + } + + known() + validated = true + } + + fun isValid(): Boolean = + try { + validate() + true + } catch (e: CasParserInvalidDataException) { + false + } + + /** + * Returns a score indicating how many valid values are contained in this object + * recursively. + * + * Used for best match union deserialization. + */ + @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1 + + override fun equals(other: Any?): Boolean { + if (this === other) { + return true + } + + return other is Provider && value == other.value + } + + override fun hashCode() = value.hashCode() + + override fun toString() = value.toString() + } + override fun equals(other: Any?): Boolean { if (this === other) { return true @@ -223,16 +402,17 @@ private constructor( return other is InboxConnectEmailResponse && expiresIn == other.expiresIn && oauthUrl == other.oauthUrl && + provider == other.provider && status == other.status && additionalProperties == other.additionalProperties } private val hashCode: Int by lazy { - Objects.hash(expiresIn, oauthUrl, status, additionalProperties) + Objects.hash(expiresIn, oauthUrl, provider, status, additionalProperties) } override fun hashCode(): Int = hashCode override fun toString() = - "InboxConnectEmailResponse{expiresIn=$expiresIn, oauthUrl=$oauthUrl, status=$status, additionalProperties=$additionalProperties}" + "InboxConnectEmailResponse{expiresIn=$expiresIn, oauthUrl=$oauthUrl, provider=$provider, status=$status, additionalProperties=$additionalProperties}" } diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxListCasFilesResponse.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxListCasFilesResponse.kt index 2240910..5d24622 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxListCasFilesResponse.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/models/inbox/InboxListCasFilesResponse.kt @@ -294,7 +294,7 @@ private constructor( /** * URL expiration time in seconds. Defaults vary by source: - * - Gmail Inbox Import: 86400 (24h) + * - Email Inbox Import (Gmail, Outlook, Zoho): 86400 (24h) * - Inbound Email with `callback_url` set: 172800 (48h) * - Inbound Email without `callback_url`: aligned with the session TTL (~30 min) * @@ -490,7 +490,7 @@ private constructor( /** * URL expiration time in seconds. Defaults vary by source: - * - Gmail Inbox Import: 86400 (24h) + * - Email Inbox Import (Gmail, Outlook, Zoho): 86400 (24h) * - Inbound Email with `callback_url` set: 172800 (48h) * - Inbound Email without `callback_url`: aligned with the session TTL (~30 min) */ diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsync.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsync.kt index d2a2a85..48499d1 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsync.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsync.kt @@ -19,7 +19,13 @@ import java.util.function.Consumer /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL @@ -79,7 +85,11 @@ interface InboxServiceAsync { * - `error` - Error code (e.g., `access_denied`, `token_exchange_failed`) * - `state` - Your original state parameter * - * **Store the `inbox_token` client-side** and use it for all subsequent inbox API calls. + * **Store the `inbox_token` client-side** and use it for all subsequent inbox API calls. The + * token is long-lived (it stores an encrypted refresh token), so a single OAuth connect gives + * ongoing access to both historical and future CAS statements in the user's inbox. Reuse the + * same token until the user revokes access via `/v4/inbox/disconnect` or their provider's + * account settings. */ fun connectEmail( params: InboxConnectEmailParams diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncImpl.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncImpl.kt index f3f2599..429fdab 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncImpl.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncImpl.kt @@ -29,7 +29,13 @@ import java.util.function.Consumer /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxService.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxService.kt index 051365a..0f13697 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxService.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxService.kt @@ -19,7 +19,13 @@ import java.util.function.Consumer /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL @@ -78,7 +84,11 @@ interface InboxService { * - `error` - Error code (e.g., `access_denied`, `token_exchange_failed`) * - `state` - Your original state parameter * - * **Store the `inbox_token` client-side** and use it for all subsequent inbox API calls. + * **Store the `inbox_token` client-side** and use it for all subsequent inbox API calls. The + * token is long-lived (it stores an encrypted refresh token), so a single OAuth connect gives + * ongoing access to both historical and future CAS statements in the user's inbox. Reuse the + * same token until the user revokes access via `/v4/inbox/disconnect` or their provider's + * account settings. */ fun connectEmail(params: InboxConnectEmailParams): InboxConnectEmailResponse = connectEmail(params, RequestOptions.none()) diff --git a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxServiceImpl.kt b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxServiceImpl.kt index 4abb1e6..0a9f7fd 100644 --- a/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxServiceImpl.kt +++ b/cas-parser-java-core/src/main/kotlin/com/cas_parser/api/services/blocking/InboxServiceImpl.kt @@ -28,7 +28,13 @@ import java.util.function.Consumer /** * Endpoints for importing CAS files directly from user email inboxes. * - * **Supported Providers:** Gmail (more coming soon) + * **Supported Providers:** + * - **Gmail** (`gmail`, default) — `@gmail.com` and Google Workspace domains + * - **Microsoft** (`outlook`) — personal Microsoft accounts: `@outlook.com`, `@hotmail.com`, + * `@live.com`, `@msn.com`, and localised variants such as `@hotmail.co.uk`, `@live.in`, + * `@hotmail.fr`. Any other address registered as a personal Microsoft account also works, + * including custom domains. + * - **Zoho Mail** (`zoho`) — Zoho-hosted mailboxes, including custom domains * * **How it works:** * 1. Call `POST /v4/inbox/connect` to get an OAuth URL diff --git a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParamsTest.kt b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParamsTest.kt index 568051f..0808a2b 100644 --- a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParamsTest.kt +++ b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailParamsTest.kt @@ -11,6 +11,7 @@ internal class InboxConnectEmailParamsTest { fun create() { InboxConnectEmailParams.builder() .redirectUri("https://yourapp.com/oauth-callback") + .provider(InboxConnectEmailParams.Provider.OUTLOOK) .state("abc123") .build() } @@ -20,12 +21,14 @@ internal class InboxConnectEmailParamsTest { val params = InboxConnectEmailParams.builder() .redirectUri("https://yourapp.com/oauth-callback") + .provider(InboxConnectEmailParams.Provider.OUTLOOK) .state("abc123") .build() val body = params._body() assertThat(body.redirectUri()).isEqualTo("https://yourapp.com/oauth-callback") + assertThat(body.provider()).contains(InboxConnectEmailParams.Provider.OUTLOOK) assertThat(body.state()).contains("abc123") } diff --git a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponseTest.kt b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponseTest.kt index 2a2f511..3025036 100644 --- a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponseTest.kt +++ b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/models/inbox/InboxConnectEmailResponseTest.kt @@ -15,12 +15,15 @@ internal class InboxConnectEmailResponseTest { InboxConnectEmailResponse.builder() .expiresIn(600L) .oauthUrl("https://accounts.google.com/o/oauth2/v2/auth?client_id=...") + .provider(InboxConnectEmailResponse.Provider.OUTLOOK) .status("success") .build() assertThat(inboxConnectEmailResponse.expiresIn()).contains(600L) assertThat(inboxConnectEmailResponse.oauthUrl()) .contains("https://accounts.google.com/o/oauth2/v2/auth?client_id=...") + assertThat(inboxConnectEmailResponse.provider()) + .contains(InboxConnectEmailResponse.Provider.OUTLOOK) assertThat(inboxConnectEmailResponse.status()).contains("success") } @@ -31,6 +34,7 @@ internal class InboxConnectEmailResponseTest { InboxConnectEmailResponse.builder() .expiresIn(600L) .oauthUrl("https://accounts.google.com/o/oauth2/v2/auth?client_id=...") + .provider(InboxConnectEmailResponse.Provider.OUTLOOK) .status("success") .build() diff --git a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncTest.kt b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncTest.kt index 47362c1..429cea2 100644 --- a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncTest.kt +++ b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/async/InboxServiceAsyncTest.kt @@ -38,6 +38,7 @@ internal class InboxServiceAsyncTest { inboxServiceAsync.connectEmail( InboxConnectEmailParams.builder() .redirectUri("https://yourapp.com/oauth-callback") + .provider(InboxConnectEmailParams.Provider.OUTLOOK) .state("abc123") .build() ) diff --git a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/blocking/InboxServiceTest.kt b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/blocking/InboxServiceTest.kt index dc041fb..1787cf1 100644 --- a/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/blocking/InboxServiceTest.kt +++ b/cas-parser-java-core/src/test/kotlin/com/cas_parser/api/services/blocking/InboxServiceTest.kt @@ -37,6 +37,7 @@ internal class InboxServiceTest { inboxService.connectEmail( InboxConnectEmailParams.builder() .redirectUri("https://yourapp.com/oauth-callback") + .provider(InboxConnectEmailParams.Provider.OUTLOOK) .state("abc123") .build() )