diff --git a/CHANGELOG.md b/CHANGELOG.md index f72713f..be6b081 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ All notable changes to the Apify Java client are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.14.1] - 2026-11-13 + +### Changed + +- Updated to Apify OpenAPI specification `v2-2026-11-13T143025Z` (documentation only). +- Javadoc of `RunClient.charge` and `Actor.getActorStandby` uses the Server Actors wording. +- `RunClient.charge` docs say to call it from inside the Actor run, with the run's `APIFY_TOKEN`. +- `ActorRun.getUsageUsd` docs say when the field is present: runs you own that pay for platform usage, not standard pay-per-event Actors. +- `docs/runs.md` states that `abort`, `reboot`, and `metamorph` work on a `lastRun()` client. +- API token docs say that Apify Console shows a token only once. + ## [0.14.0] - 2026-11-10 ### Added diff --git a/README.md b/README.md index bc9f6b1..94fe5ce 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Maven (Maven Central is a default repository, so no extra configuration is neede com.apify apify-client - 0.14.0 + 0.14.1 ``` @@ -35,7 +35,7 @@ repositories { } dependencies { - implementation 'com.apify:apify-client:0.14.0' + implementation 'com.apify:apify-client:0.14.1' } ``` @@ -50,7 +50,7 @@ import com.apify.client.actor.ActorStartOptions; class HelloApify { public static void main(String[] args) { - // Your API token from https://console.apify.com/settings/integrations + // An API token created at https://console.apify.com/settings/integrations (shown only once) ApifyClient client = ApifyClient.create(System.getenv("APIFY_TOKEN")); ActorRun run = client.actor("apify/hello-world").call(null, new ActorStartOptions(), 120L).join(); System.out.println("Run " + run.getId() + " finished with status " + run.getStatus()); @@ -437,10 +437,10 @@ try { The public `com.apify.client.Version` class (`import com.apify.client.Version;`) exposes two constants: -- `Version.CLIENT_VERSION`: the semantic version of this client (`0.14.0`). +- `Version.CLIENT_VERSION`: the semantic version of this client (`0.14.1`). - `Version.API_SPEC_VERSION`: the version of the [Apify OpenAPI specification](https://docs.apify.com/api/openapi.json) (its `info.version` field) that this client's endpoints, parameters, and models were last generated - and checked against (`v2-2026-11-09T143926Z`). It is a snapshot, not a live compatibility + and checked against (`v2-2026-11-13T143025Z`). It is a snapshot, not a live compatibility guarantee: the client keeps working against newer, backward-compatible spec revisions, but a feature added to the API after this snapshot has no corresponding method here yet. diff --git a/docs/README.md b/docs/README.md index 3a3a093..703a7fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,8 +21,10 @@ compression, default headers, user-agent suffix, custom HTTP transport). `client returns a client that sends every request with a different timeout (see [Timeouts](../README.md#timeouts)). -Get your API token from the -[Apify Console → Settings → API & Integrations](https://console.apify.com/settings/integrations). +Create an API token on the +[Apify Console → Settings → API & Integrations](https://console.apify.com/settings/integrations) +page. The Console shows the token only once, right after you create or rotate it, so copy it and +store it somewhere safe. Every network-calling method returns a `CompletableFuture` (`java.util.concurrent.CompletableFuture`) rather than blocking the calling thread; see [Asynchronous API](../README.md#asynchronous-api) in diff --git a/docs/runs.md b/docs/runs.md index 5f533a8..1be1d08 100644 --- a/docs/runs.md +++ b/docs/runs.md @@ -115,12 +115,14 @@ To update the status message of a run other than the current one, call `update() client.run("RUN_ID").update(Map.of("statusMessage", "half way there", "isStatusMessageTerminal", false)).join(); ``` -> **`lastRun()` clients are for reads.** A `RunClient` obtained via `actor(id).lastRun(...)` / -> `task(id).lastRun(...)` targets the `runs/last` path and is intended for reading (`get`, -> `dataset()`/`keyValueStore()`/`requestQueue()`, `log()`). The mutating methods (`abort`, `reboot`, -> `resurrect`, `metamorph`, `charge`, `update`, `delete`) require a concrete run and have no -> `runs/last` endpoint; resolve the id first (`lastRun(...).get().join()` then `client.run(id)`). The type -> exposes them uniformly, but calling them on a last-run client fails server-side. +> **Not every method works on a `lastRun()` client.** A `RunClient` obtained via +> `actor(id).lastRun(...)` / `task(id).lastRun(...)` targets the `runs/last` path. Reads (`get`, +> `dataset()`/`keyValueStore()`/`requestQueue()`, `log()`) are supported, and so are `abort`, +> `reboot`, and `metamorph`, which call the documented `runs/last/abort`, `runs/last/reboot`, and +> `runs/last/metamorph` endpoints with the same `status` and `origin` filters. The other mutating +> methods (`resurrect`, `charge`, `update`, `delete`) require a concrete run and have no +> `runs/last` endpoint; resolve the id first (`lastRun(...).get().join()` then `client.run(id)`). The +> type exposes them uniformly, but calling them on a last-run client fails server-side. `ActorRun` fields include `getId()`, `getActId()`, `getUserId()`, `getStatus()`, `getStatusMessage()`, `getStartedAt()`, `getFinishedAt()`, `getBuildId()`, `getDefaultDatasetId()`, @@ -143,7 +145,8 @@ owning it, e.g. `"ANYONE_WITH_ID_CAN_READ"`, `"RESTRICTED"`, or `null` to follow default), `getChargedEventCounts()` (`Map`; per-event-type charge counts for pay-per-event Actors, `null` otherwise), `getPricingInfo()` (`JsonNode`; shape depends on the Actor's pricing model), `getUsage()` / `getUsageUsd()` (`ActorRunUsage`; per-billable-unit resource -consumption, the latter as its USD cost; see below), `getUsageTotalUsd()` (`Double`; the run's +consumption, the latter as its USD cost and only for runs you own that pay for platform usage, +`null` for standard pay-per-event Actors; see below), `getUsageTotalUsd()` (`Double`; the run's total cost in USD, combining platform usage and/or event costs depending on pricing model), `getStats()` (`ActorRunStats`; runtime metrics; `getInputBodyLen()`, `getMigrationCount()`, `getRebootCount()`, `getRestartCount()`, `getResurrectCount()`, @@ -177,10 +180,13 @@ nullable), `getMemoryMbytes()` (`Long`, nullable), `getDiskMbytes()` (`Long`, nu `RunChargeOptions` (constructed with the required event name) uses plain values: `count(Long)`, `idempotencyKey(String)`, auto-generated when unset so a transport-retried charge is applied at most once, and `requestId(String)`, the `X-Actor-Request-ID` of the Server Actor request being -charged (required for multi-tenant Server Actor runs, omitted otherwise). +charged (required for multi-tenant Server Actor runs, omitted otherwise). See +[Charge for a request](https://docs.apify.com/platform/actors/monetize/server-actors#charge-for-a-request). +Call `charge` from inside the Actor run, with the API token the run received at startup in the +`APIFY_TOKEN` environment variable. ```java -client.run("RUN_ID").charge(new RunChargeOptions("my-event").count(3L)).join(); +client.run(System.getenv("ACTOR_RUN_ID")).charge(new RunChargeOptions("my-event").count(3L)).join(); ``` `MetamorphOptions` uses plain values `build(String)` and `contentType(String)`. diff --git a/pom.xml b/pom.xml index 8e65c37..baf59cd 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ com.apify apify-client - 0.14.0 + 0.14.1 jar Apify Java Client diff --git a/src/main/java/com/apify/client/ApifyClientBuilder.java b/src/main/java/com/apify/client/ApifyClientBuilder.java index 4223c1e..b6028c1 100644 --- a/src/main/java/com/apify/client/ApifyClientBuilder.java +++ b/src/main/java/com/apify/client/ApifyClientBuilder.java @@ -48,7 +48,11 @@ public final class ApifyClientBuilder { ApifyClientBuilder() {} - /** Sets the API token used for authentication (sent as a Bearer token). */ + /** + * Sets the API token used for authentication (sent as a Bearer token). Create a token on the Integrations page in Apify Console, + * which shows it only once, right after you create or rotate it. + */ public ApifyClientBuilder token(String token) { this.token = token; return this; diff --git a/src/main/java/com/apify/client/Version.java b/src/main/java/com/apify/client/Version.java index 7ab5ea0..765e3ca 100644 --- a/src/main/java/com/apify/client/Version.java +++ b/src/main/java/com/apify/client/Version.java @@ -13,13 +13,13 @@ public final class Version { * The semantic version of this client library (see SemVer). * Changes to the public interface other than additive ones are considered breaking changes. */ - public static final String CLIENT_VERSION = "0.14.0"; + public static final String CLIENT_VERSION = "0.14.1"; /** * The version of the Apify OpenAPI specification this client was generated and verified against. * Corresponds to the {@code info.version} field of the Apify OpenAPI document. */ - public static final String API_SPEC_VERSION = "v2-2026-11-09T143926Z"; + public static final String API_SPEC_VERSION = "v2-2026-11-13T143025Z"; private Version() {} } diff --git a/src/main/java/com/apify/client/actor/Actor.java b/src/main/java/com/apify/client/actor/Actor.java index a5778ee..ef449cb 100644 --- a/src/main/java/com/apify/client/actor/Actor.java +++ b/src/main/java/com/apify/client/actor/Actor.java @@ -138,7 +138,12 @@ public List getCategories() { return categories == null ? List.of() : Collections.unmodifiableList(categories); } - /** Standby-mode configuration for this Actor, if standby mode has ever been configured. */ + /** + * Standby-mode configuration for this Actor, if standby mode has ever been configured. For + * details, see Develop + * Server Actors. + */ public ActorStandby getActorStandby() { return actorStandby; } diff --git a/src/main/java/com/apify/client/run/ActorRun.java b/src/main/java/com/apify/client/run/ActorRun.java index 194de9c..8f6ced3 100644 --- a/src/main/java/com/apify/client/run/ActorRun.java +++ b/src/main/java/com/apify/client/run/ActorRun.java @@ -152,7 +152,12 @@ public ActorRunUsage getUsage() { return usage; } - /** As {@link #getUsage()}, converted to USD; only present where {@link #getUsage()} is. */ + /** + * Platform usage costs in USD, broken down by billable unit. Only present if you own the run and + * pay for platform usage (pay per usage, or pay per event with usage costs, such as runs of + * single-tenant Server Actors). Not available for standard pay-per-event Actors, and requires an + * authentication token. + */ public ActorRunUsage getUsageUsd() { return usageUsd; } diff --git a/src/main/java/com/apify/client/run/RunClient.java b/src/main/java/com/apify/client/run/RunClient.java index 7bcc127..b3e48ff 100644 --- a/src/main/java/com/apify/client/run/RunClient.java +++ b/src/main/java/com/apify/client/run/RunClient.java @@ -159,7 +159,14 @@ public CompletableFuture resurrect(RunResurrectOptions options) { /** * Charges for a pay-per-event Actor run: records occurrences of a named event. Only meaningful - * for runs of pay-per-event Actors. + * for runs of pay-per-event Actors. Call it from the Actor run itself, with the API token the run + * received at startup in the {@code APIFY_TOKEN} environment variable. + * + *

