feat(batch): accept lightweight submissions and queue pending work (#2683)

Stainless-Generated-From: 969f36bcbf28ac9d5facfc2af1f709b5ca5b9069

Author: stlc-bot

src/Batch/BatchGetResponse.php

@@ -136,7 +136,7 @@ final class BatchGetResponse implements BaseModel
     public ?Results $results;
 
     /**
-     * Current state. `completed`, `cancelled`, and `failed` are final.
+     * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
      *
      * @var value-of<Status> $status
      */
@@ -443,7 +443,7 @@ public function withResults(Results|array|null $results): self
     }
 
     /**
-     * Current state. `completed`, `cancelled`, and `failed` are final.
+     * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
      *
      * @param Status|value-of<Status> $status
      */

src/Batch/BatchGetResponse/Credits.php

@@ -39,7 +39,7 @@ final class Credits implements BaseModel
     public int $refunded;
 
     /**
-     * Credits held when the batch was accepted.
+     * Credits held by background preparation before scraping starts. Zero while pending.
      */
     #[Required]
     public int $reserved;
@@ -122,7 +122,7 @@ public function withRefunded(int $refunded): self
     }
 
     /**
-     * Credits held when the batch was accepted.
+     * Credits held by background preparation before scraping starts. Zero while pending.
      */
     public function withReserved(int $reserved): self
     {

src/Batch/BatchGetResponse/Status.php

@@ -5,10 +5,12 @@
 namespace ContextDev\Batch\BatchGetResponse;
 
 /**
- * Current state. `completed`, `cancelled`, and `failed` are final.
+ * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
  */
 enum Status: string
 {
+    case PENDING = 'pending';
+
     case QUEUED = 'queued';
 
     case RUNNING = 'running';

src/Batch/BatchListParams/Status.php

@@ -9,6 +9,8 @@
  */
 enum Status: string
 {
+    case PENDING = 'pending';
+
     case QUEUED = 'queued';
 
     case RUNNING = 'running';

src/Batch/BatchListResponse/Data.php

@@ -120,7 +120,7 @@ final class Data implements BaseModel
     public ?Results $results;
 
     /**
-     * Current state. `completed`, `cancelled`, and `failed` are final.
+     * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
      *
      * @var value-of<Status> $status
      */
@@ -377,7 +377,7 @@ public function withResults(Results|array|null $results): self
     }
 
     /**
-     * Current state. `completed`, `cancelled`, and `failed` are final.
+     * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
      *
      * @param Status|value-of<Status> $status
      */

src/Batch/BatchListResponse/Data/Credits.php

@@ -39,7 +39,7 @@ final class Credits implements BaseModel
     public int $refunded;
 
     /**
-     * Credits held when the batch was accepted.
+     * Credits held by background preparation before scraping starts. Zero while pending.
      */
     #[Required]
     public int $reserved;
@@ -122,7 +122,7 @@ public function withRefunded(int $refunded): self
     }
 
     /**
-     * Credits held when the batch was accepted.
+     * Credits held by background preparation before scraping starts. Zero while pending.
      */
     public function withReserved(int $reserved): self
     {

src/Batch/BatchListResponse/Data/Status.php

@@ -5,10 +5,12 @@
 namespace ContextDev\Batch\BatchListResponse\Data;
 
 /**
- * Current state. `completed`, `cancelled`, and `failed` are final.
+ * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
  */
 enum Status: string
 {
+    case PENDING = 'pending';
+
     case QUEUED = 'queued';
 
     case RUNNING = 'running';

src/Batch/BatchSubmitParams.php

@@ -15,7 +15,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Scrape up to 100,000 URLs, or crawl a site, asynchronously using the same formats and scrape parameters as POST /web/scrape. Choose Markdown, HTML, screenshots, images, bytes, parsed fields, products, highlights, and JSON. Poll the batch ID or receive a webhook when it finishes.
+ * Scrape up to 100,000 URLs, or crawl a site, asynchronously using the same formats and scrape parameters as POST /web/scrape. Choose Markdown, HTML, screenshots, images, bytes, parsed fields, products, highlights, and JSON. Submission persists the input and returns immediately with status pending. Organizations with fewer than 10 available credits and no overage are rejected with 402 up front. Each organization can submit up to 1,000 batches per minute, independently of its polling budget. Batches wait pending when execution capacity is full. Validation, sitemap discovery, the full credit quote, and shard scheduling happen afterward. Poll the batch ID or receive a webhook when it finishes. Deferred rejections appear as status failed with a failure code and message.
  *
  * @see ContextDev\Services\BatchService::submit()
  *

src/Batch/BatchSubmitResponse.php

@@ -72,7 +72,7 @@ final class BatchSubmitResponse implements BaseModel
     public string $createdAt;
 
     /**
-     * What accepting this batch cost.
+     * Credits are reserved after background validation, before scraping starts.
      */
     #[Required]
     public Credits $credits;
@@ -112,7 +112,7 @@ final class BatchSubmitResponse implements BaseModel
     public string $requestID;
 
     /**
-     * Always `queued`. An accepted batch has not started yet.
+     * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
      *
      * @var value-of<Status> $status
      */
@@ -285,7 +285,7 @@ public function withCreatedAt(string $createdAt): self
     }
 
     /**
-     * What accepting this batch cost.
+     * Credits are reserved after background validation, before scraping starts.
      *
      * @param Credits|CreditsShape $credits
      */
@@ -361,7 +361,7 @@ public function withRequestID(string $requestID): self
     }
 
     /**
-     * Always `queued`. An accepted batch has not started yet.
+     * Current state. `pending` means waiting for execution capacity or background validation. Capacity-limited batches remain pending until a slot opens. `completed`, `cancelled`, and `failed` are final.
      *
      * @param Status|value-of<Status> $status
      */

src/Batch/BatchSubmitResponse/Credits.php

@@ -9,7 +9,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * What accepting this batch cost.
+ * Credits are reserved after background validation, before scraping starts.
  *
  * @phpstan-type CreditsShape = array{reserved: int}
  */
@@ -19,7 +19,7 @@ final class Credits implements BaseModel
     use SdkModel;
 
     /**
-     * Credits held at submission.
+     * Credits reserved by background preparation. Zero while pending.
      */
     #[Required]
     public int $reserved;
@@ -58,7 +58,7 @@ public static function with(int $reserved): self
     }
 
     /**
-     * Credits held at submission.
+     * Credits reserved by background preparation. Zero while pending.
      */
     public function withReserved(int $reserved): self
     {