From 286d30271422bab64907b15c89b60864f5ea3378 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 07:47:12 +0000 Subject: [PATCH] chore: comply with updated client requirements (v0.4.1) Documentation-compliance pass against the updated orchestration client requirements (no OpenAPI spec change; still v2-2026-06-25T142310Z). No public API surface change, so this is a SemVer patch (0.4.0 -> 0.4.1). - Documentation: disclaimer now states the client is "official, but experimental" and AI-generated/maintained (replacing "not (yet) an officially supported Apify product") in README.md, docs/README.md, and the client.go package doc comment. - Publishing: documented in README that Go has no central registry and thus no Trusted Publisher mechanism (releases via git tag + module proxy, GITHUB_TOKEN only); go-publish.yml already complied. - Documentation completeness: added field tables for APIError and RunChargeOptions, enumerated webhook Create input keys, documented the request-queue locking method signatures, fixed the DownloadItems format list (added JSONL), and noted the plain-value option structs. - Fixed a stale API_SPEC_VERSION reference in README; bumped CLIENT_VERSION to 0.4.1 with a CHANGELOG entry. --- CHANGELOG.md | 31 +++++++++++++++++++++++++++++++ README.md | 32 +++++++++++++++++++++++++------- client.go | 4 ++++ docs/README.md | 6 +++--- docs/runs.md | 14 ++++++++++++-- docs/storages.md | 7 +++++-- docs/webhooks.md | 12 ++++++++++++ version.go | 2 +- 8 files changed, 93 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f5ae10..30f4d54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,37 @@ All notable changes to the Apify Go 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.4.1] - 2026-06-29 + +Documentation-only compliance pass against the current orchestration requirements (no spec bump; +the client remains on `v2-2026-06-25T142310Z`). No change to the public API surface, so this is a +SemVer patch. + +### Changed + +- Documentation now states the client is **official, but experimental** and **AI-generated and + AI-maintained**, replacing the previous "not (yet) an officially supported Apify product" + wording that contradicted the requirement. Updated consistently in `README.md`, `docs/README.md`, + and the package-level doc comment in `client.go`. +- `README.md` "Releasing" section now explicitly documents that Go's publishing process has no + central registry and therefore no "Trusted Publisher" mechanism — releases are cut purely by + pushing a git tag read by the public Go module proxy, authenticated only by the built-in + `GITHUB_TOKEN`. The `go-publish.yml` workflow already reflected this; the README now matches. +- Documentation completeness pass (no API change): added a field table for `*APIError` and + documented `AsAPIError` in `README.md`; added a `RunChargeOptions` field table and a note that + `MetamorphOptions`/`RunChargeOptions` use plain (non-pointer) values in `docs/runs.md`; + enumerated the webhook `Create` input keys in `docs/webhooks.md`; documented the request-queue + locking method signatures (`ListAndLockHead`, `ProlongRequestLock`, `DeleteRequestLock`, + `UnlockRequests`) in `docs/storages.md`. + +### Fixed + +- Corrected a stale `API_SPEC_VERSION` reference in the `README.md` "Versioning" section + (`v2-2026-06-24T105326Z` → `v2-2026-06-25T142310Z`) so it matches `version.go`. +- `docs/storages.md`: `DownloadItems` now lists `JSONL` in its format list, matching the format + constants table (previously the prose omitted it). +- Bumped `CLIENT_VERSION` to `0.4.1` (patch; documentation-only, no public API change). + ## [0.4.0] - 2026-06-26 Updated to Apify OpenAPI specification `v2-2026-06-25T142310Z` (previously diff --git a/README.md b/README.md index ac3cfa5..a84ce97 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Apify API client for Go -> **Experimental — AI-generated and AI-maintained.** This client is experimental. It is -> generated and maintained by AI, and is not (yet) an officially supported Apify product. Review -> the code before relying on it in production and report issues on the repository. +> **Official, but experimental — AI-generated and AI-maintained.** This is an official Apify +> client, but it is experimental: it is generated and maintained by AI. Review the code before +> relying on it in production and report issues on the repository. An idiomatic Go client for the [Apify API](https://docs.apify.com/api/v2). @@ -116,9 +116,21 @@ variable the JavaScript reference client reads); if it is set to a non-empty val ## Error handling -API errors are returned as `*APIError`, with the HTTP status, error type, message, attempt -count, and request method/path. `get`/`delete` on a missing resource is *not* an error: the -methods report absence via a boolean (`ok`) instead. +API errors are returned as `*APIError`. Recover it from any returned `error` with +`apify.AsAPIError(err) (*APIError, bool)` — the boolean is `false` when the error is not an API +error (e.g. a network or context error). `get`/`delete` on a missing resource is *not* an error: +the methods report absence via a boolean (`ok`) instead. + +`*APIError` exposes: + +| Field | Type | Meaning | +|---|---|---| +| `StatusCode` | `int` | HTTP status code of the error response. | +| `Type` | `string` | Machine-readable error type returned by the API (e.g. `"record-not-found"`). | +| `Message` | `string` | Human-readable error description returned by the API. | +| `Attempt` | `int` | 1-based number of the API call attempt that produced this error. | +| `HTTPMethod` | `string` | HTTP method of the failing call (e.g. `"GET"`, `"POST"`). | +| `Path` | `string` | Request path of the endpoint (URL excluding origin). | ```go user, ok, err := client.Me().Get(ctx) @@ -167,7 +179,7 @@ func main() { - `apify.CLIENT_VERSION` — the semantic version of this library. - `apify.API_SPEC_VERSION` — the Apify OpenAPI spec version this client was built against - (`v2-2026-06-24T105326Z`). + (`v2-2026-06-25T142310Z`). ### Releasing @@ -180,6 +192,12 @@ module proxy to index the new version so it appears on `CLIENT_VERSION` in [`version.go`](version.go), so bump that constant before releasing. The workflow uses only the built-in `GITHUB_TOKEN`; no extra credentials are required. +There is no "Trusted Publisher" step: that mechanism applies to registries that authenticate +uploads (e.g. PyPI, npm, crates.io). Go has no central registry and no upload step — a module is +published purely by pushing a git tag that the public module proxy reads — so there is no token or +trusted-publisher relationship to configure. The workflow therefore relies only on the repository's +built-in `GITHUB_TOKEN` to push the tag and open the release. + ## Examples Runnable examples live in [`examples/`](examples) and are exercised in CI. Run any of them diff --git a/client.go b/client.go index 0811ea8..c9e0f03 100644 --- a/client.go +++ b/client.go @@ -1,6 +1,10 @@ // Package apify is the official, idiomatic Go client for the Apify API // (https://docs.apify.com/api/v2). // +// Official, but experimental — AI-generated and AI-maintained. This is an official Apify +// client, but it is experimental: it is generated and maintained by AI. Review the code +// before relying on it in production and report issues on the repository. +// // It provides a resource-oriented interface that mirrors the official JavaScript and Rust // clients: start from an [ApifyClient], then drill down into resources (Actors, runs, // datasets, key-value stores, request queues, tasks, schedules, webhooks, the store, users diff --git a/docs/README.md b/docs/README.md index c6214fa..64e0458 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,8 @@ # Apify Go client documentation -> **Experimental — AI-generated and AI-maintained.** This client is experimental. It is -> generated and maintained by AI, and is not (yet) an officially supported Apify product. Review -> the code before relying on it in production and report issues on the repository. +> **Official, but experimental — AI-generated and AI-maintained.** This is an official Apify +> client, but it is experimental: it is generated and maintained by AI. Review the code before +> relying on it in production and report issues on the repository. This directory documents the public API of the Apify Go client, organized by resource. Each page lists the available methods with their parameters and short, runnable snippets. For an diff --git a/docs/runs.md b/docs/runs.md index ab64a41..c01ca1f 100644 --- a/docs/runs.md +++ b/docs/runs.md @@ -58,8 +58,18 @@ The time filters apply only to Actor- and task-scoped collections. | `Build` | `string` | Pin the target Actor's build (empty for default). | | `ContentType` | `string` | Content type of the input body (default `application/json`). | -`RunChargeOptions`: `EventName` (required), `Count`, `IdempotencyKey` (auto-generated if -empty, so a retried charge is applied at most once). +`RunChargeOptions`: + +| Field | Type | Meaning | +|---|---|---| +| `EventName` | `string` | Name of the event to charge for. **Required.** | +| `Count` | `*int64` | Number of times to charge the event (defaults to 1 when nil). | +| `IdempotencyKey` | `string` | Deduplicates the charge across retries; auto-generated when empty, so a retried charge is applied at most once. | + +> Note: unlike most option structs (whose optional fields are pointer-typed — see +> [docs/README.md](README.md)), `MetamorphOptions` and the string fields of `RunChargeOptions` +> use plain values. `Build`/`ContentType` and `EventName`/`IdempotencyKey` treat the zero value +> (empty string) as "unset"; only `RunChargeOptions.Count` is a pointer. ```go run, err := client.Run(runID).WaitForFinish(ctx, nil) // nil waits indefinitely diff --git a/docs/storages.md b/docs/storages.md index fc24065..4b02727 100644 --- a/docs/storages.md +++ b/docs/storages.md @@ -16,7 +16,7 @@ Single dataset: `client.Dataset(id)`: | `Get / Update / Delete(ctx)` | CRUD. | | `ListItems(ctx, DatasetListItemsOptions) (PaginationList[json.RawMessage], error)` | Read items. | | `PushItems(ctx, items any) error` | Append one item or a slice of items. | -| `DownloadItems(ctx, DownloadItemsFormat, DatasetDownloadOptions) ([]byte, error)` | Export items (JSON, CSV, XLSX, XML, RSS, HTML). | +| `DownloadItems(ctx, DownloadItemsFormat, DatasetDownloadOptions) ([]byte, error)` | Export items (JSON, JSONL, CSV, XLSX, XML, RSS, HTML — see the format constants below). | | `GetStatistics(ctx) (json.RawMessage, bool, error)` | Dataset statistics. | | `CreateItemsPublicURL(ctx, DatasetListItemsOptions, expiresInSecs *int64) (string, error)` | Signed public items URL. | @@ -188,7 +188,10 @@ Single queue: `client.RequestQueue(id)`: | `PaginateRequests(pageLimit *int64) *RequestQueueRequestsIterator` | Lazy iterator over all requests (yields `*RequestQueueRequest`). | | `BatchAddRequests(ctx, []RequestQueueRequest, forefront) (BatchAddResult, error)` | Add many requests (auto-chunked at 25/call). | | `BatchDeleteRequests(ctx, requests any) (json.RawMessage, error)` | Delete many requests in one call. `requests` is the JSON-marshalable batch payload — a slice in which each element identifies one request by **either** its `id` **or** its `uniqueKey` (e.g. `[]map[string]string{{"uniqueKey": "..."}}` or a slice of `RequestQueueRequest`), matching the reference client's `batchDeleteRequests`. Returns the raw API response. | -| `ListAndLockHead / ProlongRequestLock / DeleteRequestLock / UnlockRequests(ctx, ...)` | Locking. | +| `ListAndLockHead(ctx, lockSecs int64, limit *int64) (json.RawMessage, error)` | Fetch the head of the queue and lock the returned requests for `lockSecs` seconds. Returns the raw API response. | +| `ProlongRequestLock(ctx, id string, lockSecs int64, forefront bool) (json.RawMessage, error)` | Extend the lock on a request by `lockSecs` seconds; `forefront` controls re-queue position when the lock expires. | +| `DeleteRequestLock(ctx, id string, forefront bool) error` | Release the lock on a request without modifying it. | +| `UnlockRequests(ctx) (json.RawMessage, error)` | Release all locks held by this client (see `WithClientKey`). | | `WithClientKey(key string) *RequestQueueClient` | Pin a stable client key (required to unlock own locks). | `RequestQueueRequest` is the request payload/record. `URL` is required; `ID` is assigned by the diff --git a/docs/webhooks.md b/docs/webhooks.md index 0408b05..7043dd1 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -14,6 +14,18 @@ Webhooks notify external services when events occur. Access the webhook collecti An Actor's or task's webhooks are also listable via `client.Actor(id).Webhooks()` / `client.Task(id).Webhooks()`. +`Create` (and `Update`) take a free-form JSON object (`any`) that mirrors the webhook shape in +the Apify API, so it can carry any field the API accepts. The commonly used input keys are: + +| Key | Type | Meaning | +|---|---|---| +| `eventTypes` | `[]string` | Events that trigger the webhook (see [Event types](#event-types)). Required. | +| `requestUrl` | `string` | URL the webhook posts to. Required. | +| `condition` | `object` | Scope the webhook, e.g. `{"actorId": "..."}`, `{"actorTaskId": "..."}`, or `{"actorRunId": "..."}`. | +| `isAdHoc` | `bool` | `true` for a one-off webhook bound to a single run/build via `condition`. | +| `payloadTemplate` | `string` | Optional template string for the dispatched payload. | +| `description` | `string` | Optional human-readable description. | + ### Event types A webhook's `eventTypes` is a list drawn from the closed `WebhookEventType` enum (12 values): diff --git a/version.go b/version.go index bfb9ce9..f69fcc0 100644 --- a/version.go +++ b/version.go @@ -4,7 +4,7 @@ package apify // // It follows Semantic Versioning (https://semver.org/). Changes to the public // interface (other than additive ones) are considered breaking changes. -const CLIENT_VERSION = "0.4.0" +const CLIENT_VERSION = "0.4.1" // API_SPEC_VERSION is the version of the Apify OpenAPI specification that this // client was generated and verified against.