context.dev 2.6.0 → 2.7.0

data/rbi/context_dev/models/batch_retrieve_response.rbi

@@ -15,7 +15,15 @@ module ContextDev
       sig { returns(String) }
       attr_accessor :id
 
-      # Reserved and used credits.
+      # The crawl controls as submitted, so the limits requested can be compared against
+      # what the crawl reached.
+      sig { returns(T.nilable(ContextDev::CrawlControls)) }
+      attr_reader :crawl
+
+      sig { params(crawl: T.nilable(ContextDev::CrawlControls::OrHash)).void }
+      attr_writer :crawl
+
+      # What this batch has done to your credit balance.
       sig { returns(ContextDev::Models::BatchRetrieveResponse::Credits) }
       attr_reader :credits
 
@@ -26,26 +34,26 @@ module ContextDev
       end
       attr_writer :credits
 
-      # Why the batch failed.
-      sig { returns(T.nilable(ContextDev::Error)) }
-      attr_reader :error
+      # A failure of the batch as a whole, distinct from the per-page failures in
+      # `page_errors`.
+      sig { returns(T.nilable(ContextDev::Failure)) }
+      attr_reader :failure
 
-      sig { params(error: T.nilable(ContextDev::Error::OrHash)).void }
-      attr_writer :error
+      sig { params(failure: T.nilable(ContextDev::Failure::OrHash)).void }
+      attr_writer :failure
 
-      # Page failures grouped by error code.
-      sig { returns(T::Array[ContextDev::ErrorCount]) }
-      attr_accessor :errors
+      # What each page is returned as. Matches `input.data.format` on the submit
+      # request.
+      sig do
+        returns(ContextDev::Models::BatchRetrieveResponse::Format::TaggedSymbol)
+      end
+      attr_accessor :format_
 
-      # Submission counts.
-      sig { returns(ContextDev::Models::BatchRetrieveResponse::Input) }
+      # What submission took in, and what it charged for.
+      sig { returns(ContextDev::Intake) }
       attr_reader :input
 
-      sig do
-        params(
-          input: ContextDev::Models::BatchRetrieveResponse::Input::OrHash
-        ).void
-      end
+      sig { params(input: ContextDev::Intake::OrHash).void }
       attr_writer :input
 
       # Rejected URLs, up to 100. These are not charged.
@@ -54,13 +62,18 @@ module ContextDev
       end
       attr_accessor :invalid_urls
 
-      # How pages are selected.
+      # How pages were selected. Matches `input.mode` on the submit request.
       sig do
         returns(ContextDev::Models::BatchRetrieveResponse::Mode::TaggedSymbol)
       end
       attr_accessor :mode
 
-      # Current processing counts. Use `status` to check completion.
+      # Individual page failures grouped by error code, sorted by count. Unrelated to
+      # `failure`, which is the batch itself failing.
+      sig { returns(T::Array[ContextDev::PageErrorCount]) }
+      attr_accessor :page_errors
+
+      # Pages attempted so far. Use `status` to check completion.
       sig { returns(ContextDev::Models::BatchRetrieveResponse::Progress) }
       attr_reader :progress
 
@@ -71,8 +84,8 @@ module ContextDev
       end
       attr_writer :progress
 
-      # Download links available when the batch finishes. GET /batch/{batch_id}/results
-      # serves the same records as paginated JSON.
+      # Download links, available once the batch reaches a final status and null before
+      # then. GET /batch/{batch_id}/results serves the same records as paginated JSON.
       sig do
         returns(T.nilable(ContextDev::Models::BatchRetrieveResponse::Results))
       end
@@ -108,12 +121,6 @@ module ContextDev
       end
       attr_writer :timing
 