To charge a request to a multi-tenant Server Actor, set {@link + * RunChargeOptions#requestId(String)} to the {@code X-Actor-Request-ID} header value of the + * request. See Charge + * for a request. * *

An idempotency key is always sent (generated if not provided), so a retried charge is * applied at most once. @@ -182,8 +189,7 @@ public CompletableFuture charge(RunChargeOptions options) { body.put("requestId", requestId); } Map headers = Map.of(CHARGE_IDEMPOTENCY_HEADER, idempotencyKey); - // Route through mergedParams like the run's other actions, so a last-run-seeded context charges - // the same run its read methods resolve to (its pinned status/origin filters are preserved). + // Kept consistent with the other actions; there is no runs/last/charge endpoint. String url = ctx.mergedParams(new QueryParams()).applyToUrl(ctx.subUrl("charge")); return ctx.http .call( diff --git a/src/test/java/com/apify/client/ClientBehaviourRegressionTest.java b/src/test/java/com/apify/client/ClientBehaviourRegressionTest.java index af28293..7c5c38f 100644 --- a/src/test/java/com/apify/client/ClientBehaviourRegressionTest.java +++ b/src/test/java/com/apify/client/ClientBehaviourRegressionTest.java @@ -103,6 +103,40 @@ void lastRunForwardsStatusFilterToNestedStorages() { assertTrue(log.lastUrl.contains("origin=API"), log.lastUrl); } + @Test + void lastRunAbortRebootAndMetamorphCallTheLastRunEndpointsWithTheFilters() { + // The spec documents runs/last/{abort,reboot,metamorph} for Actors and tasks, so these calls + // on a filtered last-run client must keep the pinned status and origin filters. + LastRunOptions filters = new LastRunOptions().status("RUNNING").origin("API"); + String runBody = "{\"data\":{\"id\":\"run123\"}}"; + + MockTransport abort = MockTransport.ofConstant(200, runBody); + client(abort).actor("me/x").lastRun(filters).abort(null).join(); + assertLastRunUrl(abort.lastUrl, "actors/me~x/runs/last/abort"); + + MockTransport reboot = MockTransport.ofConstant(200, runBody); + client(reboot).actor("me/x").lastRun(filters).reboot().join(); + assertLastRunUrl(reboot.lastUrl, "actors/me~x/runs/last/reboot"); + + MockTransport metamorph = MockTransport.ofConstant(200, runBody); + client(metamorph) + .actor("me/x") + .lastRun(filters) + .metamorph("apify/other-actor", Map.of("foo", "bar"), new MetamorphOptions()) + .join(); + assertLastRunUrl(metamorph.lastUrl, "actors/me~x/runs/last/metamorph"); + + MockTransport taskAbort = MockTransport.ofConstant(200, runBody); + client(taskAbort).task("me/t").lastRun(filters).abort(null).join(); + assertLastRunUrl(taskAbort.lastUrl, "actor-tasks/me~t/runs/last/abort"); + } + + private static void assertLastRunUrl(String url, String expectedPath) { + assertTrue(url.contains(expectedPath), url); + assertTrue(url.contains("status=RUNNING"), url); + assertTrue(url.contains("origin=API"), url); + } + @Test void plainRunNestedStoragesCarryNoInheritedFilter() { // A non-last-run client has no pinned params, so nested accessors stay filter-free.