weft-sdk 0.7.0 → 0.9.1

data/docs/PurchaseArtifact.md

@@ -0,0 +1,23 @@
+# Weft::PurchaseArtifact
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **id** | **Integer** |  |  |
+| **merchant_url** | **String** |  |  |
+| **bytes** | **Integer** |  |  |
+| **mime** | **String** |  |  |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::PurchaseArtifact.new(
+  id: null,
+  merchant_url: null,
+  bytes: null,
+  mime: null
+)
+```

data/docs/PurchaseListResponse.md

@@ -0,0 +1,19 @@
+# Weft::PurchaseListResponse
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **data** | [**Array<Purchase>**](Purchase.md) |  |  |
+| **pagination** | [**Pagination**](Pagination.md) |  |  |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::PurchaseListResponse.new(
+  data: null,
+  pagination: null
+)
+```

data/docs/PurchaseResponse.md

@@ -0,0 +1,17 @@
+# Weft::PurchaseResponse
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **data** | [**Purchase**](Purchase.md) |  |  |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::PurchaseResponse.new(
+  data: null
+)
+```

data/docs/PurchasesApi.md

@@ -0,0 +1,148 @@
+# Weft::PurchasesApi
+
+All URIs are relative to *https://weft.network*
+
+| Method | HTTP request | Description |
+| ------ | ------------ | ----------- |
+| [**get_purchase**](PurchasesApi.md#get_purchase) | **GET** /api/v1/purchases/{id} | Get a buyer purchase |
+| [**list_purchases**](PurchasesApi.md#list_purchases) | **GET** /api/v1/purchases | List buyer purchases |
+
+
+## get_purchase
+
+> <PurchaseResponse> get_purchase(id)
+
+Get a buyer purchase
+
+### Examples
+
+```ruby
+require 'time'
+require 'weft-sdk'
+# setup authorization
+Weft.configure do |config|
+  # Configure Bearer authorization (APIKey): bearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = Weft::PurchasesApi.new
+id = 56 # Integer | Purchase ID
+
+begin
+  # Get a buyer purchase
+  result = api_instance.get_purchase(id)
+  p result
+rescue Weft::ApiError => e
+  puts "Error when calling PurchasesApi->get_purchase: #{e}"
+end
+```
+
+#### Using the get_purchase_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<PurchaseResponse>, Integer, Hash)> get_purchase_with_http_info(id)
+
+```ruby
+begin
+  # Get a buyer purchase
+  data, status_code, headers = api_instance.get_purchase_with_http_info(id)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <PurchaseResponse>
+rescue Weft::ApiError => e
+  puts "Error when calling PurchasesApi->get_purchase_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **id** | **Integer** | Purchase ID |  |
+
+### Return type
+
+[**PurchaseResponse**](PurchaseResponse.md)
+
+### Authorization
+
+[bearerAuth](../README.md#bearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+
+## list_purchases
+
+> <PurchaseListResponse> list_purchases(opts)
+
+List buyer purchases
+
+Returns the authenticated buyer's signing and settlement ledger. Unlike `/api/v1/payments`, this endpoint is User-scoped and backed by `signed_events`, so rejected and pending attempts are included.  Scoped to the buyer's own merchant spend, matching the dashboard's Purchases page. Internal signings are excluded: the Tempo refill self-transfer (`rebalance`) and operator signings (`manual`) are not payments the buyer made and never appear here.
+
+### Examples
+
+```ruby
+require 'time'
+require 'weft-sdk'
+# setup authorization
+Weft.configure do |config|
+  # Configure Bearer authorization (APIKey): bearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = Weft::PurchasesApi.new
+opts = {
+  page: 56, # Integer | Page number
+  per_page: 56 # Integer | Items per page
+}
+
+begin
+  # List buyer purchases
+  result = api_instance.list_purchases(opts)
+  p result
+rescue Weft::ApiError => e
+  puts "Error when calling PurchasesApi->list_purchases: #{e}"
+end
+```
+
+#### Using the list_purchases_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<PurchaseListResponse>, Integer, Hash)> list_purchases_with_http_info(opts)
+
+```ruby
+begin
+  # List buyer purchases
+  data, status_code, headers = api_instance.list_purchases_with_http_info(opts)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <PurchaseListResponse>
+rescue Weft::ApiError => e
+  puts "Error when calling PurchasesApi->list_purchases_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **page** | **Integer** | Page number | [optional][default to 1] |
+| **per_page** | **Integer** | Items per page | [optional][default to 25] |
+
+### Return type
+
+[**PurchaseListResponse**](PurchaseListResponse.md)
+
+### Authorization
+
+[bearerAuth](../README.md#bearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json

data/docs/ResendConfirmationRequest.md

@@ -15,4 +15,3 @@ instance = Weft::ResendConfirmationRequest.new(
   email: null
 )
 ```
-

data/docs/ResourceEnrollmentRequest.md

@@ -21,4 +21,3 @@ instance = Weft::ResourceEnrollmentRequest.new(
   wallet_address: null
 )
 ```
-

data/docs/ResourceEnrollmentResponse.md

@@ -15,4 +15,3 @@ instance = Weft::ResourceEnrollmentResponse.new(
   data: null
 )
 ```
-

data/docs/ResourceStats.md

@@ -27,4 +27,3 @@ instance = Weft::ResourceStats.new(
   last_active: null
 )
 ```
-

data/docs/ResourcesApi.md

@@ -13,7 +13,7 @@ All URIs are relative to *https://weft.network*
 
 Self-enroll a ghost resource (public, no auth)
 
-Lets an unauthenticated agent (or its operator) self-enroll a Resource as a \"ghost\" (no owning provider). The server generates the `slug` and a single-use `claim_token`; the response also carries a `claim_url` the agent hands to its human controller to claim the resource from the dashboard.  Client-supplied `slug` and `category` are silently ignored: slugs are server-generated from `name` (so callers cannot squat on reserved names), and `category` is a post-claim concern set by a real human.  Rate-limited to 10 enrollments/hour/IP. 
+Lets an unauthenticated agent (or its operator) self-enroll a Resource as a \"ghost\" (no owning provider). The server generates the `slug` and a single-use `claim_token`; the response also carries a `claim_url` the agent hands to its human controller to claim the resource from the dashboard.  Client-supplied `slug` and `category` are silently ignored: slugs are server-generated from `name` (so callers cannot squat on reserved names), and `category` is a post-claim concern set by a real human.  Rate-limited to 10 enrollments/hour/IP.
 
 ### Examples
 
@@ -22,7 +22,7 @@ require 'time'
 require 'weft-sdk'
 
 api_instance = Weft::ResourcesApi.new
-resource_enrollment_request = Weft::ResourceEnrollmentRequest.new({kind: 'agent', name: 'Self-Enrolled Bot'}) # ResourceEnrollmentRequest | 
+resource_enrollment_request = Weft::ResourceEnrollmentRequest.new({kind: 'agent', name: 'Self-Enrolled Bot'}) # ResourceEnrollmentRequest |
 
 begin
   # Self-enroll a ghost resource (public, no auth)
@@ -69,4 +69,3 @@ No authorization required
 
 - **Content-Type**: application/json
 - **Accept**: application/json
-

data/docs/SearchApi.md

@@ -13,7 +13,7 @@ All URIs are relative to *https://weft.network*
 
 Search the Weft index
 
-Semantic search over the Weft index of paid agent resources. The request body carries a free-text `query`, an optional `limit`, and an optional `filters` object that narrows by price band, payment protocol, agent protocol, or domain tag. Filters are applied as a post-filter after the embedding score is computed.  Backend selection is server-side via the `SEARCH_BACKEND` env var: `mock` (default, reads YAML fixtures and sets `_mock: true` in the response) or `platform` (proxies to the upstream search service). Both backends return the same envelope.  Account-scoped: the bearer token must be a buyer-scoped API key. Free for authenticated buyers in v1; billing is planned for a later release.  Response negotiation: `Accept: application/json` (default) returns the structured envelope; `Accept: text/markdown` returns a rendered Markdown digest of the same results — useful for piping into a chat UI or LLM prompt. 
+Semantic search over the Weft index of paid agent resources. The request body is the weft-search-platform `/v1/search` contract: a free-text `query`, optional `max_results`, and optional structured `filters` (price / price_atomic / type / protocol — the canonical FilterSpec v1 vocabulary, vendored verbatim from the platform). Price is a dual representation of one constraint: `price` in USD decimal strings (the reasoning form) XOR `price_atomic` in integer micro-USD (the settlement form) — mutually exclusive, set at most one.  Backend selection is server-side via the `SEARCH_BACKEND` env var: `mock` (default, reads YAML fixtures and sets `_mock: true` in the response) or `platform` (proxies to the upstream search service). Both backends return the platform `SearchResponse` envelope.  Account-scoped: the bearer token must be a buyer-scoped API key. Free for authenticated buyers in v1; billing is planned for a later release.  Response negotiation: `Accept: application/json` (default) returns the structured envelope; `Accept: text/markdown` returns a rendered Markdown digest of the same results — useful for piping into a chat UI or LLM prompt.
 
 ### Examples
 
@@ -27,7 +27,7 @@ Weft.configure do |config|
 end
 
 api_instance = Weft::SearchApi.new
-search_request = Weft::SearchRequest.new({query: 'send email from an agent'}) # SearchRequest | 
+search_request = Weft::SearchRequest.new({query: 'send email from an agent'}) # SearchRequest |
 
 begin
   # Search the Weft index
@@ -74,4 +74,3 @@ end
 
 - **Content-Type**: application/json
 - **Accept**: application/json, text/markdown
-

data/docs/SearchCapabilityRef.md

@@ -0,0 +1,19 @@
+# Weft::SearchCapabilityRef
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **capability_id** | **String** |  | [optional] |
+| **capability_type** | **String** |  | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchCapabilityRef.new(
+  capability_id: null,
+  capability_type: null
+)
+```

data/docs/SearchEndpointCall.md

@@ -0,0 +1,23 @@
+# Weft::SearchEndpointCall
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **method** | **String** | The HTTP verb to send. Empty string when neither the index nor the provider's own 402 challenge / OpenAPI spec declares one.  | [optional] |
+| **input_schema** | **Object** | The provider's OWN structured declaration of the arguments this endpoint takes — the machine-usable form of what `usage_instructions` states in prose. Null when the provider declares nothing.  | [optional] |
+| **example_request** | **Object** | A worked set of arguments grouped by slot (`query` / `body` / `path`). Every value is one the PROVIDER published; never synthesized.  | [optional] |
+| **example_response** | **Object** |  | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchEndpointCall.new(
+  method: null,
+  input_schema: null,
+  example_request: null,
+  example_response: null
+)
+```

data/docs/SearchEndpointHit.md

@@ -0,0 +1,41 @@
+# Weft::SearchEndpointHit
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **endpoint_id** | **String** |  | [optional] |
+| **url** | **String** |  | [optional] |
+| **resource_type** | **String** |  | [optional] |
+| **primary_protocol** | **String** |  | [optional] |
+| **call** | [**SearchEndpointCall**](SearchEndpointCall.md) |  | [optional] |
+| **price** | [**SearchEndpointPrice**](SearchEndpointPrice.md) |  | [optional] |
+| **payment** | [**Array<SearchPaymentOffer>**](SearchPaymentOffer.md) | The settlement routes this endpoint's own 402 challenge published — one entry per rail × network × asset × payee it accepts. Sibling of `call`: that block says how to shape the request, this says how to pay for it, so a caller can settle with its OWN x402/mpp SDK instead of guessing. A list because rails are irreducibly plural. Order is the provider's own preference order. Honest-empty when the pipeline observed no challenge.  | [optional] |
+| **operator_type** | **String** | Who you are actually paying. `first_party` = operated by the provider that makes the capability; `reseller` = resold, so the price carries someone else's margin. Null until the platform resolves the operator.  | [optional] |
+| **operated_by_id** | **String** |  | [optional] |
+| **settled_via_facilitator_id** | **String** |  | [optional] |
+| **settlements** | **Integer** | Count of payments observed settling against this endpoint by ANYONE (chain-indexed), not just by Weft — the reliability signal a caller can act on. Null when unknown.  | [optional] |
+| **last_verified_at** | **Time** | When Weft last CONFIRMED this endpoint answers — the most recent conclusive probe. Null when never probed, or when the latest probe errored: an endpoint we last failed to reach has no current verification.  | [optional] |
+| **latency_p50_ms** | **Integer** | Median time-to-first-byte in ms across the endpoint's probe call set. First-byte latency, not full-response time. Null when unmeasured (never 0).  | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchEndpointHit.new(
+  endpoint_id: null,
+  url: null,
+  resource_type: null,
+  primary_protocol: null,
+  call: null,
+  price: null,
+  payment: null,
+  operator_type: null,
+  operated_by_id: null,
+  settled_via_facilitator_id: null,
+  settlements: null,
+  last_verified_at: null,
+  latency_p50_ms: null
+)
+```

data/docs/SearchEndpointPrice.md

@@ -0,0 +1,25 @@
+# Weft::SearchEndpointPrice
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **indexed_usd** | **String** | The indexed price in USD as a decimal string (e.g. \"0.008\") — the dollar value people and agents reason in. A decimal string, never a float; trailing zeros trimmed. Null when unpriced.  | [optional] |
+| **atomic** | **Integer** | The same price in integer micro-USD — the settlement grain, exact. Null exactly when `indexed_usd` is. Use this for settlement.  | [optional] |
+| **source** | **String** | Where the amount came from. `probe` = observed live in the endpoint's own 402 payment-required challenge — an observation, the strongest evidence we hold. `inferred` = derived from a spec (OpenAPI) or a resale edge by the extraction pipeline, so it can lag a provider's re-pricing. Null when the endpoint carries no price.  | [optional] |
+| **last_observed_at** | **Time** | When the amount was observed. Null when unrecorded. | [optional] |
+| **live_verified** | **Boolean** | Whether this amount was confirmed against a live 402 challenge for THIS response. Search does not issue a payment-required probe at query time, so this is `false` today — treat an unflagged price as indexed, not verified.  | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchEndpointPrice.new(
+  indexed_usd: null,
+  atomic: null,
+  source: null,
+  last_observed_at: null,
+  live_verified: null
+)
+```

data/docs/SearchErrorResponse.md

@@ -17,4 +17,3 @@ instance = Weft::SearchErrorResponse.new(
   details: null
 )
 ```
-

data/docs/SearchFilterSpec.md

@@ -0,0 +1,23 @@
+# Weft::SearchFilterSpec
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **price** | [**SearchPriceUsdFilter**](SearchPriceUsdFilter.md) |  | [optional] |
+| **price_atomic** | [**SearchPriceAtomicFilter**](SearchPriceAtomicFilter.md) |  | [optional] |
+| **type** | [**SearchResourceTypeFilter**](SearchResourceTypeFilter.md) |  | [optional] |
+| **protocol** | [**SearchProtocolFilter**](SearchProtocolFilter.md) |  | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchFilterSpec.new(
+  price: null,
+  price_atomic: null,
+  type: null,
+  protocol: null
+)
+```

data/docs/SearchPaymentOffer.md

@@ -0,0 +1,31 @@
+# Weft::SearchPaymentOffer
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **protocol** | **String** | The payment rail (e.g. `x402`, `mpp`). |  |
+| **scheme** | **String** |  | [optional] |
+| **network** | **String** |  | [optional] |
+| **asset** | **String** |  | [optional] |
+| **amount** | **String** |  | [optional] |
+| **pay_to** | **String** |  | [optional] |
+| **max_timeout_seconds** | **Integer** |  | [optional] |
+| **facilitator** | **String** |  | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchPaymentOffer.new(
+  protocol: null,
+  scheme: null,
+  network: null,
+  asset: null,
+  amount: null,
+  pay_to: null,
+  max_timeout_seconds: null,
+  facilitator: null
+)
+```

data/docs/SearchPriceAtomicFilter.md

@@ -0,0 +1,25 @@
+# Weft::SearchPriceAtomicFilter
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **lte** | **Integer** | Price ≤ this many micro-USD (inclusive ceiling). | [optional] |
+| **gte** | **Integer** | Price ≥ this many micro-USD (inclusive floor). | [optional] |
+| **eq** | **Integer** | Price exactly this many micro-USD. | [optional] |
+| **range_gte** | **Integer** | Range lower bound (inclusive), micro-USD. Set with range_lte. | [optional] |
+| **range_lte** | **Integer** | Range upper bound (inclusive), micro-USD. Set with range_gte. | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchPriceAtomicFilter.new(
+  lte: null,
+  gte: null,
+  eq: null,
+  range_gte: null,
+  range_lte: null
+)
+```

data/docs/SearchPriceUsdFilter.md

@@ -0,0 +1,25 @@
+# Weft::SearchPriceUsdFilter
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **lte** | **String** | Price ≤ this many USD (inclusive ceiling), e.g. \"0.009\". | [optional] |
+| **gte** | **String** | Price ≥ this many USD (inclusive floor), e.g. \"0.001\". | [optional] |
+| **eq** | **String** | Price exactly this many USD, e.g. \"1.5\". | [optional] |
+| **range_gte** | **String** | Range lower bound (inclusive), USD. Set with range_lte. | [optional] |
+| **range_lte** | **String** | Range upper bound (inclusive), USD. Set with range_gte. | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchPriceUsdFilter.new(
+  lte: null,
+  gte: null,
+  eq: null,
+  range_gte: null,
+  range_lte: null
+)
+```

data/docs/SearchProtocolFilter.md

@@ -0,0 +1,19 @@
+# Weft::SearchProtocolFilter
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **eq** | **String** | Primary protocol is exactly this value. | [optional] |
+| **_in** | **Array<String>** | Primary protocol is one of these values. | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchProtocolFilter.new(
+  eq: null,
+  _in: null
+)
+```

data/docs/SearchProviderRef.md

@@ -0,0 +1,21 @@
+# Weft::SearchProviderRef
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **provider_id** | **String** |  | [optional] |
+| **display_name** | **String** |  | [optional] |
+| **origin_domains** | **Array<String>** |  | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchProviderRef.new(
+  provider_id: null,
+  display_name: null,
+  origin_domains: null
+)
+```

data/docs/SearchRequest.md

@@ -5,8 +5,8 @@
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
 | **query** | **String** | Free-text query. Required and non-empty. |  |
-| **limit** | **Integer** | Max number of hits to return. Clamped to [1, 50]. | [optional][default to 10] |
-| **filters** | [**SearchFilters**](SearchFilters.md) |  | [optional] |
+| **max_results** | **Integer** | Max number of hits to return. Invalid values are rejected, not clamped. | [optional][default to 10] |
+| **filters** | [**SearchFilterSpec**](SearchFilterSpec.md) |  | [optional] |
 
 ## Example
 
@@ -15,8 +15,7 @@ require 'weft-sdk'
 
 instance = Weft::SearchRequest.new(
   query: send email from an agent,
-  limit: null,
+  max_results: null,
   filters: null
 )
 ```
-

data/docs/SearchResourceTypeFilter.md

@@ -0,0 +1,19 @@
+# Weft::SearchResourceTypeFilter
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **eq** | **String** | Resource type is exactly this value. | [optional] |
+| **_in** | **Array<String>** | Resource type is one of these values. | [optional] |
+
+## Example
+
+```ruby
+require 'weft-sdk'
+
+instance = Weft::SearchResourceTypeFilter.new(
+  eq: null,
+  _in: null
+)
+```

data/docs/SearchResponse.md

@@ -4,10 +4,24 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
-| **results** | [**Array<SearchResponseResultsInner>**](SearchResponseResultsInner.md) |  |  |
-| **paid_usd** | **String** | Always `null` in v1. | [optional] |
-| **tx_hash** | **String** | Always `null` in v1. | [optional] |
-| **artifact_id** | **String** | Always `null` in v1. | [optional] |
+| **query_trace_id** | **String** | Opaque trace id for the served query, matching the platform `query_trace_id` — and the `search_id` that re-reads it. Deliberately the same id rather than a second handle: one serve, one name.  |  |
+| **query** | **String** |  |  |
+| **format** | **String** | Which view this response carries, echoing the requested format. `json` populates `results` and leaves `markdown` null; `markdown` populates `markdown` and leaves `results` empty. Exactly one is populated per response, never both — returning both eagerly would double the payload.  | [optional] |
+| **markdown** | **String** | The flat comparison table, when `format` is `markdown`; null otherwise. Rendered deterministically from the same stored result the `json` view returns, so the two views of one search can never disagree.  | [optional] |
+| **result_count** | **Integer** | How many `(Provider + Capability)` results the search produced. Read THIS, not `results.length`, for the count: on a `markdown` response `results` is empty by design, so `result_count > 0` with an empty `results` is a rendered table while `result_count == 0` is a genuine zero-result.  | [optional] |
+| **served_from** | **String** | `live` for a fresh serve; `snapshot` for an immutable replay of a completed search. A re-read is a snapshot and says so — read it with `as_of` and `stale`.  | [optional] |
+| **as_of** | **Time** | When the results were produced. Now on a `live` serve; on a `snapshot` the ORIGINAL serve time, because a replay returns exactly what was paid for, not current truth.  | [optional] |
+| **stale** | **Boolean** | Whether the active search index has changed since these results were produced. `true` does not mean the results are wrong — it means they are a snapshot of an index that has since moved. Always `false` on a `live` serve.  | [optional] |
+| **payment_note** | **String** | How payment works across the catalog, stated once for the whole response rather than repeated in every endpoint's usage instructions.  | [optional] |
+| **applied_filters** | [**SearchFilterSpec**](SearchFilterSpec.md) | The `FilterSpec` actually applied to recall, echoed back so the caller sees exactly what constrained the results. In the current contract this is the caller's `filters` verbatim (empty object when none were sent).  | [optional] |
+| **decomposition_source** | **String** | Origin of `applied_filters`; always `CALLER`. | [optional] |
+| **embedder_model** | **String** |  |  |
+| **candidates_considered** | **Integer** |  |  |
+| **warnings** | [**Array<SearchResponseWarningsInner>**](SearchResponseWarningsInner.md) |  |  |
+| **match_quality** | **String** | Calibrated confidence in this result set — read this instead of thresholding a raw similarity score. `strong`: the top match is confidently on-intent, proceed. `weak`: above the relevance floor but inside the band where plausible-but-wrong matches live, verify the result before paying. `none`: nothing cleared the floor — `results` is empty and `reason` / `suggestion` say why. Results below the floor are never returned as near-misses.  | [optional][default to 'none'] |
+| **reason** | **String** | Machine-readable cause of an empty result set, non-null exactly when `match_quality` is `none`. `below_relevance_floor`: candidates ranked but the best scored under the floor. `filter_collapsed_pool`: a caller filter cut the pool before ranking and nothing relevant survived — relax the filter. `no_catalog_coverage`: recall returned no candidates at all on an unfiltered query. `unsupported_filter_value`: a CATEGORICAL filter value (`type` / `protocol`) matches zero stored values, so it could never have matched — categorical only, since a continuous bound like `price` that matches nothing is reported as `filter_collapsed_pool` instead (the bound needs raising, the dimension is not unsupported). `index_unavailable`: no active index — an operational fault, paired with the `EMPTY_INDEX` warning.  | [optional] |
+| **suggestion** | **String** | Human/agent-readable explanation of `reason`, carrying the concrete numbers behind it (pool sizes, the best discarded score against the floor, the values actually stored for a filter). Non-null exactly when `reason` is.  | [optional] |
+| **results** | [**Array<SearchResult>**](SearchResult.md) | Ranked `(Provider + Capability)` results; empty when the index is empty or nothing cleared the relevance floor. Results BELOW the floor are never returned — an empty list plus a `reason` is the honest answer, not a list of near-misses in the same shape as a genuine match.  |  |
 | **_mock** | **Boolean** | Present and `true` only when served by the mock backend. | [optional] |
 
 ## Example
@@ -16,11 +30,24 @@
 require 'weft-sdk'
 
 instance = Weft::SearchResponse.new(
+  query_trace_id: null,
+  query: null,
+  format: null,
+  markdown: null,
+  result_count: null,
+  served_from: null,
+  as_of: null,
+  stale: null,
+  payment_note: null,
+  applied_filters: null,
+  decomposition_source: null,
+  embedder_model: null,
+  candidates_considered: null,
+  warnings: null,
+  match_quality: null,
+  reason: null,
+  suggestion: null,
   results: null,
-  paid_usd: null,
-  tx_hash: null,
-  artifact_id: null,
   _mock: null
 )
 ```
-