-      # Output format.
-      sig do
-        returns(ContextDev::Models::BatchRetrieveResponse::Type::TaggedSymbol)
-      end
-      attr_accessor :type
-
       # API key usage for this request.
       sig do
         returns(
@@ -130,25 +137,20 @@ module ContextDev
       end
       attr_writer :key_metadata
 
-      # Webhook signing secret. Also returned by GET /batch/{batch_id}.
-      sig { returns(T.nilable(String)) }
-      attr_reader :webhook_secret
-
-      sig { params(webhook_secret: String).void }
-      attr_writer :webhook_secret
-
       sig do
         params(
           id: String,
+          crawl: T.nilable(ContextDev::CrawlControls::OrHash),
           credits: ContextDev::Models::BatchRetrieveResponse::Credits::OrHash,
-          error: T.nilable(ContextDev::Error::OrHash),
-          errors: T::Array[ContextDev::ErrorCount::OrHash],
-          input: ContextDev::Models::BatchRetrieveResponse::Input::OrHash,
+          failure: T.nilable(ContextDev::Failure::OrHash),
+          format_: ContextDev::Models::BatchRetrieveResponse::Format::OrSymbol,
+          input: ContextDev::Intake::OrHash,
           invalid_urls:
             T::Array[
               ContextDev::Models::BatchRetrieveResponse::InvalidURL::OrHash
             ],
           mode: ContextDev::Models::BatchRetrieveResponse::Mode::OrSymbol,
+          page_errors: T::Array[ContextDev::PageErrorCount::OrHash],
           progress: ContextDev::Models::BatchRetrieveResponse::Progress::OrHash,
           results:
             T.nilable(
@@ -157,43 +159,45 @@ module ContextDev
           status: ContextDev::Models::BatchRetrieveResponse::Status::OrSymbol,
           tags: T::Array[String],
           timing: ContextDev::Models::BatchRetrieveResponse::Timing::OrHash,
-          type: ContextDev::Models::BatchRetrieveResponse::Type::OrSymbol,
           key_metadata:
-            ContextDev::Models::BatchRetrieveResponse::KeyMetadata::OrHash,
-          webhook_secret: String
+            ContextDev::Models::BatchRetrieveResponse::KeyMetadata::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
         # Batch ID used to retrieve or cancel the job.
         id:,
-        # Reserved and used credits.
+        # The crawl controls as submitted, so the limits requested can be compared against
+        # what the crawl reached.
+        crawl:,
+        # What this batch has done to your credit balance.
         credits:,
-        # Why the batch failed.
-        error:,
-        # Page failures grouped by error code.
-        errors:,
-        # Submission counts.
+        # A failure of the batch as a whole, distinct from the per-page failures in
+        # `page_errors`.
+        failure:,
+        # What each page is returned as. Matches `input.data.format` on the submit
+        # request.
+        format_:,
+        # What submission took in, and what it charged for.
         input:,
         # Rejected URLs, up to 100. These are not charged.
         invalid_urls:,
-        # How pages are selected.
+        # How pages were selected. Matches `input.mode` on the submit request.
         mode:,
-        # Current processing counts. Use `status` to check completion.
+        # Individual page failures grouped by error code, sorted by count. Unrelated to
+        # `failure`, which is the batch itself failing.
+        page_errors:,
+        # Pages attempted so far. Use `status` to check completion.
         progress:,
-        # Download links available when the batch finishes. GET /batch/{batch_id}/results
-        # serves the same records as paginated JSON.
+        # Download links, available once the batch reaches a final status and null before
+        # then. GET /batch/{batch_id}/results serves the same records as paginated JSON.
         results:,
         # Current state. `completed`, `cancelled`, and `failed` are final.
         status:,
         # Tags stored on the batch at submission.
         tags:,
         timing:,
-        # Output format.
-        type:,
         # API key usage for this request.
-        key_metadata: nil,
-        # Webhook signing secret. Also returned by GET /batch/{batch_id}.
-        webhook_secret: nil
+        key_metadata: nil
       )
       end
 
@@ -201,13 +205,16 @@ module ContextDev
         override.returns(
           {
             id: String,
+            crawl: T.nilable(ContextDev::CrawlControls),
             credits: ContextDev::Models::BatchRetrieveResponse::Credits,
-            error: T.nilable(ContextDev::Error),
-            errors: T::Array[ContextDev::ErrorCount],
-            input: ContextDev::Models::BatchRetrieveResponse::Input,
+            failure: T.nilable(ContextDev::Failure),
+            format_:
+              ContextDev::Models::BatchRetrieveResponse::Format::TaggedSymbol,
+            input: ContextDev::Intake,
             invalid_urls:
               T::Array[ContextDev::Models::BatchRetrieveResponse::InvalidURL],
             mode: ContextDev::Models::BatchRetrieveResponse::Mode::TaggedSymbol,
+            page_errors: T::Array[ContextDev::PageErrorCount],
             progress: ContextDev::Models::BatchRetrieveResponse::Progress,
             results:
               T.nilable(ContextDev::Models::BatchRetrieveResponse::Results),
@@ -215,10 +222,7 @@ module ContextDev
               ContextDev::Models::BatchRetrieveResponse::Status::TaggedSymbol,
             tags: T::Array[String],
             timing: ContextDev::Models::BatchRetrieveResponse::Timing,
-            type: ContextDev::Models::BatchRetrieveResponse::Type::TaggedSymbol,
-            key_metadata:
-              ContextDev::Models::BatchRetrieveResponse::KeyMetadata,
-            webhook_secret: String
+            key_metadata: ContextDev::Models::BatchRetrieveResponse::KeyMetadata
           }
         )
       end
@@ -234,88 +238,79 @@ module ContextDev
             )
           end
 
-        # Credits used by successful pages.
+        # `reserved` minus `refunded` — what the batch has cost so far. Equal to
+        # `reserved` until the batch settles.
         sig { returns(Integer) }
-        attr_accessor :charged
+        attr_accessor :net
 
-        # Credits reserved when the batch was accepted.
+        # Credits returned for pages that did not succeed. Stays 0 until the batch reaches
+        # a final status, then settles in one movement.
         sig { returns(Integer) }
-        attr_accessor :estimated
+        attr_accessor :refunded
 
-        # Reserved and used credits.
+        # Credits debited from your balance the moment the batch was accepted. This is a
+        # charge, not a forecast — the whole amount leaves the balance up front.
+        sig { returns(Integer) }
+        attr_accessor :reserved
+
+        # What this batch has done to your credit balance.
         sig do
-          params(charged: Integer, estimated: Integer).returns(T.attached_class)
+          params(net: Integer, refunded: Integer, reserved: Integer).returns(
+            T.attached_class
+          )
         end
         def self.new(
-          # Credits used by successful pages.
-          charged:,
-          # Credits reserved when the batch was accepted.
-          estimated:
+          # `reserved` minus `refunded` — what the batch has cost so far. Equal to
+          # `reserved` until the batch settles.
+          net:,
+          # Credits returned for pages that did not succeed. Stays 0 until the batch reaches
+          # a final status, then settles in one movement.
+          refunded:,
+          # Credits debited from your balance the moment the batch was accepted. This is a
+          # charge, not a forecast — the whole amount leaves the balance up front.
+          reserved:
         )
         end
 
-        sig { override.returns({ charged: Integer, estimated: Integer }) }
+        sig do
+          override.returns(
+            { net: Integer, refunded: Integer, reserved: Integer }
+          )
+        end
         def to_hash
         end
       end
 
-      class Input < ContextDev::Internal::Type::BaseModel
-        OrHash =
+      # What each page is returned as. Matches `input.data.format` on the submit
+      # request.
+      module Format
+        extend ContextDev::Internal::Type::Enum
+
+        TaggedSymbol =
           T.type_alias do
-            T.any(
-              ContextDev::Models::BatchRetrieveResponse::Input,
-              ContextDev::Internal::AnyHash
-            )
+            T.all(Symbol, ContextDev::Models::BatchRetrieveResponse::Format)
           end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
 
-        # Pages accepted, or the crawl page limit. Credits are reserved for this count.
-        sig { returns(Integer) }
-        attr_accessor :accepted
-
-        # Duplicate URL and `itemId` pairs skipped. Always 0 for crawls.
-        sig { returns(Integer) }
-        attr_accessor :duplicates
-
-        # Pages rejected during validation.
-        sig { returns(Integer) }
-        attr_accessor :invalid
-
-        # Pages submitted before validation. For a crawl, the page limit.
-        sig { returns(Integer) }
-        attr_accessor :submitted
-
-        # Submission counts.
-        sig do
-          params(
-            accepted: Integer,
-            duplicates: Integer,
-            invalid: Integer,
-            submitted: Integer
-          ).returns(T.attached_class)
-        end
-        def self.new(
-          # Pages accepted, or the crawl page limit. Credits are reserved for this count.
-          accepted:,
-          # Duplicate URL and `itemId` pairs skipped. Always 0 for crawls.
-          duplicates:,
-          # Pages rejected during validation.
-          invalid:,
-          # Pages submitted before validation. For a crawl, the page limit.
-          submitted:
-        )
-        end
+        MARKDOWN =
+          T.let(
+            :markdown,
+            ContextDev::Models::BatchRetrieveResponse::Format::TaggedSymbol
+          )
+        HTML =
+          T.let(
+            :html,
+            ContextDev::Models::BatchRetrieveResponse::Format::TaggedSymbol
+          )
 
         sig do
           override.returns(
-            {
-              accepted: Integer,
-              duplicates: Integer,
-              invalid: Integer,
-              submitted: Integer
-            }
+            T::Array[
+              ContextDev::Models::BatchRetrieveResponse::Format::TaggedSymbol
+            ]
           )
         end
-        def to_hash
+        def self.values
         end
       end
 
@@ -350,7 +345,7 @@ module ContextDev
         end
       end
 
-      # How pages are selected.
+      # How pages were selected. Matches `input.mode` on the submit request.
       module Mode
         extend ContextDev::Internal::Type::Enum
 
@@ -395,8 +390,9 @@ module ContextDev
         sig { returns(Integer) }
         attr_accessor :failed
 
-        # Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can
-        # finish under its page limit when the site has no more reachable pages.
+        # Reserved pages not yet attempted. A cancelled batch keeps reporting the URLs it
+        # never reached; a crawl whose `input.reserved_is_ceiling` is true reports 0 once
+        # final, because its unspent budget was never real pages.
         sig { returns(Integer) }
         attr_accessor :pending
 
@@ -404,7 +400,7 @@ module ContextDev
         sig { returns(Integer) }
         attr_accessor :succeeded
 
-        # Current processing counts. Use `status` to check completion.
+        # Pages attempted so far. Use `status` to check completion.
         sig do
           params(failed: Integer, pending: Integer, succeeded: Integer).returns(
             T.attached_class
@@ -413,8 +409,9 @@ module ContextDev
         def self.new(
           # Pages that could not be scraped.
           failed:,
-          # Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can
-          # finish under its page limit when the site has no more reachable pages.
+          # Reserved pages not yet attempted. A cancelled batch keeps reporting the URLs it
+          # never reached; a crawl whose `input.reserved_is_ceiling` is true reports 0 once
+          # final, because its unspent budget was never real pages.
           pending:,
           # Pages scraped successfully.
           succeeded:
@@ -451,8 +448,8 @@ module ContextDev
         end
         attr_accessor :files
 
-        # Download links available when the batch finishes. GET /batch/{batch_id}/results
-        # serves the same records as paginated JSON.
+        # Download links, available once the batch reaches a final status and null before
+        # then. GET /batch/{batch_id}/results serves the same records as paginated JSON.
         sig do
           params(
             expires_at: String,
@@ -631,38 +628,6 @@ module ContextDev
         end
       end
 
-      # Output format.
-      module Type
-        extend ContextDev::Internal::Type::Enum
-
-        TaggedSymbol =
-          T.type_alias do
-            T.all(Symbol, ContextDev::Models::BatchRetrieveResponse::Type)
-          end
-        OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-        MARKDOWN =
-          T.let(
-            :markdown,
-            ContextDev::Models::BatchRetrieveResponse::Type::TaggedSymbol
-          )
-        HTML =
-          T.let(
-            :html,
-            ContextDev::Models::BatchRetrieveResponse::Type::TaggedSymbol
-          )
-
-        sig do
-          override.returns(
-            T::Array[
-              ContextDev::Models::BatchRetrieveResponse::Type::TaggedSymbol
-            ]
-          )
-        end
-        def self.values
-        end
-      end
-
       class KeyMetadata < ContextDev::Internal::Type::BaseModel
         OrHash =
           T.type_alias do