fix: address review feedback on RequestQueueClient typing refactor

- batchDeleteRequests() now rejects an empty or over-25-request input
  up front, matching batchAddRequests() and the JS reference.
- Added RequestQueueRequest::getRetryCount()/getLockExpiresAt(), so
  listAndLockHead()'s per-item lock-expiry field is actually reachable
  via a typed getter as the LockedRequestQueueHead docblock claimed.
- Fixed the getLimit() return-type docs for the two new models.

Author: claude

CHANGELOG.md

@@ -15,6 +15,10 @@ OpenAPI-documented response schemas and the reference client's typed result inte
 - `RequestQueueHead` and the new `LockedRequestQueueHead` gained the previously-missing
   `getQueueModifiedAt()` getter (the field is present in the OpenAPI spec and the reference client,
   but was not yet exposed by this client).
+- `RequestQueueRequest` gained `getRetryCount()`/`getLockExpiresAt()` getters, populated on requests
+  returned by `listHead()`/`listAndLockHead()`/`listRequests()`.
+- `batchDeleteRequests()` now throws `InvalidArgumentException` up front for an empty or
+  over-25-request input, matching `batchAddRequests()`'s and the reference client's validation.
 
 ## 0.4.0
 

docs/models.md

@@ -183,7 +183,7 @@ Returned by `listAndLockHead()`.
 | Getter | Description |
 |---|---|
 | `getItems(): array` | The locked `RequestQueueRequest` items at the head of the queue. |
-| `getLimit(): ?int` | The requested head size limit. |
+| `getLimit(): int` | The requested head size limit. |
 | `hadMultipleClients(): bool` | Whether multiple clients have accessed the queue. |
 | `getLockSecs(): int` | The lock duration applied to every returned request. |
 | `queueHasLockedRequests(): ?bool` | Whether the queue has any requests locked by any client. |
@@ -195,7 +195,7 @@ Returned by `listRequests()`.
 | Getter | Description |
 |---|---|
 | `getItems(): array` | The `RequestQueueRequest` items in this page. |
-| `getLimit(): ?int` | The requested page size limit. |
+| `getLimit(): int` | The requested page size limit. |
 | `getExclusiveStartId(): ?string` | The exclusive start ID used for this page (deprecated; use the cursor). |
 | `getCursor(): ?string` | The cursor that produced this page. |
 | `getNextCursor(): ?string` | The cursor to request the next page, or `null` if this is the last page. |
@@ -264,6 +264,8 @@ Pass `url` and `uniqueKey` positionally for the common case; `data` seeds any ad
 | `getUniqueKey(): ?string` / `setUniqueKey(string): self` | The deduplication key. |
 | `getMethod(): ?string` / `setMethod(string): self` | The HTTP method (defaults to `GET`). |
 | `getUserData(): mixed` / `setUserData(array): self` | Arbitrary user data attached to the request. |
+| `getRetryCount(): ?int` | How many times this request has already been retried (read-only, populated by `listHead()`/`listAndLockHead()`/`listRequests()`). |
+| `getLockExpiresAt(): ?string` | When this request's lock expires (read-only, populated by `listAndLockHead()` only). |
 
 ### `ActorEnvVar`
 Constructor: `new ActorEnvVar(?string $name = null, ?string $value = null, ?bool $isSecret = null, array $data = [])`.

docs/storages.md

@@ -91,7 +91,7 @@ Single — `$client->requestQueue($id)`:
 - `addRequest(RequestQueueRequest $request, bool $forefront = false): RequestQueueOperationInfo` — adds a request to the queue; when `$forefront` is `true` it is added to the front (handled before the rest) instead of the back.
 - `getRequest(string $id): ?RequestQueueRequest`, `updateRequest(RequestQueueRequest $request, bool $forefront = false): RequestQueueOperationInfo` (with `$forefront` `true` the updated request is moved to the front of the queue), `deleteRequest(string $id): void`
 - `batchAddRequests(array $requests, bool $forefront = false, ?BatchAddRequestsOptions $options = null): BatchAddResult` — every request must have a non-empty `uniqueKey`; with `$forefront` `true` the requests are added to the front of the queue; input is split into batches of at most 25 requests that also respect the ~9 MiB payload limit.
-- `batchDeleteRequests(array $requests): BatchDeleteResult` — `$requests` is a `list<RequestQueueRequest>` where each entry identifies a request to delete via `setId()` or `setUniqueKey()` (other fields, if set, are ignored by the API).
+- `batchDeleteRequests(array $requests): BatchDeleteResult` — `$requests` is a `list<RequestQueueRequest>` (1-25 entries) where each entry identifies a request to delete via `setId()` or `setUniqueKey()` (other fields, if set, are ignored by the API); throws `InvalidArgumentException` if empty or over 25 (unlike `batchAddRequests()`, oversized input is rejected rather than chunked, since delete is idempotent and can simply be called again).
 - `listRequests(?ListRequestsOptions $options = null): RequestQueueRequestsPage`
 - `paginateRequests(?PaginateRequestsOptions $options = null): iterable` — lazily iterate the queue's requests, yielding `RequestQueueRequest` instances and following cursor pagination (see the options note below).
 - `listAndLockHead(int $lockSecs, ?int $limit = null): LockedRequestQueueHead` — atomically returns and locks up to `$limit` requests for `$lockSecs` seconds.

src/Model/LockedRequestQueueHead.php

@@ -48,8 +48,8 @@ public static function fromData(mixed $data): self
     }
 
     /**
-     * The locked requests from the head of the queue. Each item carries its own
-     * {@see RequestQueueRequest} lock-expiry field as reported by the API.
+     * The locked requests from the head of the queue. Each item's own
+     * {@see RequestQueueRequest::getLockExpiresAt()} reports when its individual lock expires.
      *
      * @return list<RequestQueueRequest>
      */

