Upgrade Fern generator (#249)

This change is the result of re-generating the SDK
using the latest v3 Fern generator (`3.27.6`) and
re-applying the `BaseClient` builder fixes.

---------

Co-authored-by: fern-api[bot] <115122769+fern-api[bot]@users.noreply.github.com>
Co-authored-by: Jay Vercellone <jay.vercellone@workday.com>

Author: fern-api[bot]

.fern/metadata.json

@@ -0,0 +1,13 @@
+{
+  "cliVersion": "3.5.0",
+  "generatorName": "fernapi/fern-java-sdk",
+  "generatorVersion": "3.27.6",
+  "generatorConfig": {
+    "publish-to": "central",
+    "client-class-name": "BaseClient",
+    "custom-dependencies": [
+      "api org.apache.commons:commons-text:1.13.1"
+    ]
+  },
+  "sdkVersion": "1.2.0"
+}

.fernignore

@@ -10,8 +10,8 @@ LICENSE
 reference.md
 
 # Base client files (temporary)
-# src/main/java/com/pipedream/api/AsyncBaseClientBuilder.java
-# src/main/java/com/pipedream/api/BaseClientBuilder.java
+src/main/java/com/pipedream/api/AsyncBaseClientBuilder.java
+src/main/java/com/pipedream/api/BaseClientBuilder.java
 
 # Custom Pipedream client files
 src/main/java/com/pipedream/api/AsyncPipedreamClient.java
@@ -45,3 +45,8 @@ src/main/java/com/pipedream/api/types/HTTPAuthType.java
 src/test/java/com/pipedream/api/OauthTokensWireTest.java
 src/test/java/com/pipedream/api/ProxyClientWireTest.java
 src/test/java/com/pipedream/api/TokensWireTest.java
+
+# Test utilities (JDK-only mock-server shim used by wire tests)
+src/test/java/com/pipedream/api/testutil/MockResponse.java
+src/test/java/com/pipedream/api/testutil/MockWebServer.java
+src/test/java/com/pipedream/api/testutil/RecordedRequest.java

CLAUDE.md

@@ -0,0 +1,188 @@
+# CLAUDE.md
+
+Guidance for working in this repo with Claude Code (or any agent).
+
+## What this repo is
+
+Official Pipedream Java SDK. Most of the source tree is generated by **Fern**
+(generator: `fernapi/fern-java-sdk`, version pinned in `.fern/metadata.json`). A
+small set of files are hand-maintained on top of the generated code; they are
+listed explicitly in `.fernignore` and are the only files Fern won't overwrite
+on regeneration.
+
+## The single most important rule
+
+**If a file is not in `.fernignore`, do not edit it.** Fern owns it and the next
+regeneration will discard your changes. This includes:
+
+- `build.gradle`, `settings.gradle`, `gradle/**`
+- The entire `.fern/` directory (incl. `.fern/metadata.json`)
+- `README.md`
+- Every file under `src/main/java/com/pipedream/api/` and
+  `src/test/java/com/pipedream/api/` not in `.fernignore`
+
+If you need to change something in a generated file, the change has to happen
+**upstream of this repo** — in the Fern API definition / generator config the
+bot reads from — and arrive here via the next regeneration. Locally, your
+options are: add the file to `.fernignore` (and own it going forward), or absorb
+the change into a hand-maintained wrapper. When in doubt, ask.
+
+## What's hand-maintained
+
+`.fernignore` is the source of truth. As of this writing:
+
+| Path                                                                                                          | Purpose                                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/main/java/com/pipedream/api/PipedreamClient.java`                                                        | Public sync entry point. Wraps generated `BaseClient`, adds `workflows()` and `rawAccessToken()`, exposes the env-var-aware `builder()` factory.                          |
+| `src/main/java/com/pipedream/api/PipedreamClientBuilder.java`                                                 | Backward-compatible builder. Owns the `clientId/clientSecret/token/scope` fluent surface and orchestrates OAuth (`OAuthTokenSupplier`) or token-header auth in `build()`. |
+| `src/main/java/com/pipedream/api/AsyncPipedreamClient.java`, `AsyncPipedreamClientBuilder.java`               | Async mirrors of the above.                                                                                                                                               |
+| `src/main/java/com/pipedream/api/BaseClientBuilder.java`, `AsyncBaseClientBuilder.java`                       | Re-protected after the 3.27.6 regen so the generic `<T extends ...<T>>` self-type the Pipedream subclasses depend on cannot silently disappear in a future regen.         |
+| `src/main/java/com/pipedream/api/resources/proxy/**`                                                          | Custom HTTP proxy implementation (request types, sync/async clients, `ProxyResponse`).                                                                                    |
+| `src/main/java/com/pipedream/api/resources/workflows/**`, `types/HTTPAuthType.java`                           | Custom workflow invocation surface.                                                                                                                                       |
+| `src/test/java/com/pipedream/api/OauthTokensWireTest.java`, `ProxyClientWireTest.java`, `TokensWireTest.java` | Wire tests we own.                                                                                                                                                        |
+| `src/test/java/com/pipedream/api/testutil/MockWebServer.java`, `MockResponse.java`, `RecordedRequest.java`    | JDK `HttpServer`-based mock-server shim. Replaces `okhttp3.mockwebserver` so we don't need to thread an extra test dep through the Fern-managed `build.gradle`.           |
+| `reference.md`, `LICENSE`, `.github/workflows/auto-close-empty-prs.yml`                                       | Docs / legal / CI we control.                                                                                                                                             |
+
+If you add a new hand-maintained file, list it in `.fernignore` in the same
+commit.
+
+## Adding dependencies
+
+`build.gradle` and `.fern/metadata.json` (where the `custom-dependencies` array
+lives) are both Fern-managed — neither can be edited in this repo. Adding a
+runtime or test dependency means changing the upstream Fern config and waiting
+for the next regen.
+
+**If you need the dep in this repo before then, do not "bridge" by editing
+`build.gradle` — find another path.** For test-only dependencies, prefer the JDK
+or write a shim in `src/test/java/com/pipedream/api/testutil/` (already
+`.fernignore`-protected). The existing `MockWebServer` shim is the worked
+example: it sidesteps `okhttp3.mockwebserver` so we don't need a test dep at
+all.
+
+## Versioning
+
+The version is propagated by Fern from upstream config into `build.gradle` and
+`.fern/metadata.json`'s `sdkVersion`. Don't bump it in either place locally —
+the bump has to happen upstream and ride in via regen.
+
+This SDK currently follows the convention: any net-new public API surface is a
+**minor bump** (no breaking change), any removal/rename is a **major bump**.
+Backward compatibility for the `PipedreamClient.builder()` chain is a hard
+requirement — see the next section.
+
+## Public API contract (PipedreamClient)
+
+The supported customer-facing API on the sync side (mirror exists on async):
+
+```java
+// Env-aware: reads PIPEDREAM_CLIENT_ID, _CLIENT_SECRET, _BASE_URL,
+// _PROJECT_ENVIRONMENT, _PROJECT_ID
+PipedreamClient.builder()
+    .clientId("...")        // override env default
+    .clientSecret("...")    // override env default
+    .scope("read:accounts") // OAuth progressive scopes (added 1.2.0)
+    .token("eyJ...")        // bypass OAuth entirely; precedence over creds
+    .url("https://...")     // alias: baseUrl(...)
+    .projectId("...")
+    .projectEnvironment("...")
+    .timeout(60).maxRetries(2)
+    .httpClient(myOkHttpClient)
+    .addHeader("X-Foo", "bar")
+    .build();
+```
+
+Build-time precedence in `PipedreamClientBuilder.build()`:
+
+1. `token != null` → `Authorization: Bearer <token>`
+2. else `clientId != null && clientSecret != null` → OAuth client-credentials
+   via `OAuthTokenSupplier` + `OauthTokensClient` (lazy on first request)
+3. else → no auth header
+
+`.clientId(null) / .clientSecret(null)` is a supported way to suppress the
+env-var defaults for tests.
+
+## Why we don't add `withCredentials`/`withToken` to PipedreamClient
+
+The generated `BaseClient` exposes `static withCredentials(...)` and `static
+withToken(...)` returning `BaseClientBuilder._CredentialsAuth` and `_TokenAuth`.
+Java's static-method-hiding rules require any same-name static on a subclass to
+have a covariant return type. `PipedreamClientBuilder` is not a subtype of
+`_CredentialsAuth` / `_TokenAuth`, so adding those statics on `PipedreamClient`
+won't compile. The hybrid surface above (env-aware `builder()` plus
+`.token(...)` and `.scope(...)`) is the workaround.
+
+Customers wanting the Fern-native factory style can still call
+`BaseClient.withCredentials(...)` / `BaseClient.withToken(...)` directly — they
+just lose the `workflows()` accessor.
+
+## Testing
+
+```bash
+./gradlew test           # full unit + wire suite (28 tests as of 1.2.0)
+./gradlew compileJava    # main sources only
+./gradlew clean test     # forces re-run; useful when fiddling with test code
+```
+
+Wire tests use the `com.pipedream.api.testutil` shim — `MockWebServer` is backed
+by `com.sun.net.httpserver.HttpServer`, no external dep. The shim only
+implements the surface the tests use (`start`, `shutdown`, `url`, `enqueue`,
+`takeRequest`, plus `MockResponse` setters and `RecordedRequest` getters).
+Extend it if a test needs more.
+
+When writing a wire test, prefer constructing the client via
+`PipedreamClient.builder().url(server.url("/").toString()).build()` over `new
+PipedreamClientBuilder()` — it's the public factory and matches how customers
+wire things up. Heads up: `builder()` reads `PIPEDREAM_CLIENT_ID` /
+`PIPEDREAM_CLIENT_SECRET` from the environment, so if those are set on the
+machine the OAuth flow will fire on the first request and consume an extra
+queued response. CI is clean; locally, unset them or pass explicit
+`.clientId(null).clientSecret(null)`.
+
+`./gradlew spotlessCheck` is **broken** on newer JDKs (Palantir Java Format
+calls `JCImport.getQualifiedIdentifier()` which the JDK has removed). It was
+broken before the recent regen too. Don't try to "fix" it as part of an
+unrelated change — it's a separate cleanup that needs the spotless / PJF plugin
+versions bumped, and those live in the Fern-generated `build.gradle`.
+
+## Java compatibility
+
+`sourceCompatibility` / `targetCompatibility` are pinned at Java 8. Keep new
+hand-written code Java-8-compatible: no `var`, no `record`, no `List.of`, no
+`InputStream.readAllBytes()` (see the helper in `ProxyClientWireTest`).
+
+## After a Fern regen
+
+When a Fern bot PR lands, expect:
+
+1. `build.gradle` to change (deps, version, sometimes plugins).
+2. `README.md` to be regenerated wholesale.
+3. Generated source under `src/main/java/com/pipedream/api/` to churn.
+4. The files in `.fernignore` to stay untouched.
+
+Sanity checks before merging a regen PR:
+
+- `./gradlew compileJava` is green.
+- `./gradlew test` is green.
+- The public API on `PipedreamClient` / `AsyncPipedreamClient` (see contract
+  section above) still compiles. Inspect any change to `BaseClient` /
+  `AsyncBaseClient` static factories carefully — those are what the wrappers
+  build on top of.
+- The dep set in the regenerated `build.gradle` still has everything the wire
+  tests need (today: nothing beyond what Fern emits, since the `testutil/` shim
+  removed the `okhttp3.mockwebserver` requirement).
+
+## Don't
+
+- Don't edit `build.gradle` or `.fern/metadata.json` to add deps, change
+  versions, or touch plugins/config. Both are Fern-managed; the change has to
+  happen upstream.
+- Don't edit `README.md`. It's regenerated. Put project-specific docs in
+  `reference.md` (which is in `.fernignore`).
+- Don't add backward-compatibility shims that mutate generated code. If the
+  generated API changed in a way that breaks customers, absorb the change in the
+  hand-maintained wrappers (`PipedreamClient*`) — that's what they exist for.
+- Don't introduce new test dependencies via `build.gradle`. Use the JDK or
+  extend `testutil/`.
+- Don't try to add `static withCredentials(...)` / `static withToken(...)` on
+  `PipedreamClient` — it won't compile (see the rationale section above).

README.md

@@ -28,7 +28,7 @@ Add the dependency in your `build.gradle` file:
 
 ```groovy
 dependencies {
-  implementation 'com.pipedream:pipedream:1.1.14'
+  implementation 'com.pipedream:pipedream'
 }
 ```
 
@@ -40,7 +40,7 @@ Add the dependency in your `pom.xml` file:
 <dependency>
   <groupId>com.pipedream</groupId>
   <artifactId>pipedream</artifactId>
-  <version>1.1.14</version>
+  <version>1.2.0</version>
 </dependency>
 ```
 
@@ -56,12 +56,10 @@ import com.pipedream.api.resources.actions.requests.RunActionOpts;
 
 public class Example {
     public static void main(String[] args) {
-        BaseClient client = BaseClient
-            .builder()
-            .clientId("<clientId>")
-            .clientSecret("<clientSecret>")
+        BaseClient client = BaseClient.withCredentials("<clientId>", "<clientSecret>")
             .projectId("YOUR_PROJECT_ID")
-            .build();
+            .build()
+        ;
 
         client.actions().run(
             RunActionOpts
@@ -73,6 +71,29 @@ public class Example {
     }
 }
 ```
+## Authentication
+
+This SDK supports two authentication methods:
+
+### Option 1: Direct Bearer Token
+
+If you already have a valid access token, you can use it directly:
+
+```java
+BaseClient client = BaseClient.withToken("your-access-token")
+    .url("https://api.example.com")
+    .build();
+```
+
+### Option 2: OAuth Client Credentials
+
+The SDK can automatically handle token acquisition and refresh:
+
+```java
+BaseClient client = BaseClient.withCredentials("client-id", "client-secret")
+    .url("https://api.example.com")
+    .build();
+```
 
 ## Environments
 
@@ -119,7 +140,7 @@ try{
 
 ### Custom Client
 
-This SDK is built to work with any instance of `OkHttpClient`. By default, if no client is provided, the SDK will construct one. 
+This SDK is built to work with any instance of `OkHttpClient`. By default, if no client is provided, the SDK will construct one.
 However, you can pass your own client like so:
 
 ```java
@@ -138,7 +159,9 @@ BaseClient client = BaseClient
 
 The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
 as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
-retry limit (default: 2).
+retry limit (default: 2). Before defaulting to exponential backoff, the SDK will first attempt to respect
+the `Retry-After` header (as either in seconds or as an HTTP date), and then the `X-RateLimit-Reset` header
+(as a Unix timestamp in epoch seconds); failing both of those, it will fall back to exponential backoff.
 
 A request is deemed retryable when any of the following HTTP status codes is returned:
 
@@ -160,23 +183,22 @@ BaseClient client = BaseClient
 ### Timeouts
 
 The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.
-
 ```java
 import com.pipedream.api.BaseClient;
 import com.pipedream.api.core.RequestOptions;
 
 // Client level
 BaseClient client = BaseClient
     .builder()
-    .timeout(10)
+    .timeout(60)
     .build();
 
 // Request level
 client.actions().run(
     ...,
     RequestOptions
         .builder()
-        .timeout(10)
+        .timeout(60)
         .build()
 );
 ```
@@ -207,6 +229,19 @@ client.actions().run(
 );
 ```
 
+### Access Raw Response Data
+
+The SDK provides access to raw response data, including headers, through the `withRawResponse()` method.
+The `withRawResponse()` method returns a raw client that wraps all responses with `body()` and `headers()` methods.
+(A normal client's `response` is identical to a raw client's `response.body()`.)
+
+```java
+RunHttpResponse response = client.actions().withRawResponse().run(...);
+
+System.out.println(response.body());
+System.out.println(response.headers().get("X-My-Header"));
+```
+
 ## Contributing
 
 While we value open-source contributions to this SDK, this library is generated programmatically.

build.gradle

@@ -14,15 +14,14 @@ repositories {
 }
 
 dependencies {
-    api 'com.squareup.okhttp3:okhttp:4.12.0'
-    api 'com.fasterxml.jackson.core:jackson-databind:2.17.2'
-    api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.17.2'
-    api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.17.2'
+    api 'com.squareup.okhttp3:okhttp:5.2.1'
+    api 'com.fasterxml.jackson.core:jackson-databind:2.18.2'
+    api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.2'
+    api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.2'
     testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
     testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.8.2'
     testImplementation 'org.junit.jupiter:junit-jupiter-params:5.8.2'
     api 'org.apache.commons:commons-text:1.13.1'
-    testImplementation 'com.squareup.okhttp3:mockwebserver:4.12.0'
 }
 
 
@@ -49,7 +48,7 @@ java {
 
 group = 'com.pipedream'
 
-version = '1.1.14'
+version = '1.2.0'
 
 jar {
     dependsOn(":generatePomFileForMavenPublication")
@@ -80,7 +79,7 @@ publishing {
         maven(MavenPublication) {
             groupId = 'com.pipedream'
             artifactId = 'pipedream'
-            version = '1.1.14'
+            version = '1.2.0'
             from components.java
             pom {
                 name = 'pipedream'