Restore base client builder interfaces

Author: jverce

.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

@@ -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>
 ```
 

build.gradle

@@ -48,7 +48,7 @@ java {
 
 group = 'com.pipedream'
 
-version = '1.1.14'
+version = '1.2.0'
 
 jar {
     dependsOn(":generatePomFileForMavenPublication")
@@ -79,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'

src/main/java/com/pipedream/api/AsyncBaseClientBuilder.java

@@ -12,7 +12,7 @@
 import java.util.Optional;
 import okhttp3.OkHttpClient;
 
-public class AsyncBaseClientBuilder {
+public class AsyncBaseClientBuilder<T extends AsyncBaseClientBuilder<T>> {
     private Optional<Integer> timeout = Optional.empty();
 
     private Optional<Integer> maxRetries = Optional.empty();
@@ -54,43 +54,43 @@ public static _CredentialsAuth withCredentials(String clientId, String clientSec
     /**
      * Sets projectEnvironment
      */
-    public AsyncBaseClientBuilder projectEnvironment(String projectEnvironment) {
+    public T projectEnvironment(String projectEnvironment) {
         this.projectEnvironment = projectEnvironment;
-        return this;
+        return (T) this;
     }
 
-    public AsyncBaseClientBuilder environment(Environment environment) {
+    public T environment(Environment environment) {
         this.environment = environment;
-        return this;
+        return (T) this;
     }
 
-    public AsyncBaseClientBuilder url(String url) {
+    public T url(String url) {
         this.environment = Environment.custom(url);
-        return this;
+        return (T) this;
     }
 
     /**
      * Sets the timeout (in seconds) for the client. Defaults to 60 seconds.
      */
-    public AsyncBaseClientBuilder timeout(int timeout) {
+    public T timeout(int timeout) {
         this.timeout = Optional.of(timeout);
-        return this;
+        return (T) this;
     }
 
     /**
      * Sets the maximum number of retries for the client. Defaults to 2 retries.
      */
-    public AsyncBaseClientBuilder maxRetries(int maxRetries) {
+    public T maxRetries(int maxRetries) {
         this.maxRetries = Optional.of(maxRetries);
-        return this;
+        return (T) this;
     }
 
     /**
      * Sets the underlying OkHttp client
      */
-    public AsyncBaseClientBuilder httpClient(OkHttpClient httpClient) {
+    public T httpClient(OkHttpClient httpClient) {
         this.httpClient = httpClient;
-        return this;
+        return (T) this;
     }
 
     /**
@@ -101,14 +101,14 @@ public AsyncBaseClientBuilder httpClient(OkHttpClient httpClient) {
      * @param value The header value
      * @return This builder for method chaining
      */
-    public AsyncBaseClientBuilder addHeader(String name, String value) {
+    public T addHeader(String name, String value) {
         this.customHeaders.put(name, value);
-        return this;
+        return (T) this;
     }
 
-    public AsyncBaseClientBuilder projectId(String projectId) {
+    public T projectId(String projectId) {
         this.projectId = projectId;
-        return this;
+        return (T) this;
     }
 
     protected ClientOptions buildClientOptions() {

src/main/java/com/pipedream/api/AsyncPipedreamClient.java

@@ -15,11 +15,24 @@ public AsyncPipedreamClient(final ClientOptions clientOptions) {
         this.workflowsClient = Suppliers.memoize(() -> new WorkflowsClient(clientOptions));
     }
 
+    /**
+     * Creates a builder pre-populated from the standard Pipedream environment variables
+     * (PIPEDREAM_BASE_URL, PIPEDREAM_CLIENT_ID, PIPEDREAM_CLIENT_SECRET,
+     * PIPEDREAM_PROJECT_ENVIRONMENT, PIPEDREAM_PROJECT_ID).
+     *
+     * <p>For OAuth client credentials, the env-var defaults can be overridden via
+     * {@code .clientId(...)} / {@code .clientSecret(...)} and progressive scopes set with
+     * {@code .scope(...)}. For pre-generated access tokens, use {@code .token(...)} to bypass
+     * the OAuth flow entirely.
+     */
     public static AsyncPipedreamClientBuilder builder() {
+        String baseUrl = System.getenv("PIPEDREAM_BASE_URL") != null
+                ? System.getenv("PIPEDREAM_BASE_URL")
+                : Environment.PROD.getUrl();
         return new AsyncPipedreamClientBuilder()
                 .clientId(System.getenv("PIPEDREAM_CLIENT_ID"))
                 .clientSecret(System.getenv("PIPEDREAM_CLIENT_SECRET"))
-                .environment(Environment.PROD)
+                .url(baseUrl)
                 .projectEnvironment(System.getenv("PIPEDREAM_PROJECT_ENVIRONMENT"))
                 .projectId(System.getenv("PIPEDREAM_PROJECT_ID"));
     }