src/Model/RequestQueueRequest.php

@@ -95,4 +95,25 @@ public function setUserData(mixed $userData): self
         $this->data['userData'] = $userData;
         return $this;
     }
+
+    /**
+     * How many times processing this request has already been retried. Populated on requests
+     * returned by {@see \Apify\Client\Resource\RequestQueueClient::listHead()},
+     * {@see \Apify\Client\Resource\RequestQueueClient::listAndLockHead()} and
+     * {@see \Apify\Client\Resource\RequestQueueClient::listRequests()}; absent when constructing a
+     * request to add.
+     */
+    public function getRetryCount(): ?int
+    {
+        return $this->getInt('retryCount');
+    }
+
+    /**
+     * ISO 8601 timestamp of when this request's processing lock expires. Only present on requests
+     * returned by {@see \Apify\Client\Resource\RequestQueueClient::listAndLockHead()}.
+     */
+    public function getLockExpiresAt(): ?string
+    {
+        return $this->getString('lockExpiresAt');
+    }
 }

src/Resource/RequestQueueClient.php

@@ -398,12 +398,30 @@ private static function sleepBackoff(int $attempt, int $minDelayMillis): void
      * either {@see RequestQueueRequest::setId()} or {@see RequestQueueRequest::setUniqueKey()} (other
      * fields, if present, are ignored by the API).
      *
+     * Unlike {@see batchAddRequests()}, this does not chunk oversized input: the API caps a single
+     * batch at 25 requests (matching the reference client), so a larger input is rejected up front
+     * rather than silently split (a delete is idempotent, so callers can simply call this again per
+     * chunk).
+     *
      * @param list<RequestQueueRequest> $requests
+     * @throws InvalidArgumentException if {@code $requests} is empty or exceeds the per-call limit
      */
     public function batchDeleteRequests(array $requests): BatchDeleteResult
     {
+        $requests = array_values($requests);
+        if ($requests === []) {
+            throw new InvalidArgumentException('batchDeleteRequests: $requests must not be empty');
+        }
+        if (count($requests) > self::MAX_REQUESTS_PER_BATCH) {
+            throw new InvalidArgumentException(sprintf(
+                'batchDeleteRequests: got %d requests, which exceeds the maximum of %d per call',
+                count($requests),
+                self::MAX_REQUESTS_PER_BATCH
+            ));
+        }
+
         $params = $this->applyClientKey(new QueryParams());
-        $payload = array_map(static fn (RequestQueueRequest $r) => $r->toArray(), array_values($requests));
+        $payload = array_map(static fn (RequestQueueRequest $r) => $r->toArray(), $requests);
         return BatchDeleteResult::fromData($this->ctx->deleteWithBody('requests/batch', $params, $payload));
     }
 

tests/Unit/RequestQueueTypedResultsTest.php

@@ -7,6 +7,7 @@
 use Apify\Client\ApifyClient;
 use Apify\Client\Internal\Json;
 use Apify\Client\Model\RequestQueueRequest;
+use InvalidArgumentException;
 use PHPUnit\Framework\TestCase;
 
 /**
@@ -47,14 +48,16 @@ public function testListAndLockHeadReturnsTypedResult(): void
             'queueHasLockedRequests' => true,
             'clientKey' => 'my-client-key',
             'items' => [
-                ['id' => 'r1', 'uniqueKey' => 'r1', 'url' => 'https://a.com'],
+                ['id' => 'r1', 'uniqueKey' => 'r1', 'url' => 'https://a.com', 'retryCount' => 2, 'lockExpiresAt' => '2026-08-01T00:01:00.000Z'],
             ],
         ]]));
 
         $locked = $this->client($transport)->requestQueue('q1')->listAndLockHead(60, 5);
 
         self::assertCount(1, $locked->getItems());
         self::assertSame('r1', $locked->getItems()[0]->getId());
+        self::assertSame(2, $locked->getItems()[0]->getRetryCount());
+        self::assertSame('2026-08-01T00:01:00.000Z', $locked->getItems()[0]->getLockExpiresAt());
         self::assertSame(60, $locked->getLockSecs());
         self::assertTrue($locked->queueHasLockedRequests());
         self::assertSame('my-client-key', $locked->getClientKey());
@@ -125,4 +128,33 @@ public function testBatchDeleteRequestsSendsIdentifiersAndReturnsTypedResult():
         $sentBody = Json::decode(MockTransport::readBody($transport->lastRequest()));
         self::assertSame([['id' => 'r1'], ['id' => 'r2']], $sentBody);
     }
+
+    public function testBatchDeleteRequestsRejectsEmptyInputBeforeAnyCall(): void
+    {
+        $transport = new MockTransport();
+
+        $this->expectException(InvalidArgumentException::class);
+        try {
+            $this->client($transport)->requestQueue('q1')->batchDeleteRequests([]);
+        } finally {
+            self::assertSame(0, $transport->callCount());
+        }
+    }
+
+    public function testBatchDeleteRequestsRejectsOversizedInputBeforeAnyCall(): void
+    {
+        $transport = new MockTransport();
+        $requests = array_map(
+            static fn (int $i) => (new RequestQueueRequest())->setId('r' . $i),
+            range(0, 25) // 26 > the 25-per-call limit
+        );
+
+        try {
+            $this->client($transport)->requestQueue('q1')->batchDeleteRequests($requests);
+            self::fail('expected InvalidArgumentException');
+        } catch (InvalidArgumentException $e) {
+            self::assertStringContainsString('26', $e->getMessage());
+        }
+        self::assertSame(0, $transport->callCount());
+    }
 }